Structure queries¶

Overview¶

Structure queries allow retrieving structural metadata.

Below is a list of popular types of structural metadata, that you will typically find in SDMX web services.

• Concept schemes: In order to make sense of some statistical data, we need to know the concepts associated with them. For example, on its own, the figure 1.2953 is pretty meaningless, but if we know that this is an exchange rate for the US dollar against the euro on 23 November 2006, it starts making more sense. The various concepts are typically grouped into collections known as concept schemes.
• Codelists: Some of the concepts can be free text (such as a comment about a particular observation value) but others take their values from a controlled vocabulary list (such as, for example, a list of countries). These are known as codelists in SDMX.
• Data structure definitions: All the concepts that describe a particular domain (such as exchange rates or inflation) are grouped into a data structure definition (DSD). In a DSD, concepts are divided into dimensions and attributes. Dimensions, when combined, allow to uniquely identify statistical data. Attributes on the other hand do not help identifying statistical data, but add useful information (like the unit of measure or the number of decimals). In order to perform granular data queries, one must know the concepts that are used as dimensions, as well as their allowed values (as defined in the codelists).
• Dataflows: Dataflows represent the data that cover a particular domain (such as, for example, balance of payments). A dataflow provides a reference to the data structure definition that applies for a particular domain, thereby indicating how the data for that domain will look like.

Structure queries in SDMX allow you to retrieve structural metadata at various levels of granularity, from all structural metadata available in the source to a single code from a particular version of a particular codelist maintained by a particular agency.

Syntax¶

    protocol://ws-entry-point/structure/{artefactType}/{agencyID}/{resourceID}/{version}?{detail}&{references}&{asOf}

For item schemes, an additional path parameter (itemID) is permissible.

    protocol://ws-entry-point/structure/{artefactType}/{agencyID}/{resourceID}/{version}/{itemID}?{detail}&{references}&{asOf}

Notes about using itemID¶

As mentioned, itemID can be used for item scheme queries only! These are:

• categoryscheme
• conceptscheme
• codelist
• agencyscheme
• dataproviderscheme
• metadataproviderscheme
• dataconsumerscheme
• organisationunitscheme
• reportingtaxonomy
• transformationscheme
• rulesetscheme
• userdefinedoperatorscheme
• customtypescheme
• namepersonalisationscheme
• vtlmappingscheme

Although it is not following the item scheme pattern, the valuelist is also a collection, i.e. a collection of values.

If itemID is set and is a top-level id (e.g.: Code A (Annual) in the Frequency Codelist), and such an item exists in the matching item scheme, the item scheme returned should contain only the matching item and its isPartial parameter should be set to true.

If itemID is set and is a nested id (e.g.: Category A.1.1, belonging to Category A.1, belonging to Category A in a Category Scheme), and such an item exists in the matching item scheme, the item scheme returned should contain the matching item and its ancestors, and its isPartial parameter should be set to true.

The detail parameter allows specifying the amount of details to be retrieved. When itemID is used, the full details of the items requested are the following:

• Identification
• Names
• Descriptions
• Annotations
• Other details except Items

Since details are not exactly the same for all Item Schemes, the following table provides these details per Artefact type (@ is used for XML attributes and / for XML elements).

While most Item Schemes are flat, hence the above table is easy to interpret, for Category Schemes and Reporting Taxonomies (which have a nested structure) the above table indicates that any child Item(s) of the Item(s) requested must not be included in an Item Query request.

Further to the above, the reference resolution mechanism will be applied to all items returned. For example, querying for a category which has two ancestors in the hierarchy of the category scheme, will result into returning three categories (the requested one and its ancestors), as well as all references of those three categories.

Applicability and meaning of references (including referencepartial)¶

The table below lists the 1st level artefacts (one level up, one level down) that will be returned if the references parameter is set to all. Artefacts referenced by the matching artefact are displayed in regular style, artefacts that reference the matching artefact are displayed in Italic and artefacts that can both reference and be referenced by the matching artefact are displayed in bold italic.

Also, when returning only partial references (via referencepartial), the filtering applies to any dependency, regardless of its level. The table below describes the impact of using referencepartial on the referenced item schemes.

For example, a dataflow only references a data structure definition and, in addition, it may be referenced by one or more data constraints. In case references is set to all and detail is set to referencepartial, the following should apply to the returned item schemes:

• The concept scheme(s) should only include the concepts referenced by the data structure referenced by target dataflow;
• The codelist(s) should only include the codes referenced by the data constraint(s) referencing the target dataflow;
• The data provider schemes(s) should only include the data provider(s) that are linked to the target dataflow via a provision agreement
• The agency scheme(s) should only include the agencies maintaining the structural metadata to be returned (dataflow, data constraints, data structures, etc.)

Response types¶

The following media types can be used with structure queries:

• application/vnd.sdmx.structure+json;version=2.1.0
• application/vnd.sdmx.structure+xml;version=3.1.0
• application/vnd.sdmx.structure+json;version=2.0.0
• application/vnd.sdmx.structure+xml;version=3.0.0

The default format is highlighted in bold. For media types of previous SDMX versions, please consult the documentation of the SDMX version you are interested in.

Examples of queries¶

• To retrieve version 1.0.0 of the DSD with id ECB_EXR1 maintained by the ECB, as well as the code lists and the concepts used in the DSD:

  https://ws-entry-point/structure/datastructure/ECB/ECB_EXR1/1.0.0?references=children&detail=referencepartial
  

• To retrieve the latest stable version of the DSD with id ECB_EXR1 maintained by the ECB, without the code lists and concepts of the DSD:

  https://ws-entry-point/structure/datastructure/ECB/ECB_EXR1/+
  

• To retrieve the latest version of all DSDs maintained by the ECB, as well as the dataflows using these DSDs:

  https://ws-entry-point/structure/datastructure/ECB?references=dataflow
  

• To retrieve the latest version of all code lists maintained by all maintenance agencies, but without the codes:

  https://ws-entry-point/structure/codelist?detail=allstubs
  

• To retrieve, as stubs, the latest version of all maintainable artefacts maintained by the ECB:

  https://ws-entry-point/structure/all/ECB?detail=allstubs
  

• To retrieve the category PRICES of the DOMAINS category scheme maintained by the ECB, as well as the categorisations referencing that category:

  https://ws-entry-point/structure/categoryscheme/ECB/DOMAINS/+/PRICES?references=categorisation
  

• To retrieve the latest version of the CL_FREQ codelists maintained by the BIS or the ECB:

  https://ws-entry-point/structure/codelist/BIS,ECB/CL_FREQ