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)
itemsis the list of top level hierarchical codes, in the order they are held in the hierarchy.codeis 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 iscodefor a code in a codelist.itemsinside 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.
idis written only when the id of the hierarchical code differs from the id of the code it references (here the hierarchical codeNORTHreferences codeN).uriis the URI of the hierarchical code.validityis the validity period of the hierarchical code.versionis the version string held on the hierarchical code.levelis the id of the level the code is explicitly linked to.annotationsandlinksfollow 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
idis given the id of the code it references. - A hierarchical code without a code reference is rejected.
- The
levelof a hierarchical code is read as a level id. A code with noleveltakes its level from its depth when the hierarchy has formal levels.