Data conventions

PAPI's JSON data follows these overall conventions:

  • When any response data can be singular or plural, it's always represented as an array, named items, to simplify client processing. This also applies to resources that only yield a single item.

  • Parameter names always match member names in JSON requests and responses.

  • Member names explicitly reference the type of object, for example propertyVersion rather than version.

Naming conventions

PAPI applies these JSON member naming conventions:

  • *Id members are machine-readable identifiers used for inputs to URL operations. Their values may appear with three-letter prefixes, or you can configure them not to appear. See ID prefixes.

  • *Name members are descriptive and human-readable, and never serve as URL parameter values or in any other context to key data.

  • *Date members represent timestamps in ISO 8601 format using the UTC timezone.

  • *Link members are URLs that respond to HTTP GET requests, described by a linked JSON schema document. As a convenience, any response that provides a *Link JSON member also provides the same information in the Location HTTP header. Since API hostnames are client-specific, URLs appear as absolute-path relative reference URLs, for example /papi/v1/properties rather than Clients need to establish the base URL of links from the retrieval URL. The * portion of the name serves as the link relation.

Object envelopes

Most of the API's GET data is structured within an outer envelope object, which provides additional contextual metadata about the requested object. Relevant data for most resources is available within a nested items array, even if the request yields a single record. When writing to the API, you often POST these smaller objects rather than perform a PUT on the entire data structure. For example, a GET may yield this hypothetical data structure:

    "contextualMember": true,
    "nouns": {
        "items": [
            { "nounName": "resource" }

To write new data, you'd POST only the inner object to the same URL:

{ "nounName": "endpoint" }