Skip to content

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"
Source: structureset/testStructureAndCodelistMaps.yaml (trimmed)

  • 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.
  • source and target of a map are the referenced maintainables in canonical form (Class=AGENCY:ID(version), see references).
  • components of a structure map pair the source and target component (concept) ids.
  • items of 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"
Source: structureset/testComplete.yaml

  • 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 is organisationSchemes, 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 source and target are 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: codelistMap is the id of a codelist map in the same Structure Set; alternatively toValueType and/or toTextFormat describe the target value, and valueMappings lists explicit value pairs. In valueMappings the target is a sorted value or array.
  • extension – written only when the structure map is an extension (true).
  • Item validity – a code map gains a validity period when it has one.
  • Annotations – component maps, code maps and item maps write annotations as 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[].target as either a single string or an array.
  • toValueType is read with the exact enumeration name (VALUE, NAME, DESCRIPTION).