Skip to content

Query Structures SDMX v2 REST API

Overview

Fusion Metadata Registry provides a web service for querying structural metadata using the SDMX REST API v2 structure query endpoint as defined in the official SDMX REST API v2.2.1 structure query specification.

This page describes the standard SDMX REST API v2 structure query syntax and parameters.
Entry Point /sdmx/v2/structure/
Access Public
Authentication None
Http Method GET
Response Format SDMX REST API v2 structure formats as negotiated using the HTTP Accept header
Response Statuses 200 - Success
404 - Structure not found
500 - Server Error

Syntax

The SDMX REST API v2 structure endpoint uses the following syntax:

protocol://domain/sdmx/v2/structure{artefactType}/{agencyID}/{resourceID}/{version}?detail={detail}&references={references}&asOf={asOf}

For item schemes and other supported collections, an additional itemID path parameter may be used:

protocol://domain/sdmx/v2/structure{artefactType}/{agencyID}/{resourceID}/{version}/{itemID}?detail={detail}&references={references}&asOf={asOf}

Path parameters

Parameter Type Description Default Multiple values?
artefactType String The type of structural metadata to be returned. See the list in the next section. * No
agencyID SDMX common:NestedNCNameIDType The agency maintaining the artefact to be returned. * Yes, separated by ,
resourceID SDMX common:IDType The identifier of the artefact to be returned. * Yes, separated by ,
version SDMX semantic version The version of the artefact to be returned. ~ Yes, separated by ,
itemID Depends on artefact type The item to be returned for supported item scheme queries. * Yes, separated by ,

Artefact types

The following SDMX REST API v2 artefact types are supported for structure queries:

  • datastructure
  • metadatastructure
  • categoryscheme
  • conceptscheme
  • codelist
  • hierarchy
  • hierarchyassociation
  • valuelist
  • agencyscheme
  • dataproviderscheme
  • metadataproviderscheme
  • dataconsumerscheme
  • organisationunitscheme
  • dataflow
  • metadataflow
  • reportingtaxonomy
  • provisionagreement
  • metadataprovisionagreement
  • structuremap
  • representationmap
  • conceptschememap
  • categoryschememap
  • organisationschememap
  • reportingtaxonomymap
  • process
  • categorisation
  • dataconstraint
  • metadataconstraint
  • transformationscheme
  • rulesetscheme
  • userdefinedoperatorscheme
  • customtypescheme
  • namepersonalisationscheme
  • vtlmappingscheme

Headers

HTTP Header Purpose Allowed Values
Accept Defines the response format. application/vnd.sdmx.structure+json;version=2.0.0
application/vnd.sdmx.structure+xml;version=3.0.0
Accept-Language Optional language negotiation for multilingual names and descriptions. Standard HTTP language tags such as en, fr, or *
If-Modified-Since Optional conditional retrieval based on modification time. HTTP date value

Query parameters

The SDMX REST API v2 structure query specification defines the following standard query parameters.

Parameter Purpose Allowed Values
detail Specifies how much information should be returned for matching artefacts and references. full (default)
allstubs
referencestubs
allcompletestubs
referencecompletestubs
referencepartial
raw
references Controls whether referenced artefacts, referencing artefacts, or both are returned. none (default)
parents
parentsandsiblings
ancestors
children
descendants
all
or a concrete artefact type such as codelist or dataflow
asOf Retrieves the artefact as it existed at the specified point in time. xs:dateTime

Notes on detail

  • full returns all available information.
  • allstubs returns only identification information and names for all returned artefacts.
  • referencestubs returns the main artefact in full, but references as stubs.
  • allcompletestubs returns identification, names, descriptions and annotations for all returned artefacts.
  • referencecompletestubs returns the main artefact in full, but references as complete stubs.
  • referencepartial returns referenced item schemes filtered to only the items needed by the returned artefacts.
  • raw returns extended codelists without resolving inherited codes.

Notes on itemID

The itemID parameter is valid only for queries on the following collection types:

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

When itemID is supplied:

  • if it identifies a top-level item, the returned item scheme contains only the matching item and is marked as partial;
  • if it identifies a nested item, the returned item scheme contains the matching item together with its ancestors and is marked as partial;
  • child items beneath the requested nested item are not included.

Notes on references

The references parameter can be used to retrieve artefacts referenced by the queried artefact, artefacts that reference it, or both.

Examples:

  • references=children returns artefacts referenced by the matched artefact.
  • references=parents returns artefacts that reference the matched artefact.
  • references=all returns both upward and downward first-level relationships, with deeper traversal where defined by the specification.
  • references=codelist returns only references of the specified artefact type, Codelists in this example.

For the full artefact-by-artefact reference applicability matrix and the exact meaning of referencepartial, refer to the official SDMX REST API v2.2.1 structure query specification.

Examples

Retrieve version 1.0.0 of the DSD ECB_EXR1 maintained by ECB, together with its child references, returning partial referenced item schemes:

/ws/public/sdmxapi/rest/structure/datastructure/ECB/ECB_EXR1/1.0.0?references=children&detail=referencepartial

Retrieve the latest stable version of the DSD ECB_EXR1 maintained by ECB:

/ws/public/sdmxapi/rest/structure/datastructure/ECB/ECB_EXR1/+

Retrieve the latest version of all DSDs maintained by ECB, together with related dataflows:

/ws/public/sdmxapi/rest/structure/datastructure/ECB?references=dataflow

Retrieve the latest version of all codelists without returning their codes:

/ws/public/sdmxapi/rest/structure/codelist?detail=allstubs

Retrieve the latest version of all maintainable artefacts maintained by ECB as stubs:

/ws/public/sdmxapi/rest/structure/all/ECB?detail=allstubs

Retrieve the category PRICES from category scheme DOMAINS maintained by ECB, together with referencing categorisations:

/ws/public/sdmxapi/rest/structure/categoryscheme/ECB/DOMAINS/+/PRICES?references=categorisation

Retrieve the latest version of codelist CL_FREQ maintained by either BIS or ECB:

/ws/public/sdmxapi/rest/structure/codelist/BIS,ECB/CL_FREQ

Official specification

The normative SDMX REST API v2 structure query definition is maintained by the SDMX Technical Working Group: