title: "PuppetDB 2.0 » API » Report Wire Format, Version 3"
layout: default
canonical: "/puppetdb/latest/api/wire_format/report_format_v3.html"
---

[api]: ../index.html

## Report interchange format

A report is represented as JSON (this implies UTF-8 encoding). Unless
otherwise noted, `null` is not allowed anywhere in the report.

    {
        "certname": <string>,
        "environment": <string>,
        "puppet-version": <string>,
        "report-format": <int>,
        "configuration-version": <string>,
        "start-time": <datetime>,
        "end-time": <datetime>,
        "resource-events": [<resource-event>, <resource-event>, ...],
        "transaction-uuid": <string>
    }

All keys are mandatory unless otherwise noted, though values that are lists may be empty lists.

`"certname"` is the certname the report is associated with.

`"report"` is the environment associated to the node at the time of the report

`"puppet-version"` is the version of puppet that was run to generate this report.

`"report-format"` is the version number of the report format that puppet used
to generate the original report data.  This is a constant defined by puppet.

`"configuration-version"` is an identifier string that puppet uses to match a
specific catalog for a node to a specific puppet run.  This value is
generated by puppet.

`"start-time"` is the time at which the puppet run began; see more details about
the `datetime` format below.

`"end-time"` is the time at which the puppet run completed; see more details about
the `datetime` format below.

`"transaction-uuid"` is a string used to identify a puppet run.  It can be used to
match a report with the catalog that was used for the run.  This field may be `null`.

### Encoding

The entire report is expected to be valid JSON, which implies UTF-8
encoding.

### Data type: `<string>`

A JSON string. By virtue of the report being UTF-8, these must also
be UTF-8.

### Data type: `<integer>`

A JSON int.

### Data type: `<datetime>`

A JSON string representing a date and time (with time zone), formatted based on
the recommendations in ISO8601; so, e.g., for a UTC time, the String would be
formatted as `YYYY-MM-DDThh:mm:ss.sssZ`.  For non-UTC, the `Z` may be replaced
with `±hh:mm` to represent the specific timezone.

### Data type: `<resource-event>`

A JSON Object of the following form:

    {
     "resource-type": <string>,
     "resource-title": <string>,
     "property": <string>,
     "timestamp": <datetime>,
     "status": <string>,
     "old-value": <string>,
     "new-value": <string>,
     "message": <string>,
     "file": <string>,
     "line: <integer>,
     "containment-path": [<string>, <string>, ...]
    }

All keys are required.

`"resource-type"` is the name of the puppet resource type that the event occurred on.

`"resource-title"` is the title of the puppet resource that the event occurred on.

`"property"` is the name of the property of the resource for which the event occurred.
This may be `null` only if the `status` is `skipped`.

`"timestamp"` is the date/time at which the event occurred.

`"status"` is a string representing the outcome of the event; this should be one
of `success`, `failure`, or `skipped`.

`"old-value"` is the value that puppet determined the property to have held prior
to the event.

`"new-value"` is the value that puppet was instructed to set the property to.

`"message"` is a descriptive message providing extra information about the event.
This should be `null` if `status` is `success`.

`"file"` is the manifest in which the resource is defined. This field may be `null`.

`"line"` is the line number (within `"file"`) where the resource is defined. This field may be `null`.

`"containment-path"` is a collection of strings where each string is a Puppet type or class
that represents the containment hierarchy of the resource within the catalog. This field may be `null`.

## Gaps with this wire format

1. Binary data needs to be dealt with (hopefully only for the `old-value` and
`new-value` fields.

Why a version 3 of the report wire format?
-----

[below]: #why-a-v3-report-wire-format

Prior to version 3 of the store report command, there was a single
version of the report wire format. How that wire format was
interpreted was different from one command version to another. This
approach changed in version 3 of the store report command. Beginning
with version 3, each command is tied to a the wire format version of
the same number.

###  Differences with the previous report wire format

1. A new top-level key "environment" was added
