Skip to content

Structure Map

A Structure Map (SDMX 3.0) maps the components of a source Data Structure or Dataflow to the components of a target Data Structure or Dataflow. Value mappings are held in separate Representation Maps, which component maps reference. Documents start ref: "StructureMap=AGENCY:ID(1.0)".

Simple form

The document starts with the common header. A Structure Map with a single component map:

format: "fusion-yaml(1.0.0)"
ref: "StructureMap=ACY:MAP_TEST(1.0)"
name: "Test"
source: "Dataflow=SOURCE_ACY:SOURCE_FLOW(1.0)"
target: "Dataflow=TARGET_ACY:TARGET_FLOW(1.0)"
componentMap:
- source: "COUNTRY"
  target: "REF_AREA"
  representationmap: "ACY:COUNTRY_REF_AREA(1.0)"
Source: structuremap/testSingleCompoentMap.yaml

  • source and target are the mapped Dataflows or Data Structures, in canonical form (Class=AGENCY:ID(version), see references).
  • componentMap lists the component maps; each one gives the source and target component ids, and optionally the Representation Map used to map their values. The Representation Map is written as a reference keyed by its lower case class name, with a short URN value.

Complex form

Many to many component maps

source and target of a component map are written as a string when one component is mapped; either becomes an array when several components are mapped (value or array).

componentMap:
- source: "SERIES_CODE"
  target:
  - "FREQ"
  - "REF_AREA"
  - "INDICATOR"
  - "DOMAIN"
  representationmap: "ACY:SERIES_CODE_FREQ_REF_AREA_INDICATOR_DOMAIN(1.0)"
Source: structuremap/testMultiTargetMapping.yaml (body only)

A component map without a representationmap copies the value unchanged.

Fixed values

fixedInput and fixedOutput are objects of component id to value, sorted by component id. A fixed input restricts the mapping to source data having that value; a fixed output sets the target component to that value for every mapping.

fixedInput:
  REF_AREA: "UK"
fixedOutput:
  FREQ: "A"
componentMap:
- source: "OBS_VALUE"
  target: "OBS_VALUE"
Source: structuremap/testFixedValueMap.yaml (body only)

Date pattern maps

timePatternMap maps a source component holding dates in a custom pattern to an SDMX time component.

timePatternMap:
- source: "D1"
  target: "TIME_PERIOD"
  targetFreqId: "A"
  periodResolution: "start"
  targetLocale: "en"
  pattern: "DD/MM/yyyy"
- source: "D2"
  target: "TIME_PERIOD"
  targetFreqDim: "FREQ"
  periodResolution: "mid"
  targetLocale: "en"
  pattern: "yy"
Source: structuremap/testTimePatternMappingResolvePeriod.yaml (body, trimmed)

The output frequency is given either as a fixed frequency id (targetFreqId) or as the id of the dimension that holds the frequency (targetFreqDim).

Epoch maps

epochMap maps a source component holding a number of intervals since a base period (for example Unix time) to an SDMX time component.

epochMap:
- source: "UNIX_TIME"
  target: "TIME_PERIOD"
  targetFreqDim: "FREQ"
  basePeriod: "1970"
  epochInterval: "millisecond"
Source: structuremap/testEpochMapOutputFreqDim.yaml (body only)

In date pattern and epoch maps, annotations is the last field of the object, after the map specific fields (targetLocale and pattern, or basePeriod and epochInterval):

epochMap:
- source: "UNIX_TIME"
  target: "TIME_PERIOD"
  targetFreqId: "A"
  basePeriod: "1970"
  epochInterval: "millisecond"
  annotations:
  - id: "ANN"
Source: structuremap/testEpochMapAnnotations.yaml (body only); see also structuremap/testTimePatternMappingAnnotations.yaml

Time format mapping

timeFormat references a Representation Map that maps a frequency id to a time pattern (for example A to YYYY). It is written in canonical form, e.g. timeFormat: "RepresentationMap=ACY:TIME_FORMATS(1.0)".

Field reference

Field Value Written when
source canonical reference to a Dataflow or Data Structure the source is set
target canonical reference to a Dataflow or Data Structure the target is set
timeFormat canonical reference to a Representation Map there is a time format mapping
fixedInput object, component id → value there are fixed inputs
fixedOutput object, component id → value there are fixed outputs
componentMap array of component maps there is at least one component map
timePatternMap array of date pattern maps there is at least one date pattern map
epochMap array of epoch maps there is at least one epoch map

componentMap[]

Field Value Written when
source component id, or array of ids always
target component id, or array of ids always
representationmap short URN of the Representation Map a Representation Map is referenced
annotations annotations the component map has annotations

timePatternMap[]

Field Value Written when
source source component id always
target target component id always
targetFreqDim id of the dimension holding the output frequency set
targetFreqId output frequency id set
periodResolution start, mid or end set
targetLocale locale of the pattern set
pattern date pattern set
annotations annotations the map has annotations

epochMap[]

Field Value Written when
source source component id always
target target component id always
targetFreqDim id of the dimension holding the output frequency set
targetFreqId output frequency id set
periodResolution start, mid or end set
basePeriod SDMX date, e.g. "1970" always (required)
epochInterval day, second, millisecond, microsecond or nanosecond always (required)
annotations annotations the map has annotations

Notes

  • The keys of fixedInput and fixedOutput are sorted by component id.
  • Component maps, date pattern maps and epoch maps are written in the order held by the bean.