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"
customstructuredefinitionis the reference to the CSD, keyed by its lower case class name with a short URN value.sdmxClassis 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:
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."
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:
uri– identifiable and nameable values with a URIname,name-xx,description,description-xx– nameable values- the property values
annotations– when the value has annotationslinks– 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"
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-xxis a localised value of propertyproponly if the CSD definespropand does not define a property namedprop-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.
- a field named
sdmxClassis not read from the document; the class comes from the CSD.- The instance type is taken from the package qualified class in
ref.