PuppetDB receives catalogs from puppet masters in the following wire format. This format is subtly different from the internal format used by Puppet so catalogs are converted by the PuppetDB terminus plugins before they are sent. See below for the justification for this separate format.

Catalog Interchange Format


Note: This is version 4 of the catalog interchange format and has been deprecated. See [version 5][catalog_v5] for the currently supported version of this wire format.


The entire catalog is serialized as JSON, which requires strict UTF-8 encoding. Unless otherwise noted, null is not allowed anywhere in the catalog.

Main Data Type: Catalog

  "name": <string>,
  "version": <string>,
  "environment": <string>,
  "transaction-uuid": <string>,
      [<edge>, <edge>, ...],
      [<resource>, <resource>, ...]


String. The name of the node for which the catalog was compiled.


String. An arbitrary string that uniquely identifies this specific catalog across time for a single node. This is controlled by Puppet’s config_version setting and is usually the seconds elapsed since the epoch.


String. The envrionment associated to the node when the catalog was compiled.


List of <edge> objects. Every relationship between any two resources in the catalog, which may have been made with chaining arrows, metaparameters, or the require function.


  • “Autorequire” relationships are not currently encoded in the catalog.
  • This key is significantly different from its equivalent in Puppet’s internal catalog format, which only encodes containment edges.


List of <resource> objects. Contains every resource in the catalog.


String. A string used to match the catalog with the corresponding report that was issued during the same puppet run. This field may be null. (Note: support for this field was introduced in Version 3 of the “replace catalog” command. Versions prior to version 3 will populate this field with a null value.

Data Type: <string>

A JSON string. Because the catalog is UTF-8, these must also be UTF-8.

Data Type: <integer>

A JSON int.

Data Type: <boolean>

A JSON boolean.

Data Type: <edge>

A JSON object of the following form, which represents a relationship between two resources:

{"source": <resource-spec>,
 "target": <resource-spec>,
 "relationship": <relationship>}

All edges are normalized so that the “source” resource is managed before the “target” resource. To do this, the Puppet language’s “require” and “subscribe” relationship types are munged into “required-by” and “subscription-of” when they are converted into edges.

The keys of an edge are source, target, and relationship, all of which are required.


A <resource-spec>. The resource which should be managed first.


A <resource-spec>. The resource which should be managed second.


A <relationship>. The way the two resources are related.

Data Type: <resource-spec>

(Synonym: <resource-hash>.)

The JSON representation of a resource reference (single-resource kind). An object of the following form:

{"type": <string>,
 "title": <string>}

The resource named by a resource-spec must exist in the catalog’s "resources" list. Note also that the title must be the resource’s actual title, rather than an alias or name/namevar.

Data Type: <relationship>

One of the following exact strings, when used in the relationship key of an <edge> object:

  • contains
  • before
  • required-by
  • notifies
  • subscription-of

Note: Regardless of the relationship type, the “source” resource is always managed before the “target” resource. This means that, functionally speaking, required-by is a synonym of before and subscription-of is a synonym of notifies. In this catalog format, the different relationship types preserve information about the origin of the relationship.

String Relationship Type Origin of Relationship
contains containment Class or defined type containment
before ordering before metaparam on source, or -> chaining arrow
required-by ordering require metaparam on target, or require function
notifies ordering w/ notification notify metaparam on source, or ~> chaining arrow
subscription-of ordering w/ notification subscribe metaparam on target

Data Type: <resource>

A JSON object of the following form, which represents a Puppet resource:

{"type": <string>,
 "title": <string>,
 "aliases": [<string>, <string>, ...],
 "exported": <boolean>,
 "file": <string>,
 "line": <string>,
 "tags": [<string>, <string>, ...],
 "parameters": {<string>: <JSON object>,
                <string>: <JSON object>,

The eight keys in a resource object are type, title, aliases, exported, file, line, tags and parameters. All of them are required.


String. The type of the resource, capitalized. (E.g. File, Service, Class, Apache::Vhost.) Note that every segment must be capitalized if the type includes a namespace separator (::).


String. The title of the resource.


List of strings. Includes every alias for the resource, including the value of its name/namevar and any extra names added with the "alias" metaparameter.


Boolean. Whether or not this is an exported resource.


String. The manifest file in which the resource definition is located.


Positive integer. The line (of the containing manifest file) at which the resource definition can be found.


List of strings. Includes every tag the resource has. This is a normalized superset of the value of the resource’s tag attribute.


JSON object. Includes all of the resource’s attributes and their associated values. The value of an attribute may be any JSON data type, but Puppet will only provide booleans, strings, arrays, and hashes — resource references and numbers in attributes are converted to strings before being inserted into the catalog. Attributes with undef values are not added to the catalog.

Why a version 4 of the catalog wire format?

Prior to version 4 of the replace catalog command, there was a single version of the catalog wire format. How that wire format was interpreted was different from one command version to another. This approach changed in version 4 of the “replace catalog” command. Each command is tied to a the wire format version of the same number.

Differences with the previous catalog wire format

There were a number of small changes to the previous (v1) of the catalog wire format

  1. The top-level object, containing the “metadata” and “data” keys was removed. “api_version” is no longer included in the command. What was the value of “data” is now the top level object.
  2. A new top-level key “environment” was added
Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.