Skip to content

Hierarchical Codelist

A Hierarchical Codelist (SDMX 2.1) references a set of codelists and arranges their codes into one or more hierarchies. Each hierarchy is written in the same way as the body of a Hierarchy. A hierarchical codelist document starts ref: "HierarchicalCodelist=AGENCY:ID(1.0)".

Simple form

The document is the common header, the list of referenced codelists, and the list of hierarchies.

format: "fusion-yaml(1.0.0)"
ref: "HierarchicalCodelist=ACY:HCL(1.0)"
name: "TEST"
codelists:
- alias: "CL1"
  codelist: "SDMX:CL_AREA(1.0)"
hierarchies:
- H2:
    name: "H2"
    items:
    - code: "SDMX:CL_AREA(1.0).A"
      items:
      - code: "SDMX:CL_AREA(1.0).B"

Source: hierarchicalcodelist/testTwoHierarchies.yaml (trimmed)

  • codelists lists the codelists used by the hierarchies, in the order they are held. Each entry writes its alias and then the reference to the codelist, keyed by the lower-case class of the referenced structure (codelist).
  • hierarchies lists the hierarchies, each written as a single-key object keyed by the hierarchy id (see identifiables).
  • Inside a hierarchy, items holds the hierarchical codes, exactly as in a Hierarchy. Each hierarchical code references its code by full short URN (codelist and code id), not by the codelist alias. A hierarchical code that also records the alias of its codelist writes it as codelistAlias, after code (and id, if written):

    items:
    - code: "SDMX:CL_AREA(1.0).EUR"
      codelistAlias: "CL1"
Source: hierarchicalcodelist/testCodelistAlias.yaml (trimmed)

Complex form

A hierarchy can have names in several locales, descriptions, a URI, levels, annotations and links. Its hierarchical codes can carry ids, validity, levels and so on. The example below has two codelists and two hierarchies, the first of which has formal levels and a hierarchical code whose id differs from the code it references.

format: "fusion-yaml(1.0.0)"
ref: "HierarchicalCodelist=ACY:HCL(1.0)"
name: "TEST"
codelists:
- alias: "CL1"
  codelist: "SDMX:CL_AREA(1.0)"
- alias: "CL2"
  codelist: "SDMX:CL_REGION(1.0)"
hierarchies:
- H1:
    name: "H1"
    formalLevels: true
    level:
      L1:
        name: "Region"
        level:
          L2:
            name: "Country"
    items:
    - code: "SDMX:CL_AREA(1.0).EUR"
      items:
      - code: "SDMX:CL_AREA(1.0).UK"
      - code: "SDMX:CL_AREA(1.0).FR"
    - code: "SDMX:CL_REGION(1.0).WEST"
      items:
      - code: "SDMX:CL_REGION(1.0).N"
        id: "NORTH"
- H2:
    name: "H2"
    items:
    - code: "SDMX:CL_AREA(1.0).A"
      items:
      - code: "SDMX:CL_AREA(1.0).B"

Source: hierarchicalcodelist/testTwoHierarchies.yaml

Inside a hierarchy object the fields are written in this order: name and description (localised text), uri, formalLevels, level, items, annotations, links. The formalLevels, level and items fields, and the level and hierarchical code objects, are described on the Hierarchy page.

Field reference

Body fields, written after the common header:

Field Value Written when
codelists Array of codelist reference objects The hierarchical codelist references at least one codelist.
hierarchies Array of ID: {hierarchy} The hierarchical codelist has at least one hierarchy.

Codelist reference fields (codelists[]):

Field Value Written when
alias String The codelist reference has an alias.
codelist Short URN of the codelist, see references Always. The key is the lower-case class of the referenced structure.

Hierarchy fields (hierarchies[].<ID>):

Field Value Written when
name, name-<locale> String The hierarchy has a name in that locale.
description, description-<locale> String The hierarchy has a description in that locale.
uri String The hierarchy has a URI.
formalLevels true The hierarchy has formal levels.
level Single-key object ID: {level}, see Hierarchy The hierarchy defines at least one level.
items Array of hierarchical code objects, see Hierarchy The hierarchy has at least one code.
annotations Array, see annotations The hierarchy has annotations.
links Array, see links The hierarchy has links.

Reading notes

  • The hierarchies inside a hierarchical codelist have no agency or version of their own in the document; on reading they take the agency and version of the hierarchical codelist.
  • A hierarchical code with no id is given the id of the code it references.