Structure Set¶
A Structure Set is the SDMX 2.1 container for mappings between structures: structure maps (between Data Structures or
Dataflows), codelist maps, category scheme maps, concept scheme maps and organisation scheme maps. Documents start
ref: "StructureSet=AGENCY:ID(1.0)".
In SDMX 3.0 the mappings are maintained as separate artifacts, see Structure Map, Representation Map and the item scheme maps such as Category Scheme Map.
Simple form¶
The document starts with the common header. A Structure Set with one structure map and one codelist map:
format: "fusion-yaml(1.0.0)"
ref: "StructureSet=ACY:SS_MAPS(1.0)"
name: "TEST"
structureMaps:
- SM1:
name: "SM1"
source: "Dataflow=TEST:DF_SOURCE0(1.0)"
target: "Dataflow=TEST:DF_TARGET0(1.0)"
components:
- source: "D_SOURCE0"
target: "D_TARGET0"
codelistMaps:
- CL_MAP1:
name: "CL_MAP1"
source: "Codelist=TEST:CL_SOURCE0(1.0)"
target: "Codelist=TEST:CL_TARGET0(1.0)"
items:
- source: "C_SOURCE0"
target: "C_TARGET0"
- source: "C_SOURCE1"
target: "C_TARGET1"
- Each map is a nameable identifiable, written as a single-key object keyed by its id, holding its names and descriptions followed by the map fields.
sourceandtargetof a map are the referenced maintainables in canonical form (Class=AGENCY:ID(version), see references).componentsof a structure map pair the source and target component (concept) ids.itemsof a codelist map pair a source code id with a target code id.
Complex form¶
The full example below adds related structures, a structure map flagged as an extension, representation mappings on component maps, a validity period on a code map, and a concept scheme map.
format: "fusion-yaml(1.0.0)"
ref: "StructureSet=ACY:SS_COMPLETE(1.0)"
name: "TEST"
relatedStructures:
dataStructures:
- "TEST:DSD_SOURCE(1.0)"
- "TEST:DSD_TARGET(1.0)"
conceptSchemes: "TEST:CS_SOURCE(1.0)"
structureMaps:
- SM:
name: "DSD Map"
source: "DataStructure=TEST:DSD_SOURCE(1.0)"
target: "DataStructure=TEST:DSD_TARGET(1.0)"
extension: true
components:
- source: "FREQ"
target: "FREQUENCY"
representationmap:
codelistMap: "CL_MAP"
- source: "OBS_VALUE"
target: "OBS_VALUE"
- source: "REF_AREA"
target: "COUNTRY"
representationmap:
toValueType: "NAME"
toTextFormat:
textType: "String"
maxLength: 2
valueMappings:
- source: "EL"
target: "GR"
- source: "UK"
target: "GB"
codelistMaps:
- CL_MAP:
name: "Frequency Map"
source: "Codelist=TEST:CL_FREQ_SOURCE(1.0)"
target: "Codelist=TEST:CL_FREQ_TARGET(1.0)"
items:
- source: "A"
target: "ANNUAL"
validity: "2000-01-01/2010-12-31"
- source: "Q"
target: "QUARTERLY"
conceptSchemeMaps:
- CS_MAP:
name: "Concept Map"
source: "ConceptScheme=TEST:CS_SOURCE(1.0)"
target: "ConceptScheme=TEST:CS_TARGET(1.0)"
items:
- source: "FREQ"
target: "FREQUENCY"
- Related structures – each list is written as a single value or an array.
The values are short URNs (
AGENCY:ID(version)), as the list name already gives the structure type. The exception isorganisationSchemes, which may hold different organisation scheme types, so each value is written in canonical form, e.g."AgencyScheme=SDMX:AGENCIES(1.0)". - Component source/target – a component map normally maps one component to one component, so
sourceandtargetare strings; either becomes an array when several components are mapped. representationmap– a component map may carry an SDMX 2.1 representation mapping. It is always an object:codelistMapis the id of a codelist map in the same Structure Set; alternativelytoValueTypeand/ortoTextFormatdescribe the target value, andvalueMappingslists explicit value pairs. InvalueMappingsthetargetis a sorted value or array.extension– written only when the structure map is an extension (true).- Item validity – a code map gains a
validityperiod when it has one. - Annotations – component maps, code maps and item maps write
annotationsas the last field of the object when they have any.
Note
This representationmap object is specific to the SDMX 2.1 Structure Set. The SDMX 3.0
Structure Map instead references a separate Representation Map artifact.
Field reference¶
| Field | Value | Written when |
|---|---|---|
relatedStructures |
object, see below | the Structure Set has related structures |
structureMaps |
array of structure maps keyed by id | there is at least one structure map |
codelistMaps |
array of codelist maps keyed by id | there is at least one codelist map |
categorySchemeMaps |
array of item scheme maps keyed by id | there is at least one category scheme map |
conceptSchemeMaps |
array of item scheme maps keyed by id | there is at least one concept scheme map |
organisationSchemeMaps |
array of item scheme maps keyed by id | there is at least one organisation scheme map |
relatedStructures
| Field | Value | Written when |
|---|---|---|
dataStructures |
short URN(s) | there are related Data Structures |
metadataStructures |
short URN(s) | there are related Metadata Structures |
conceptSchemes |
short URN(s) | there are related Concept Schemes |
categorySchemes |
short URN(s) | there are related Category Schemes |
organisationSchemes |
canonical reference(s) Class=AGENCY:ID(version) |
there are related organisation schemes |
hierarchicalCodelists |
short URN(s) | there are related Hierarchical Codelists |
Every map (structureMaps[], codelistMaps[], categorySchemeMaps[], conceptSchemeMaps[],
organisationSchemeMaps[]), inside the object keyed by the map id:
| Field | Value | Written when |
|---|---|---|
name, name-xx, description, description-xx |
localised text | present |
uri |
string | the map has a URI |
source |
canonical reference | the source is set |
target |
canonical reference | the target is set |
| map specific fields | see below | |
annotations |
annotations | the map has annotations |
links |
links | the map has links |
Structure map specific fields
| Field | Value | Written when |
|---|---|---|
extension |
true |
the map is an extension |
components |
array of component maps | there is at least one component map |
components[].source |
string or array of component ids | always |
components[].target |
string or array of component ids | always |
components[].representationmap |
object, see below | the component map has a representation mapping |
components[].annotations |
annotations | the component map has annotations |
representationmap (component map)
| Field | Value | Written when |
|---|---|---|
codelistMap |
id of a codelist map in this Structure Set | the mapping uses a codelist map |
toValueType |
VALUE, NAME or DESCRIPTION |
set |
toTextFormat |
object of text format fields | set |
valueMappings |
array, sorted by source value | there are value mappings |
valueMappings[].source |
string | always |
valueMappings[].target |
string or array of strings (sorted), value or array | always |
Codelist map and item scheme map specific fields
| Field | Value | Written when |
|---|---|---|
items |
array of item maps | there is at least one item map |
items[].source |
source item id | always |
items[].target |
target item id | always |
items[].validity |
validity period | codelist maps only, when the code map has a validity period |
items[].annotations |
annotations | the item map has annotations |
Reading notes¶
- The reader accepts
valueMappings[].targetas either a single string or an array. toValueTypeis read with the exact enumeration name (VALUE,NAME,DESCRIPTION).