Skip to content

Hierarchy

A Hierarchy (SDMX 3.0) arranges codes, taken from one or more codelists, into a tree of hierarchical codes. It can optionally define named levels. A hierarchy document starts ref: "Hierarchy=AGENCY:ID(1.0)".

Simple form

The document is the common header followed by the tree of hierarchical codes. Each hierarchical code is an object holding the reference to the code it uses, and its child codes under items.

format: "fusion-yaml(1.0.0)"
ref: "Hierarchy=ACY:HCY(1.0)"
name: "HCY"
items:
- code: "SDMX:CL_REF(1.0).EUR"
  items:
  - code: "SDMX:CL_REF(1.0).UK"
  - code: "SDMX:CL_REF(1.0).FR"
  - code: "SDMX:CL_REF(1.0).DE"
- code: "SDMX:CL_REF(1.0).ASIA"

Source: hierarchy/testLevels.yaml (levels removed)

  • items is the list of top level hierarchical codes, in the order they are held in the hierarchy.
  • code is the reference to the code, as a short URN including the code id. The key is the lower-case class of the referenced item, which is code for a code in a codelist.
  • items inside a hierarchical code holds its child codes, written in the same way, to any depth.

Unlike the items of an item scheme, hierarchical codes are not keyed by id: each is an object in the list. The id of a hierarchical code is normally the id of the code it references, so it is not written.

Complex form

Levels

A hierarchy can define levels. The level field holds the top level, as a single-key object keyed by the level id (see identifiables). Each level may hold its child level under its own level field, so the levels form a chain. When the levels are formal, formalLevels: true is written first: each depth of the tree is then at the level of the same depth.

format: "fusion-yaml(1.0.0)"
ref: "Hierarchy=ACY:HCY(1.0)"
name: "HCY"
formalLevels: true
level:
  L1:
    name: "Continent"
    level:
      L2:
        name: "Country"
items:
- code: "SDMX:CL_REF(1.0).EUR"
  items:
  - code: "SDMX:CL_REF(1.0).UK"
  - code: "SDMX:CL_REF(1.0).FR"
  - code: "SDMX:CL_REF(1.0).DE"
- code: "SDMX:CL_REF(1.0).ASIA"

Source: hierarchy/testFormalLevels.yaml

A level object holds, in order: name and description (localised text), uri, the coding format text format fields (textType, maxLength, …), the child level, then annotations and links.

Hierarchical code fields

A hierarchical code only writes the fields it needs. The level of a code is written only when the code explicitly references a level; a code whose level follows from its depth writes nothing.

format: "fusion-yaml(1.0.0)"
ref: "Hierarchy=ACY:HCY(1.0)"
name: "HCY"
level:
  L1:
    name: "Continent"
    level:
      L2:
        name: "Region"
        level:
          L3:
            name: "Country"
items:
- code: "SDMX:CL_REF(1.0).EUR"
  level: "L2"
  items:
  - code: "SDMX:CL_REF(1.0).UK"
  - code: "SDMX:CL_REF(1.0).N"
    id: "NORTH"
    uri: "https://example.org/hierarchy/NORTH"
    validity: "2009/2009"
    version: "1.0"
    annotations:
    - id: "NOTE"
      title: "Northern region"

Based on hierarchy/testLevelDiffersFromDepth.yaml, hierarchy/testHierarchicalCodeId.yaml and hierarchy/testValidity.yaml; the uri, version and annotations fields are added following the field order in HierarchyCanonicalWriter.

  • id is written only when the id of the hierarchical code differs from the id of the code it references (here the hierarchical code NORTH references code N).
  • uri is the URI of the hierarchical code.
  • validity is the validity period of the hierarchical code.
  • version is the version string held on the hierarchical code.
  • level is the id of the level the code is explicitly linked to.
  • annotations and links follow the shared annotations and links rules.
  • items (the child codes) is always the last field of a hierarchical code.

Field reference

Body fields, written after the common header:

Field Value Written when
formalLevels true The hierarchy has formal levels.
level Single-key object ID: {level} The hierarchy defines at least one level.
items Array of hierarchical code objects The hierarchy has at least one code.

Level object fields (level.<ID>):

Field Value Written when
name, name-<locale> String The level has a name in that locale.
description, description-<locale> String The level has a description in that locale.
uri String The level has a URI.
textType, maxLength, minLength, … Coding format, see representation The level has a coding format; only the set fields are written.
level Single-key object ID: {level} The level has a child level.
annotations Array The level has annotations.
links Array The level has links.

Hierarchical code fields (items[]):

Field Value Written when
code Short URN of the referenced code, e.g. "SDMX:CL_REF(1.0).UK" Always. The key is the lower-case class of the referenced item.
id String The id differs from the id of the referenced code.
codelistAlias String The hierarchical code names the alias of its codelist (only in a Hierarchical Codelist).
uri String The hierarchical code has a URI.
validity Validity period, e.g. "2009/2009" The hierarchical code has a validity period.
version String The hierarchical code has a version.
level Level id The hierarchical code explicitly references a level.
annotations Array The hierarchical code has annotations.
links Array The hierarchical code has links.
items Array of hierarchical code objects The hierarchical code has children.

Reading notes

  • A hierarchical code with no id is given the id of the code it references.
  • A hierarchical code without a code reference is rejected.
  • The level of a hierarchical code is read as a level id. A code with no level takes its level from its depth when the hierarchy has formal levels.