Skip to content

Metadata Schema

Important note on upcoming changes to the API platform

On 29th July 2026, we will be migrating our API platform to a new data source. While this should improve performance and reliability for our users, it will also include some changes which may require certain adjustments to existing integrations. Please read this documentation carefully and get in touch with us if you have any questions or concerns.

This section provides documentation for the JSON objects returned by Sherpa APIs. This is intended to be used as reference for developers while building against our APIs.

Phrases

Phrases for discrete value are included in the JSON returned by the API. The general pattern is that phrases appear in the same scope, with the same name as the field with a '_phrases' suffix. For example:

{
    "colour" : "blue",
    "colour_phrases" : [
        {
        "value" : "blue",
        "phrase" : "Blue",
        "language" : "en"
        }
    ],
    "person" : {
        "name" : "John Smith",
        "clothing" : ["tshirt", "jeans"],
        "clothing_phrases" : [
            {
            "value" : "tshirt",
            "phrase" : "T-Shirt",
            "language" : "en"
            },
            {
            "value" : "jeans",
            "phrase" : "Jeans",
            "language" : "en"
            }
        ]
    }
}

Notes:

  • Only English is currently supported, but there is scope for further language support.
  • If a field does not have an associated _phrases, then it is a text, numeric or object type.
  • Ordering of names in a JSON object is not defined. Be aware that an _phrases array may not be adjacent to its associated field.

Primary Objects

Notes:

  • For brevity, _phrase elements are omitted.
  • Preferred names and titles are generated automatically from the name and title fields to simplify objects in some contexts.
  • Empty values should not be included. If something is missing, it's probably because it's not set.

Common to all types

All types have a 'system_metadata' section with the following fields:

{
    "id": "integer: the Sherpa id of this object",
    "publicly_visible": "value("yes","no"): Is this object publicly visible?",
    "date_created": "date: the date this object was first created",
    "date_modified": "date: the date this object was last modified",
    "uri": "URL: the identity address of this object"
}

Was this helpful?

No