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"
sdmxClassis the class name of the instances, which becomes part of their URN andref(for examplecustom.imf.PivotTable).propertieslists the properties of the structure. Each property is a single-key object keyed by the property id (see identifiables) holding its cardinality, itstypeand 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"
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,IdentifiableorAnnotatable– the SDMX base the values of the type extend, which decides the reserved fields they have (see Custom Structure Instance); orextends: 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
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"
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
Reading notes¶
- A missing
itemSchemeis read as a maintainable (non item scheme) definition. - A missing
maxOccursis read as unbounded; a missingminOccurskeeps the default of 1. - A property without
typeis rejected. mutuallyExclusiveandrefTypeare accepted as a single string or an array.