Skip to content

Custom Structure Instance

A Custom Structure Instance is a maintainable structure whose type is defined by a Custom Structure Definition (CSD) rather than by the SDMX information model. Its ref class carries a package prefix: custom (or customscheme when the CSD defines an item scheme), followed by the lower case agency id(s) of the CSD's agency, then the class name defined by the CSD. For example an instance of the IMF PivotTable CSD starts ref: "custom.imf.PivotTable=OECD:POP(1.0.0)", and an instance of the IMF Glossary item scheme CSD starts ref: "customscheme.imf.Glossary=ECB:STAT_GLOSSARY(1.0.0)".

Simple form

The document starts with the common header, followed by the reference to the CSD, the SDMX class, and then the property values defined by the CSD:

format: "fusion-yaml(1.0.0)"
ref: "custom.imf.PivotTable=OECD:POP(1.0.0)"
name: "Population Pivot"
customstructuredefinition: "IMF:PIVOT_TABLE(1.0.0)"
sdmxClass: "PivotTable"
dataflow: "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=OECD:POP(1.0.0)"
rows:
  SEX:
    name: "Sex"
    dimension: "SEX"
    headingText: "By sex"
cols:
  AGE:
    name: "Age"
    dimension: "AGE"
    headingCode: "urn:sdmx:org.sdmx.infomodel.codelist.Code=SDMX:CL_AGE(1.0).TOTAL"
slice:
  TIME:
    name: "Time"
    dimension: "TIME_PERIOD"
    position: "0"
Source: customstructure/testPivotTable.yaml. The CSD is shown on the Custom Structure Definition page.

  • customstructuredefinition is the reference to the CSD, keyed by its lower case class name with a short URN value.
  • sdmxClass is the class name defined by the CSD.
  • Every other field is a property value, in the order held by the instance, keyed by the property id.

Values are written without type information

The writer does not record the property type (simple, reference, indirect reference, complex) or the text type of a value. All non-complex values are written as strings, exactly as held: references are full URNs (dataflow above), indirect references are ids (dimension: "SEX"), and numbers and booleans are quoted (position: "0"). Complex values are written as objects. The shape alone does not say which property type a value has, so the CSD is needed to read the document (see Reading notes).

Complex form

A property value flips between forms according to the number of values, whether the value is localised, and the base type of its complex type.

Simple values

Values Written as
one value prop: "value"
several values prop: followed by an array of strings
localised (a multilingual property) one field per locale, prop-en: "...", prop-fr: "..."

Localised property values always carry the locale suffix, including English (definition-en). This differs from the reserved name and description and from annotation text, where English is written without a suffix (see localised text). The suffix is kept because a property value may be either plain or localised, and the CSD does not enforce which, so prop: "..." (an unlocalised value) and prop-en: "..." (an English value) must stay distinguishable.

Complex values

Values Written as
one value prop: followed by an object
several values prop: followed by an array of objects

What the object contains depends on the base type of the value's complex type in the CSD:

  • Identifiable or Nameable – the value is written as a single-key object keyed by its id (rows: {SEX: {...}}, see identifiables).
  • Annotatable – the value has no id, so its fields are written directly in the object.

For example, a property keyValue of an Annotatable complex type with properties dimension and codeId is written as an object with one value, and as an array of objects with two:

keyValue:
  dimension: "FREQ"
  codeId: "A"

keyValue:
- dimension: "FREQ"
  codeId: "A"
- dimension: "REF_AREA"
  codeId: "UK"
Constructed examples, following the writer rules.

Item schemes

Instances of an item scheme CSD hold their items in the reserved items property. Items are nameable, so each one is keyed by its id and has a name. With two or more items items is an array; a single item would be written as an object. Nested complex values follow the same rules, so children with one value is an object:

format: "fusion-yaml(1.0.0)"
ref: "customscheme.imf.Glossary=ECB:STAT_GLOSSARY(1.0.0)"
name: "Statistical Glossary"
customstructuredefinition: "IMF:GLOSSARY(1.0.0)"
sdmxClass: "Glossary"
items:
- GDP:
    name: "Gross Domestic Product"
    definition-en: "The total monetary value of all final goods and services produced\
      \ within a country in a given period."
    definition-fr: "La valeur monetaire totale de tous les biens et services finaux\
      \ produits dans un pays sur une periode donnee."
    children:
      GDP_PC:
        name: "GDP per capita"
        definition-en: "Gross domestic product divided by the population of the country."
- CPI:
    name: "Consumer Price Index"
    definition-en: "A measure of the average change over time in the prices paid by\
      \ consumers for a basket of goods and services."
Source: customstructure/testGlossary.yaml

Reserved fields

The base type of a complex type reserves some property ids, which are not written as ordinary properties:

Base type Reserved Written as
Nameable id, name, description, annotations the id is the object key; name/description as localised text
Identifiable id, annotations the id is the object key
Annotatable annotations –

Inside a complex value the fields are written in this order:

  1. uri – identifiable and nameable values with a URI
  2. name, name-xx, description, description-xx – nameable values
  3. the property values
  4. annotations – when the value has annotations
  5. links – identifiable and nameable values with links

Note

In a complex value uri comes before name, whereas in other identifiable objects (e.g. items of a codelist) the names come first.

The annotations and links of the instance itself are part of the common header.

Field reference

Field Value Written when
customstructuredefinition short URN of the CSD always
sdmxClass class name defined by the CSD always
property id string, array of strings, object, or array of objects the instance has a value for the property
property id-locale string for each locale of a localised property

Stub

A stub also writes the CSD reference and sdmxClass after the header; no property values are written.

format: "fusion-yaml(1.0.0)"
ref: "custom.imf.PivotTable=OECD:POP(1.0.0)"
url: "https://sdmx.stub.com"
name: "Population Pivot"
customstructuredefinition: "IMF:PIVOT_TABLE(1.0.0)"
sdmxClass: "PivotTable"
Source: customstructure/testStub.yaml

Reading notes

Reading a Custom Structure Instance requires its CSD. Pass an ICanonicalStructureResolver to CanonicalFormatReader.read(rdl, resolver); it is asked for the structure referenced by customstructuredefinition:

ICanonicalStructureResolver resolver = ref -> csd.getUrn().equals(ref.getURN()) ? csd : null;
try (ReadableDataLocation rdl = new ReadableDataLocationTmp(file)) {
    MaintainableBean instance = CanonicalFormatReader.read(rdl, resolver);
}
  • If the CSD can not be resolved, reading fails as soon as the first property value is reached. A stub has no property values, so it can be read without a resolver.
  • The CSD tells the reader how to interpret each value:
    • a field named prop-xx is a localised value of property prop only if the CSD defines prop and does not define a property named prop-xx (property ids may contain -);
    • an object is read as keyed by id when its complex type has an SDMX class, otherwise its fields are read directly;
    • the value strings are typed and validated against the property definitions when the instance is built.
  • sdmxClass is not read from the document; the class comes from the CSD.
  • The instance type is taken from the package qualified class in ref.