Skip to content

VTL Mapping Scheme

A VTL Mapping Scheme maps the aliases used in VTL programs to SDMX structures: Dataflows, Codelists and Concepts. Each mapping is an item of the scheme. Documents start ref: "VtlMappingScheme=AGENCY:ID(1.0)".

Unlike the other VTL schemes, a VTL Mapping Scheme has no VTL version, so no vtlVersion field is written.

Simple form

The smallest complete VTL Mapping Scheme has one mapping, with its alias and the structure it maps to. A mapping is never written in the ID: "name" short form, every mapping is written as an object.

format: "fusion-yaml(1.0.0)"
ref: "VtlMappingScheme=SDMX:VTL_MAPPING(1.0)"
name: "VTL_MAPPING Name"
items:
- DF2:
    name: "N2"
    alias: "alias8"
    dataflow: "ACY1:DF2(1.0)"
Trimmed from vtlmappingscheme/testComplete.yaml

The document starts with the common header. The body fields are:

  • items – the mappings, in scheme order, each keyed by its id (see items).
    • name – the localised name of the mapping.
    • alias – the name by which the structure is known in VTL. Required.
    • the mapped structure – a reference keyed by the lower case class of the referenced structure, with a short URN value. Required.

Complex form

The kind of mapping is not written as a field of its own; it is given by the class of the mapped structure, which is the field name of the reference:

Reference field Mapping kind Example value
dataflow VTL Dataflow Mapping "ACY1:DF1(1.0)"
codelist VTL Codelist Mapping "ACY1:CL1(1.0)"
concept VTL Concept Mapping "ACY1:CS1(1.0).C1" (a Concept is identified within its Concept Scheme)

A Dataflow mapping can also state the methods and sub-spaces used to map between the SDMX dataflow and the VTL dataset. These fields are only written for Dataflow mappings.

format: "fusion-yaml(1.0.0)"
ref: "VtlMappingScheme=SDMX:VTL_MAPPING(1.0)"
name: "VTL_MAPPING Name"
items:
- CLM1:
    name: "N1"
    alias: "alias1"
    codelist: "ACY1:CL1(1.0)"
- CM1:
    name: "N1"
    alias: "alias5"
    concept: "ACY1:CS1(1.0).C1"
- DFM1:
    name: "N1"
    alias: "alias7"
    dataflow: "ACY1:DF1(1.0)"
    fromMethod: "FromMethod"
    toMethod: "ToMethod"
    fromSubSpace:
    - "D1"
    - "D2"
    - "D3"
    toSubSpace:
    - "D1x"
    - "D2x"
    - "D3x"
Trimmed from vtlmappingscheme/testComplete.yaml

  • fromMethod and toMethod are written only when set.
  • fromSubSpace and toSubSpace are written only when they have at least one value. They follow the value or array rule: a single value is written as a string, several as an array.
  • A mapping may also carry a description, a URI, annotations and links, written in the positions given in the field reference below.

Field reference

Scheme fields, written after the common header:

Field Value Written when
partial true The scheme is a partial item scheme
items Array of mappings The scheme has at least one mapping

Mapping fields (items[].<ID>):

Field Value Written when
name, name-<lang> String Always (en as name, other locales as name-<lang>)
description, description-<lang> String The mapping has a description
uri String The mapping has a URI
alias String Always (required)
dataflow / codelist / concept Short URN of the mapped structure Always (required); the field name depends on the mapped structure
fromMethod String Dataflow mapping with a from method
toMethod String Dataflow mapping with a to method
fromSubSpace String or array of strings Dataflow mapping with at least one from sub-space value
toSubSpace String or array of strings Dataflow mapping with at least one to sub-space value
annotations Array, see annotations The mapping has annotations
links Array, see links The mapping has links

Mappings never use the - ID: "name" simple item form, as the mapping bean reports itself as never simple.

Reading notes

  • The reader determines the kind of each mapping from the class of the reference field: a Dataflow reference gives a Dataflow mapping, a Concept reference a Concept mapping, and a Codelist reference a Codelist mapping. A reference to any other class is an error.
  • A mapping without a reference field is an error.
  • fromMethod, toMethod, fromSubSpace and toSubSpace are only kept for Dataflow mappings; on a Codelist or Concept mapping they are read but discarded.