Support for enumerated values with descriptions

[cportele]

The discussion about this issue started in #953.

It is common that the domain of values of a property is an enumerated list. The value in the data is often a short code with a human-readable title and potentially a description. It is a good practice to publish such codelists (or codesets as used in the new ISO 19103:2024) as resources on the web.

When requesting a schema that contains such properties (as returnables, receivables, queryables), the response should not only list the codes, but also provide access to additional information about each code.

In the discussion we have identified two ways of representing properties with an enumerated list of codes.

The first option uses oneOf with a schema for each code. This has the advantage that all information is in the schema; no external information needs to be accessed.

The second option uses enum with a URI reference to the codelist resource. This has the advantage that enum is easier to parse/handle than oneOf and that a separate resource for codelists may be useful for other purposes (in the API or separate from the API). A codelist URI may exist and the codelist may already be managed / published at the URI.

Here is an example using the CulturePnt feature type in the Daraa dataset that was used in various OGC initiatives.

Using oneOf with each option with a const and optional title / description values

Example, see properties ZI037_REL and F_CODE:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://demo.ldproxy.net/daraa/collections/CulturePnt/schema",
  "title": "Cultural (Points)",
  "type": "object",
  "required": [
    "geometry",
    "ZI001_SDV"
  ],
  "properties": {
    "ZI006_MEM": {
      "title": "Memorandum",
      "type": "string"
    },
    "FCSUBTYPE": {
      "title": "Feature Subtype Code",
      "type": "integer"
    },
    "ZI037_REL": {
      "title": "Religious Designation",
      "oneOf": [
        {
          "const": 1,
          "title": "Buddhism"
        },
        {
          "const": 2,
          "title": "Islam"
        },
        {
          "const": 3,
          "title": "Roman Catholic"
        },
        {
          "const": 5,
          "title": "Judaism"
        },
        {
          "const": 6,
          "title": "Orthodox"
        },
        {
          "const": 7,
          "title": "Protestant"
        },
        {
          "const": 8,
          "title": "Shinto"
        },
        {
          "const": 9,
          "title": "Hinduism"
        },
        {
          "const": 10,
          "title": "Shia"
        },
        {
          "const": 11,
          "title": "Sunni"
        },
        {
          "const": 12,
          "title": "Nestorian"
        },
        {
          "const": 13,
          "title": "Chaldean"
        },
        {
          "const": 14,
          "title": "Mixed and/or No Designation"
        },
        {
          "const": -999999,
          "title": "No Information"
        }
      ]
    },
    "ZI001_SDP": {
      "title": "Source Description",
      "type": "string"
    },
    "UFI": {
      "title": "Unique Entity Identifier",
      "type": "string"
    },
    "geometry": {
      "x-ogc-role": "primary-geometry",
      "format": "geometry-point"
    },
    "id": {
      "x-ogc-role": "id",
      "type": "integer"
    },
    "F_CODE": {
      "title": "Feature Type Code",
      "x-ogc-role": "type",
      "oneOf": [
        {
          "const": "AK121",
          "title": "Lookout"
        },
        {
          "const": "AL012",
          "title": "Archaeological Site"
        },
        {
          "const": "AL030",
          "title": "Cemetery"
        },
        {
          "const": "AL130",
          "title": "Memorial Monument"
        },
        {
          "const": "BH075",
          "title": "Fountain"
        }
      ]
    },
    "ZI001_SDV": {
      "title": "Last Change",
      "x-ogc-role": "primary-instant",
      "format": "date-time",
      "type": "string"
    },
    "ZI005_FNA": {
      "title": "Name",
      "type": "string"
    }
  }
}

Using enum and a separate codelist resource

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://demo.ldproxy.net/daraa/collections/CulturePnt/schema",
  "title": "Cultural (Points)",
  "type": "object",
  "required": [
    "geometry",
    "ZI001_SDV"
  ],
  "properties": {
    "ZI006_MEM": {
      "title": "Memorandum",
      "type": "string"
    },
    "FCSUBTYPE": {
      "title": "Feature Subtype Code",
      "type": "integer"
    },
    "ZI037_REL": {
      "title": "Religious Designation",
      "x-ldproxy-codelistUri": "https://demo.ldproxy.net/daraa/codelists/daraa%2Frel",
      "enum": [
        -999999,
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14
      ],
      "type": "integer"
    },
    "ZI001_SDP": {
      "title": "Source Description",
      "type": "string"
    },
    "UFI": {
      "title": "Unique Entity Identifier",
      "type": "string"
    },
    "geometry": {
      "x-ogc-role": "primary-geometry",
      "format": "geometry-point"
    },
    "id": {
      "x-ogc-role": "id",
      "type": "integer"
    },
    "F_CODE": {
      "title": "Feature Type Code",
      "x-ldproxy-codelistUri": "https://demo.ldproxy.net/daraa/codelists/daraa%2Ff_code",
      "x-ogc-role": "type",
      "enum": [
        "AK121",
        "AL012",
        "AL030",
        "AL130",
        "BH075"
      ],
      "type": "string"
    },
    "ZI001_SDV": {
      "title": "Last Change",
      "x-ogc-role": "primary-instant",
      "format": "date-time",
      "type": "string"
    },
    "ZI005_FNA": {
      "title": "Name",
      "type": "string"
    }
  }
}

Note that this a (live example).

Proposal

Both variants have their advantages and disadvantages. Part 5 should, therefore, define the two variants as profiles (e.g., codelist-inline and codelist-ref). It would be the decision of each API that has coded values, whether they support none of the profiles, only one profile or both profiles.

In the by-reference profile, the new key for the URI reference to the codelist should be x-ogc-codelistUri.