Skip to content

Custom Structure Definition

A Custom Structure Definition (CSD) defines a new type of maintainable structure that is not part of the SDMX information model: its SDMX class name, its properties, and the complex types its properties use. Structures of that type are Custom Structure Instances. Documents start ref: "CustomStructureDefinition=AGENCY:ID(1.0.0)".

Simple form

The document starts with the common header. A CSD defining a structure class with a single reference property:

format: "fusion-yaml(1.0.0)"
ref: "CustomStructureDefinition=IMF:PIVOT_TABLE(1.0.0)"
name: "PIVOT_TABLE"
sdmxClass: "PivotTable"
properties:
- dataflow:
    minOccurs: 1
    maxOccurs: 1
    type: "reference"
    refType: "Dataflow"
Source: customstructuredefinition/testPivotTable.yaml (trimmed)

  • sdmxClass is the class name of the instances, which becomes part of their URN and ref (for example custom.imf.PivotTable).
  • properties lists the properties of the structure. Each property is a single-key object keyed by the property id (see identifiables) holding its cardinality, its type and the fields of that type.

Complex form

Property types

type is one of four values, and decides which other fields follow it:

type Meaning Type specific fields
simple a value with a text format the text format fields, e.g. textType, multilingual, minValue
reference a reference to a structure refType: the class of the referenced structure, a string, or an array when several classes are allowed
indirectRef an id of an item or component within a structure referenced by another property context: the id of the property that gives the structure; refType: the class of the referenced object
complex a nested object complexType: the id of a complex type defined in complexTypes

A property always writes minOccurs. maxOccurs is written only when there is an upper bound; no maxOccurs means unbounded. description is a single, non-localised string, written first when present.

properties:
- dimension:
    description: "Dimension ID"
    minOccurs: 1
    maxOccurs: 1
    type: "indirectRef"
    context: "dataflow"
    refType: "Dimension"
- value:
    description: "Free text Dimension Value"
    minOccurs: 1
    maxOccurs: 1
    type: "simple"
    textType: "String"
Source: customstructuredefinition/testMRD3P.yaml (excerpt)

A class from another CSD is written with its package, for example refType: "custom.imf.PivotTable".

Complex types and mutually exclusive properties

complexTypes lists the types used by complex properties. Each is a nameable keyed by its id, with names and descriptions, then either:

  • baseType: Nameable, Identifiable or Annotatable – the SDMX base the values of the type extend, which decides the reserved fields they have (see Custom Structure Instance); or
  • extends: the id of another complex type in this CSD, whose properties it inherits.

Then come the optional sdmxClass (the class of the values, needed for values that have a URN), the properties, and mutuallyExclusive. Each entry of mutuallyExclusive is one set of properties of which only one may be reported, written as the property ids, sorted and joined with +. It follows the value or array rule: one set is written as a string, several as an array.

format: "fusion-yaml(1.0.0)"
ref: "CustomStructureDefinition=IMF:PIVOT_TABLE(1.0.0)"
name: "PIVOT_TABLE"
sdmxClass: "PivotTable"
properties:
- rows:
    minOccurs: 0
    type: "complex"
    complexType: "RowColType"
- slice:
    minOccurs: 0
    type: "complex"
    complexType: "SliceType"
- dataflow:
    minOccurs: 1
    maxOccurs: 1
    type: "reference"
    refType: "Dataflow"
complexTypes:
- RowColType:
    name: "RowCol"
    baseType: "Nameable"
    sdmxClass: "PivotTableRowCol"
    properties:
    - level:
        minOccurs: 0
        maxOccurs: 1
        type: "simple"
        textType: "Integer"
        minValue: 0
    - dimension:
        minOccurs: 1
        maxOccurs: 1
        type: "indirectRef"
        context: "dataflow"
        refType: "Dimension"
    - headingText:
        minOccurs: 1
        maxOccurs: 1
        type: "simple"
        textType: "String"
    - headingCode:
        minOccurs: 1
        maxOccurs: 1
        type: "reference"
        refType: "Code"
    mutuallyExclusive: "headingCode+headingText"
- SliceType:
    name: "Slice"
    extends: "RowColType"
    sdmxClass: "PivotTableSlice"
    properties:
    - position:
        minOccurs: 0
        maxOccurs: 1
        type: "simple"
        textType: "Integer"
        minValue: 0
Source: customstructuredefinition/testPivotTable.yaml (trimmed)

Item scheme definitions

A CSD whose instances are item schemes writes itemScheme: true. The items are defined by the reserved items property, a complex property whose complex type is the item type:

format: "fusion-yaml(1.0.0)"
ref: "CustomStructureDefinition=IMF:GLOSSARY(1.0.0)"
name: "GLOSSARY"
sdmxClass: "Glossary"
properties:
- items:
    minOccurs: 0
    type: "complex"
    complexType: "TermType"
itemScheme: true
complexTypes:
- TermType:
    name: "Term"
    baseType: "Nameable"
    sdmxClass: "GlossaryTerm"
    properties:
    - definition:
        minOccurs: 0
        type: "simple"
        textType: "String"
        multilingual: true
    - children:
        minOccurs: 0
        type: "complex"
        complexType: "TermType"
Source: customstructuredefinition/testGlossary.yaml

Instances of an item scheme CSD have the URN package customscheme instead of custom, e.g. customscheme.imf.Glossary.

Field reference

Field Value Written when
sdmxClass class name of the instances set
properties array of properties keyed by id there is at least one property
mutuallyExclusive + joined property ids, value or array there are mutually exclusive property sets
itemScheme true the instances are item schemes
complexTypes array of complex types keyed by id there is at least one complex type

complexTypes[] (inside the object keyed by the type id)

Field Value Written when
name, name-xx, description, description-xx localised text present
uri string the type has a URI
extends id of the extended complex type the type extends another complex type
baseType Nameable, Identifiable or Annotatable the type does not extend another complex type
sdmxClass class name of the values set
properties array of properties keyed by id there is at least one property
mutuallyExclusive + joined property ids, value or array there are mutually exclusive property sets
annotations annotations the type has annotations
links links the type has links

properties[] (inside the object keyed by the property id)

Field Value Written when
description string, not localised set
minOccurs number always
maxOccurs number there is an upper bound (absent means unbounded)
type simple, reference, indirectRef or complex always
complexType complex type id complex properties
context id of the property giving the referenced structure indirectRef properties
refType structure class(es), value or array (several classes only for reference) reference and indirectRef properties
text format fields see representation simple properties, for each facet that is set
annotations annotations the property has annotations

Stub

A stub CSD also writes sdmxClass and, for item scheme definitions, itemScheme: true, after the header, so that the type of its instances is known without the full definition:

format: "fusion-yaml(1.0.0)"
ref: "CustomStructureDefinition=IMF:GLOSSARY(1.0.0)"
url: "https://sdmx.stub.com"
name: "GLOSSARY"
sdmxClass: "Glossary"
itemScheme: true
Source: customstructuredefinition/testStub.yaml

Reading notes

  • A missing itemScheme is read as a maintainable (non item scheme) definition.
  • A missing maxOccurs is read as unbounded; a missing minOccurs keeps the default of 1.
  • A property without type is rejected.
  • mutuallyExclusive and refType are accepted as a single string or an array.