List paths

Reference lists are arranged into a hierarchy depending on their contents. The list is likely to expand as more data are added to the system, but for example the current hierarchy is:

  • lr
    • creditor
    • application
      • land-use
      • category
      • deed
        • type

The full path is gained by following the tree and joining with forward slashes. For example the deed type full name is "lr/application/deed/type". For practical purposes, it's best to call the API end-point to list existing paths.

Valid names

Any combination of lowercase letters and '-' joined by slashes are potentially valid names for lists, with the following caveats:

  • "schema" is a reserved word
  • Only those paths listed by the list discovery end-point are actually valid

#/ - Reference list schema

A schema for describing controlled lists

The root element here is nonsense. You wouldn't want to validate a data structure against the root schema; this schema is only intended to be used to reference the individual entities described in it.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Reference list schema",
    "id": "http://developers.ros.gov.uk/schema/ref/schema.json",
    "description": "A schema for describing controlled lists"
}

#/basic - Basic reference list

A basic list representation lists the values and labels, but no ordering is guaranteed.

{
    "title": "Basic reference list",

    "type": "object",
    "additionalProperties": {"anyOf": [
        {"type": "string"},
        {"type": "number"}
    ]}
}
{
    "A" : "High priority",
    "L": "Low priority",
    "M": "Medium priority",
    "X": "Very high priority"
}

#/detailed - Detailed reference list

In the detailed list a number of extra pieces of information are available about the list itself and each item within it.

List fields

The list metadata block must contain the name and description field, and may contain any extra items. In future extra items stored here may be overwritten with new mandatory fields. The items field contains all valid values for the list in a guaranteed order.

Item fields

Individual items have optional enabled, description and metadata fields. The enabled field will decide if the field is shown in the other representations and is assumed to be true. The metadata field is always a sub-object the keys and meaning of which are specific to the list. The values in this area will never be constrained by the API.

Metadata

Each item can have a JSON object of additional metadata. The structure of this metadata changes from list to list.

If you want to know what structure the data should have you can look at the metadata.metadataSchema field in the list which has an embedded JSON schema which describes the structure.

{
    "title": "Detailed reference list",

    "type": "object",
    "additionalProperties": false,

    "properties": {
        "metadata": {
            "type": "object",
            "properties": {
                "name": {"type" : "string"},
                "description": {"type": "string"},
                "metadataSchema": {"type": "object"}
            },
            "required": ["name", "description"]
        },

        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": false,

                "properties": {
                    "label": {"type": "string"},
                    "value": {"anyOf": [
                        {"type": "string"},
                        {"type": "number"}
                    ]},
                    "description": {"type": "string"},
                    "metadata": {
                        "type": "object"
                    },
                    "active": {
                        "type": "boolean",
                        "default": true
                    }
                },

                "required": ["label", "value"]
            }
        }

    },
    "required": ["metadata", "items"]
}
{
    "metadata": {
        "name": "Priority",
        "description": "Fictional priorities for documentation examples",

        "metadataSchema": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "type": "object",
            "additionalProperties": false,

            "properties": {
                "customValue": {
                    "type": "string"
                }
            }
        }
    },
    "items": [
        {
            "label": "Very high priority",
            "value": "X",
            "active": true,
            "metadata": {
                "customValue": "Example"
            }
        },
        {
            "label": "High priority",
            "value": "A",
            "metadata": {
                "customValue": "Example"
            }
        },
        {
            "label": "Medium priority",
            "value": "M",
            "active": true
        },
        {
            "label": "Low priority (old)",
            "value": "D",
            "active": false,
            "description": "The old priority we used to use before 2001"
        },
        {
            "label": "Low priority",
            "value": "L",
            "active": false
        }
    ]
}

#/ordered - Ordered reference list

In the ordered list, the items are presented in a guaranteed order (decided by the person who entered the data into the system).

{
    "title": "Ordered reference list",

    "type": "array",
    "items": {
        "type": "object",
        "additionalProperties": false,

        "properties": {
            "label": {"type": "string"},
            "value": {"anyOf": [
                {"type": "string"},
                {"type": "number"}
            ]}
        },

        "required": ["label", "value"]
    }
}
[
    {
        "label": "Very high priority",
        "value": "X"
    },
    {
        "label": "High priority",
        "value": "A"
    },
    {
        "label": "Medium priority",
        "value": "M"
    },
    {
        "label": "Low priority",
        "value": "L"
    }
]


Is there anything wrong with this page?