Skip to content

Representation Map

A Representation Map (SDMX 3.0) maps values of one or more source representations to values of one or more target representations. Each representation is either an enumeration (Codelist or Value List) or a text type. Structure Maps reference Representation Maps from their component maps. Documents start ref: "RepresentationMap=AGENCY:ID(1.0)".

Simple form

The document starts with the common header. A one to one mapping between two codelists:

format: "fusion-yaml(1.0.0)"
ref: "RepresentationMap=ACY:ONE2ONE_REPMAP(1.0)"
name: "Test: ONE2ONE_REPMAP"
source: "Codelist=ACY:S0(1.0)"
target: "Codelist=ACY:T0(1.0)"
mappedItems:
- source: "GB"
  target: "GBR"
- source: "US"
  target: "USA"
- source: "FR"
  target: "FRA"
Source: representationmap/test1To1MappingCodelist.yaml

  • source and target describe the representations. An enumeration is written as a canonical reference (Codelist=ACY:S0(1.0), ValueList=ACY:S0(1.0), see references); a non-enumerated representation is written as its text type, e.g. "String".
  • mappedItems lists the mappings, each pairing a source value with a target value.

Complex form

Several sources or targets

With one source representation source is a string. With several, it becomes an array of single-field objects, each repeating the field name (- source: ...); the same applies to target:

source: "String"
target:
- target: "String"
- target: "String"
- target: "String"
- target: "String"
mappedItems:
- source: "A"
  target:
  - "A"
  - "UK"
  - "EMP"
  - "EMPL"
Source: representationmap/testMultiTargetMapping.yaml (body, trimmed)

In a mapped item, the target values follow the value or array rule: one target value is a string, several are an array, in the order of the target representations.

Several source values are written as a sources array of objects, in the order of the source representations, instead of the inline source field:

source:
- source: "String"
- source: "String"
- source: "String"
- source: "String"
target: "String"
mappedItems:
- sources:
  - source: "A"
  - source: "UK"
  - source: "EMP"
  - source: "EMPL"
  target: "A"
Source: representationmap/testMultiSourceMapping.yaml (body, trimmed)

Regular expressions and substrings

A source value is a plain string to match. When it is a regular expression, regEx: true is added; start and end (numbers) take a substring of the source value before it is matched. With a single source these fields are written inline in the mapped item, before target:

mappedItems:
- source: "GB"
  regEx: true
  start: 1
  target: "GBR"
- source: "US"
  regEx: true
  end: 3
  target: "USA"
- source: "FR"
  regEx: true
  start: 1
  end: 3
  target: "FRA"
Source: representationmap/testSubstringWithRegex.yaml (body only)

With several sources, they are written inside each sources entry. Targets may refer to regular expression capture groups, and an empty value is written as "":

mappedItems:
- sources:
  - source: ""
  - source: ".*"
  target:
  - ""
  - "M"
- sources:
  - source: "^(.*)"
    regEx: true
  - source: "^(.*)"
    regEx: true
  target:
  - "\\1"
  - "\\2"
Source: representationmap/test2To2MappingRegex.yaml (body, trimmed)

Validity

A mapping that is valid for a limited period gains a validity field; either end may be open. A mapping valid for all periods has no validity field.

mappedItems:
- source: "C"
  target: "Cx"
  validity: "/2008-12-31"
- source: "C"
  target: "Cxx"
  validity: "2009-01-01/"
Source: representationmap/testMappingWithValidity.yaml (body, trimmed)

Field reference

Field Value Written when
source canonical reference or text type; array of {source: ...} objects when there are several always
target canonical reference or text type; array of {target: ...} objects when there are several always
mappedItems array of mappings there is at least one mapping

mappedItems[]

Field Value Written when
source source value one source value, and the value is not null
regEx true one source value, which is a regular expression
start number, substring start index one source value, start index greater than 0
end number, substring end index one source value, end index greater than 0
sources array of source value objects (source, regEx, start, end as above) more than one source value
target target value, or array of target values always
validity validity period the mapping is not valid for all periods
annotations annotations the mapping has annotations

Reading notes

  • A source or target value containing = is read as an enumeration reference; any other value is read as a text type.
  • Any field of a mapped item other than sources, target, validity and annotations is read as a field of the single (inline) source value.
  • A missing regEx is read as false; missing start and end mean no substring.