Skip to content

Codelist

A Codelist is an item scheme of codes: an enumerated list of allowed values, such as frequencies or countries. Codes may form a hierarchy through a parent code, and a codelist may inherit codes from other codelists. A codelist document starts ref: "Codelist=AGENCY:ID(1.0)".

Simple form

In its simplest form a codelist is the common header followed by a list of codes. Each code is a single ID: "name" pair.

format: "fusion-yaml(1.0.0)"
ref: "Codelist=ACY:CL_FREQ(1.0)"
name: "Frequency"
items:
- A: "Annual"
- Q: "Quarterly"
- M: "Monthly"
- D: "Daily"
  • items is the list of codes, written in the order they are held in the codelist (codes are not sorted).
  • Each code is written as ID: "name", where the name is the English name. This is the simple form of an item.

YAML keys are only quoted when YAML requires it. For example, a code with the id Y is written - "Y": "Y-name", because an unquoted Y would be read as a boolean by some YAML parsers.

Complex form

A code is written in the simple form only when it has nothing to say other than its id and its English name. As soon as it carries more information it becomes an object, keyed by its id. All other codes in the list stay in the simple form.

format: "fusion-yaml(1.0.0)"
ref: "Codelist=ESTAT:CL_ACTIVITY(1.0.2)"
name: "Activity"
items:
- _T:
    name: "Total - All activities"
    description: "This aggregate includes all activities"
- A: "Agriculture, forestry and fishing"
- A01:
    name: "Crop and animal production"
    name-fr: "Culture et production animale"
    uri: "https://example.org/activity/A01"
    parent: "A"
    validity: "2008/2025"
    annotations:
    - id: "NOTE"
      type: "FOOTNOTE"
      text: "Includes hunting"
    links:
    - rel: "external"
      url: "https://example.org/activity/A01.html"

Constructed from the field order in CodelistCanonicalWriter; see codelist/testActivityWithDescriptions.yaml, codelist/testHierarchy.yaml, codelist/testItemValidiy.yaml, codelist/testUri.yaml and codelist/testLinks.yaml for the individual cases.

A code is written as a string (- A: "Annual") when all of the following are true:

  • it has exactly one name, and that name is in English;
  • it has no description;
  • it has no URI;
  • it has no parent code;
  • it has no validity period;
  • it has no annotations and no links.

If any one of these is not true, the code is written as an object. Inside the object the fields are written in this order:

  1. name, then the name in other locales (name-fr, …), then description and description-<locale>, as localised text. English comes first, the other locales follow in alphabetical order.
  2. uri, the code's URI.
  3. parent, the id of the parent code. The codes are always written as a flat list; the hierarchy is expressed only through parent.
  4. validity, the code's validity period, for example "1892/1976".
  5. annotations, see annotations.
  6. links, see links.

Partial codelists

A partial codelist (one that holds only a subset of the codes of the full codelist) writes partial: true as the first body field, after the header:

format: "fusion-yaml(1.0.0)"
ref: "Codelist=ACY:CL_FREQ(1.0.0)"
name: "TEST"
partial: true
items:
- A: "Annual"
- S: "Semi-Annual"

Source: codelist/testPartial.yaml (trimmed)

Inheritance

A codelist that extends other codelists writes an inheritance list before the items. Each rule references the inherited codelist and, optionally, a prefix added to the inherited code ids.

format: "fusion-yaml(1.0.0)"
ref: "Codelist=ACY:CL_INDICATOR(1.0)"
name: "TEST"
inheritance:
- codelist: "ACY:CL_INDICATOR_1(1.0)"
  prefix: "EX1_"
- codelist: "ACY:CL_INDICATOR_2(1.0)"
  prefix: "EX2_"
items:
- EX1_IA: "Indicator A ex1"
- EX1_IB: "Indicator B ex1"
- EX2_IA: "Indicator A ex2"
- EX2_IB: "Indicator B ex2"

Source: codelist/testDiscriminatedUnion.yaml (trimmed)

A rule can also select which codes are inherited. Each selection is sorted and follows the value or array rule: a single id is written as a string, several as an array.

inheritance:
- codelist: "SDMX:CL_AREA(1.0)"
  inclusive:
  - "EU%"
  - "UK"
  inclusiveCascade: "EUR"
  exclusive: "EU27"
  exclusiveCascade: "EU15"

The inheritance rules are written in the order they are held on the codelist. The inherited codes themselves are part of items, like any other code.

Field reference

Body fields, written after the common header:

Field Value Written when
partial true The codelist is partial.
inheritance Array of inheritance rule objects The codelist inherits from at least one codelist.
items Array of codes, each ID: "name" or ID: {object} The codelist has at least one code.

Inheritance rule fields (inheritance[]):

Field Value Written when
codelist Short URN of the inherited codelist, see references. The key is the lower-case class of the referenced structure. Always.
prefix String prefix added to inherited code ids A prefix is set.
inclusive Sorted value or array of code ids to include; % is a wildcard At least one id is set.
inclusiveCascade Sorted value or array of code ids whose descendants are included At least one id is set.
exclusive Sorted value or array of code ids to exclude; % is a wildcard At least one id is set.
exclusiveCascade Sorted value or array of code ids whose descendants are excluded At least one id is set.

Code object fields (items[].<ID>), used when the code is not simple:

Field Value Written when
name, name-<locale> String The code has a name in that locale.
description, description-<locale> String The code has a description in that locale.
uri String The code has a URI.
parent Id of the parent code The code has a parent.
validity Validity period, e.g. "1892/1976" The code has a validity period.
annotations Array, see annotations The code has annotations.
links Array, see links The code has links.

Reading notes

  • A code written as ID: "name" is read as a code with a single English name.
  • A codelist document with a url in the header and no items is read back as a stub.
  • The inheritance selections (inclusive, exclusive, …) are read as either a single value or an array.