Custom Structure Web Services¶

Warning

SDMX 3.2 has not been released and is currently in internal review, so the resources, formats and behaviour described on this page are provisional and may change as a result of the review process. See the introduction for details.

Custom structures are submitted and queried through the standard SDMX structure web services. There is no separate API for them; the only thing which is unusual is that the REST API resource used to query instances is not fixed by the standard, because the class of the instances is defined by data.

Formats¶

Custom Structure Definitions and their instances are only expressible in formats which understand the draft SDMX 3.2 specification.

Format	`format` parameter	Definitions container	Instances container
SDMX-ML 3.2	`sdmx-3.2`	`str:CustomStructureDefinitions`	`str:CustomStructures`
SDMX-JSON 2.2	`sdmx-json&version=2.2.0`	`data.customStructureDefinitions`	`data.customStructures`
Fusion JSON	`fusion-json`	`CustomStructureDefinition`	`CustomStructure`

Requesting custom structures in an earlier format is not possible - earlier formats have no container to put them in.

In SDMX-ML the CustomStructures container holds each instance as an element named after the class of its definition, in a namespace which is the URN of that definition. A validator which has only the standard SDMX schema set checks such an instance for well formedness; full validation requires the schema generated from the definition.

Submitting¶

Custom structures are submitted through the Submit Structures Web Service, like any other structure:

POST /ws/secure/sdmxapi/rest/

A definition and instances of it may be submitted in the same message, in which case the definition is processed first. Otherwise the definition must already exist in the registry - an instance cannot be validated without it.

Submission of an instance fails, and nothing is stored, when:

the Custom Structure Definition it names cannot be found;
the content does not conform to the definition (an unknown property, a cardinality breach, both members of a mutually exclusive set, a missing mandatory property, a missing id or Name);
a Reference property names an artefact which does not exist;
an IndirectReference property names an object which does not exist in its resolved context.

The last case is worth illustrating, because it is the one which surprises people. Submitting a Pivot Table whose dimension property reports TIME_PERIOD, where the referenced Dataflow's Data Structure Definition has no such Dimension, is rejected:

<message:Error>
    <message:ErrorMessage code="100">
        <com:Text>Could not resolve reference from structure PivotTableSlice 'SDMX:POP(1.0.0).TIME' to structure Dimension 'urn:sdmx:org.sdmx.infomodel.datastructure.Dimension=SDMX:POP(1.0.0).TIME_PERIOD'</com:Text>
    </message:ErrorMessage>
</message:Error>

Deletion uses the Delete Structures Web Service in the usual way, addressing the artefact by its resource, Agency, ID and version.

Querying definitions¶

Definitions are a standard SDMX artefact type with the fixed resource name customstructuredefinition, queried through the SDMX v2 structure API:

/sdmx/v2/structure/customstructuredefinition/{agencyID}/{resourceID}/{version}

All the standard behaviours apply - wildcards, multiple values, version operators, detail, references and asOf.

Retrieve every definition in the registry:

/sdmx/v2/structure/customstructuredefinition/*/*/*?format=sdmx-3.2

Retrieve the latest stable version of one definition:

/sdmx/v2/structure/customstructuredefinition/IMF/PIVOT_TABLE/+?format=sdmx-3.2

Querying instances¶

Instances of a custom structure are queried using a dynamic REST API resource, derived from the definition:

{definition-agency}:{classname}

the Agency part is the lower case, period separated identifier of the Agency which maintains the definition;
the class part is the lower case sdmxClassName declared by the definition.

Definition	Class	Instance resource
`IMF:PIVOT_TABLE(1.0.0)`	`PivotTable`	`imf:pivottable`
`IMF:GLOSSARY(1.0.0)`	`Glossary`	`imf:glossary`
`IMF.STA:COLLECTION_TABLE(1.0.0)`	`CollectionTable`	`imf.sta:collectiontable`

The resource is then used exactly like any built in resource:

/sdmx/v2/structure/{resource}/{agencyID}/{resourceID}/{version}
/sdmx/v2/structure/{resource}/{agencyID}/{resourceID}/{version}/{itemID}

Note

The Agency in the resource is the Agency of the definition; the Agency in the query path is the Agency of the instance. A query for imf:glossary/ECB/STAT_GLOSSARY/1.0.0 asks for the ECB's Glossary, built against the IMF's definition.

The resource carries no version of the definition, so one resource covers instances of every version of that definition. The version in the query path is the version of the instance. A client which needs to distinguish instances of PIVOT_TABLE(1.0.0) from instances of PIVOT_TABLE(2.0.0) should read the CustomStructureDefinition reference on each returned instance - bearing in mind that an instance may late bind to the definition, so the reference is not necessarily an absolute version - or query the definition's referencing artefacts:

/sdmx/v2/structure/customstructuredefinition/IMF/PIVOT_TABLE/1.0.0?format=sdmx-3.2&references=parents

Examples¶

Retrieve one Pivot Table:

/sdmx/v2/structure/imf:pivottable/OECD/POP/1.0.0?format=sdmx-3.2

Retrieve the latest minor version within 1.0:

/sdmx/v2/structure/imf:pivottable/OECD/POP/1.0+.0?format=sdmx-3.2

Retrieve every version of a Pivot Table as stubs:

/sdmx/v2/structure/imf:pivottable/OECD/POP/*?format=sdmx-3.2&detail=allstubs

Retrieve a Pivot Table together with everything it references - its definition and the Dataflow it is built over:

/sdmx/v2/structure/imf:pivottable/OECD/POP/1.0.0?format=sdmx-3.2&references=children

Find every custom structure which references a Dataflow:

/sdmx/v2/structure/dataflow/OECD/DF_POP/1.0.0?format=sdmx-3.2&references=parents

Retrieve one item from an item scheme based instance, returning the scheme as partial:

/sdmx/v2/structure/imf:glossary/ECB/STAT_GLOSSARY/1.0.0/CPI?format=sdmx-3.2

Retrieve every Glossary in the registry, whoever maintains it:

/sdmx/v2/structure/imf:glossary/*/*/*?format=sdmx-3.2

Resource registration¶

Because instance resources come from the definitions, a resource only exists once its definition has been submitted.

Querying imf:glossary before the IMF Glossary definition has been loaded returns 422 Unprocessable Entity, because the resource is not a recognised part of the API:

<message:Error>
    <message:ErrorMessage code="150">
        <com:Text>Unknown REST Resource: imf:glossary</com:Text>
    </message:ErrorMessage>
</message:Error>

Once the definition has been submitted, the same query is understood. If no instances exist yet the response is a normal 404 Not Found, meaning "the resource is valid, but nothing matches".

Registration is persistent, not a runtime artefact of the submission: the resources of every definition in the registry are re-registered when the registry starts, so a restart does not affect which resources are understood.

Item queries¶

The itemID path parameter is available for instances of a definition with base="ItemScheme", and behaves as it does for standard item schemes:

a query for a top level item returns the scheme containing only that item, marked as partial;
a query for a nested item returns the item together with its ancestors, marked as partial;
items below the requested item are not returned.

Reference queries¶

Instances take part in reference queries like every other structure.

Query	Returns
`references=children` on an instance	The Custom Structure Definition it conforms to, plus every artefact it references directly or indirectly
`references=parents` on a referenced artefact	The custom structure instances which reference it
`references=parents` on a definition	The instances which conform to it

Indirectly referenced artefacts participate too. A Pivot Table which reports the Dimension identifier SEX against a Dataflow is recorded as referencing that Dimension, so the reference is visible from both ends.