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)
codelistslists the codelists used by the hierarchies, in the order they are held. Each entry writes itsaliasand then the reference to the codelist, keyed by the lower-case class of the referenced structure (codelist).hierarchieslists the hierarchies, each written as a single-key object keyed by the hierarchy id (see identifiables).- Inside a hierarchy,
itemsholds 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 ascodelistAlias, aftercode(andid, if written):
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
idis given the id of the code it references.