Field Guide to SDMX-JSON Structure Message 2.1.0 Objects (aligned with SDMX 3.1)¶

message¶

Message is the top level object and it contains the requested information (“data”) as well as the meta-information describing the (technical) context of the message and, possibly, error information.

$schema - String optional. Contains the URL to the schema allowing to validate the message. This also allows identifying the version of SDMX-JSON format used in this message. Providing the link to the SDMX-JSON schema is recommended.
meta - Object optional. A meta object that contains non-standard meta-information and basic technical information about the message, such as when it was prepared and who has sent it.
data - Object optional. Data contains the message’s “primary data”.
errors - Array optional of statusInformation objects providing - when appropriate - more detail to the HTTP status codes in the RESTful SDMX web service responses.

The properties data and errors CAN coexist in the same message.

Example

{
    "$schema": "https://json.sdmx.org/2.1/sdmx-json-data-schema.json",
    "meta": {
        # meta object #
    },
    "data": {
        # data object #
    },
    "errors": [
        {
            # statusInformation object #
        }
    ]
}

meta¶

Object optional. Used to include non-standard meta-information and basic technical information about the message, such as when it was prepared and who has sent it. Any members MAY be specified within meta objects.

schema - String optional. Deprecated and replaced by the $schema property at the root level, which allows for automated validations.
id - String. Unique string that identifies the message for further references.
test - Boolean optional. Indicates whether the message is for test purposes or not. False for normal messages.
- prepared - String. A date or date-time indicating when the message was prepared. Values must follow the ISO 8601 syntax for dates or combined dates and times, including time zone.
contentLanguages - Array optional. Array of strings containing the identifier of all languages used anywhere in the message for localized elements, and thus the languages of the intended audience, representing in an array format the same information than the http Content-Language response header, e.g. “en, fr-fr”. See IETF Language Tags. The array’s first element indicates the main language used in the message for localized elements. The usage of this property is recommended.
name - String optional. Human-readable (best-language-match) name for the transmission.
names - Object optional. Human-readable localised names for the transmission.
sender - Object. Sender contains information about the party that is transmitting the message.
receiver - Object optional. Receiver contains information about the party that is receiving the message. This can be useful if the WS requires authentication.
links - Array optional. Links field is an array of link objects. If appropriate, a collection of links to additional external resources for the header.

See the section on localised text elements on how the message deals with languages.

Example

"meta": {
    "copyright": "Copyright 2017 Statistics hotline",
    "id": "b1804c51-1ee3-45a9-bb75-795cd4e06489",
    "prepared": "2018-01-03T12:54:12",
    "test": false,
    "contentLanguages": [ "en", "fr-fr" ],
    "name": "Transmission name",
    "names": {
        # name object #
    },
    "sender": {
        # sender object #
    },
    "receiver": {
        # receiver object #
    },
    "links": [
        {
            # link object #
        }
    ]
}

sender¶

Object. Information about the party that is transmitting the message. Sender contains the following fields:

id - String. A unique identifier of the party.
name - String nullable. A human-readable (best-language-match) name of the sender.
names - Object optional. A list of human-readable localised names of the sender.
contacts - Array optional. A collection of contacts. Provides contact information for the party in regard to the transmission of the message.

See the section on localised text elements on how the message deals with languages.

Example

"sender": {
    "id": "ECB",
    "name": "European Central Bank",
    "names": {
        # name object #
    },
    "contacts": [
        {
            # contact objects #
        }
    ]
}

names¶

Object containing all appropriate localised names, one per object property:

One or more of: IETF Language Tag according to RFC 5646 documentation for specifying locals in HTTP - String. The localised name.

See the section on localised text elements on how the message deals with languages.

Example

{
  "en": "This is an English name",
  "en-GB": "This is a British name",
  "fr": "C'est un nom français"
}

contact¶

Object. A collection of contact details. Each object in the collection may contain the following field:

id - String. Identifier for the resource.
name - String optional. Human-readable (best-language-match) name of the contact.
names - Object optional. Human-readable localised names of the contact.
department - String optional. Human-readable (best-language-match) name of the organisational structure for the contact.
departments - Object optional. Human-readable localised names of the organisational structure for the contact.
role - String optional. Human-readable (best-language-match) name of the responsibility of the contact.
roles - Object optional. Human-readable localised names of the responsibility of the contact.
telephones - Array optional. An array of telephone numbers for the contact.
faxes - Array optional. An array of fax numbers for the contact person.
uris - Array optional. An array of uris. Each uri holds an information URL for the contact.
emails - Array optional. An array of email addresses for the contact person.
x400s - Array optional. An array of X.400 addresses for the contact person.

See the section on localised text elements on how the message deals with languages.

Example

{
  "id": "HOTLINE",
  "name": "Statistics hotline",
  "names": {
    "en": "Statistics hotline",
    "fr": "Service d'assistance téléphonique des Statistiques"
  },
  "department": "Statistics hotline",
  "departments": {
    "en": "Statistics hotline",
    "fr": "Service d'assistance téléphonique des Statistiques"
  },
  "role": "Statistics hotline",
  "roles": {
    "en": "Statistics hotline",
    "fr": "Service d'assistance téléphonique des Statistiques"
  },
  "telephones": ["+00 0 00 00 00 00"],
  "faxes": ["+00 0 00 00 00 01"],
  "uris": ["www.xyz.org"],
  "emails": ["statistics@xyz.org"]
}

receiver¶

Object optional. Information about the party that is receiving the message. This can be useful if the WS requires authentication. Receiver contains the same fields as sender.

link¶

See the section on linking mechanism for all information on links.

data¶

Object optional. Header contains the message’s “primary data”.

[Artefact type] - Array optional. This field is an array of objects of one of the corresponding SDMX Information Model artefact types: dataStructure, metadataStructure, categoryScheme, conceptScheme, codelist, geographicCodelists, geoGridCodelists, valueLists, hierarchy, hierarchyAssociation, agencyScheme, dataProviderScheme, dataProviderScheme, metadataProviderScheme, organisationUnitScheme, dataflow, metadataflow, reportingTaxonomy, provisionAgreement, metadataProvisionAgreement, structureMap, representationMap, conceptSchemeMap, categorySchemeMap, organisationSchemeMap, reportingTaxonomyMap, process, categorisation, dataConstraint, metadataConstraint, customTypeScheme, vtlMappingScheme, namePersonalisationScheme, rulesetScheme, transformationScheme and userDefinedOperatorScheme. Each of the corresponding object properties is allowed at maximum one time. Contains the requested structural information according to the definition of this artefact. For more information, please see:
- Common SDMX artefact properties
- Common properties of SDMX artefacts of base type “ItemScheme”
- dataStructures
- metadataStructures
- categorySchemes
- conceptSchemes
- codelists
- geographicCodelists
- geoGridCodelists
- valueLists
- hierarchies
- hierarchyAssociations
- agencySchemes
- dataProviderSchemes
- dataConsumerSchemes
- metadataProviderSchemes
- organisationUnitSchemes
- dataflows
- metadataflows
- reportingTaxonomies
- provisionAgreements
- metadataProvisionAgreements
- structureMaps
- representationMaps
- conceptSchemeMaps
- categorySchemeMaps
- organisationSchemeMaps
- reportingTaxonomyMaps
- processes
- categorisations
- dataConstraints
- availabilityConstraints
- metadataConstraints
- customTypeSchemes
- vtlMappingSchemes
- namePersonalisationSchemes
- rulesetSchemes
- transformationSchemes
- userDefinedOperatorSchemes

Example

"data": {
    "dataStructures": [
        {
            # dataStructureDefinition object #
        }
    ],
    "dataflows": [
        {
            # dataflow object #
        }
    ]
}

Common SDMX artefact properties¶

All SDMX artefact types share the following common object properties:

id - String. Identifier for the resource.
agencyID - String optional. ID of the agency maintaining this resource.
version - String optional. Version of this resource. Can be a legacy version with two version parts (e.g. ‘1.0’) for fully mutable artefacts, or a semantic version according to SDMX versioning rules with 3 parts (e.g. ‘1.0.0’) for immutable artefacts or with 4 parts (e.g. ‘1.0.0-draft’) for artefacts allowed to change within a certain scope.
name - String. Human-readable (best-language-match) name of the resource.
names - Object optional. Human-readable localised names of the resource.
description - String optional. Human-readable (best-language-match) description of the resource.
descriptions - Object optional. Human-readable localised descriptions (see names) of the resource.
validFrom - String optional. A timestamp from which the version is valid. Values must follow the ISO 8601 syntax for combined dates and times, including time zone.
validTo - String optional. A timestamp from which the version is superseded. Values must follow the ISO 8601 syntax for combined dates and times, including time zone.
isPartialLanguage - Boolean optional. Default: false. Set to true if the structure doesn’t contain the complete set of all available languages, e.g., when obtained as a response to a GET query that requested specific languages through the HTTP header “Accept-Language”.
isExternalReference - Boolean optional. If set to “true” it indicates that the content of the resource is held externally.
annotations - Array optional. Provides a list of annotation objects.
links - Array optional. A collection of links to additional resources for the resource. See the section link. It is recommended to systematically include as the first link a self-referencing hyperlink (link with “rel”=”self”) to indicate the URL address of the resource, and its URN.

See the section on localised text elements on how the message deals with languages.

Note about handling actions:

Structural metadata (artefacts) are maintainable. Thus, when interacting with SDMX Rest web services, the HTTP action verbs GET, PUT and POST are used to indicate the intended action per web request. Consequently, different actions cannot be bundled and executed with “transactional ACIDity”.

Example

{
    "id": "MOBILE_NAVI_PUB",
    "agencyID": "ECB.DISS",
    "version": "1.0.0",
    "name": "Economic concepts",
    "names": {
        "en": "Economic concepts",
        "fr": "Concepts économiques"
    },
    "description": "This is the description of Economic concepts",
    "descriptions": {
        "en": "This is the description of Economic concepts",
        "fr": "Ceci est la description des concepts économiques"
    },
    "validFrom": "2012-05-04",
    "validTo": "2015-05-04",
    "isPartialLanguage": true,
    "isExternalReference": false,
    "annotations":[
        {
            # annotation object#
        }
    ],
    "links": [
        {
            # link object#
        }
    ]
}

annotation¶

Object optional. Provides all information about an annotation.

id - String optional. ID provides a non-standard identification of an annotation. It can be used to disambiguate annotations.
title - String optional. Provides a non-localised title for the annotation.
type - String optional. Type is used to distinguish between annotations designed to support various uses. The types are not enumerated, and these can be freely specified by the creator of the annotations. The definitions and use of annotation types should be documented by their creator.
value - String optional. Provides a non-localised value text for the annotation.
text - String optional. A human-readable (best-language-match) text of the annotation.
texts - Object optional. A list of human-readable localised texts (see names) of the annotation.
links - Array optional. Links field is an array of link objects. If appropriate, a link to an additional external resource which may contain or supplement the annotation.

See the section on localised text elements on how the message deals with languages.

Example

{
    "id": "74747",
    "title": "Sample annotation",
    "type": "reference",
    "value": "123456",
    "text": "Sample annotation text",
    "texts": {
        "en": "Sample annotation text",
        "fr": "Exemple de texte d'annotation"
    },
    "links": [
        {
            # link object #
        }
    ]
}

Common properties of SDMX artefacts of base type “ItemScheme”¶

All SDMX artefacts of base type “ItemScheme” (CategoryScheme, ConceptScheme, Codelist, GeographicCodelist, GeoGridCodelist, AgencyScheme, DataProviderScheme, MetadataProviderSchemes, DataConsumerScheme, OrganisationUnitScheme, ReportingTaxonomy, CustomTypeScheme, VtlMappingScheme, NamePersonalisationScheme, RulesetScheme, UserDefinedOperatorScheme) share the Common SDMX artefact properties.

In addition, they share the following common object properties:

isPartial - Boolean optional. If set to true, it indicates that the resource contains only a sub-set of items.
categories / concepts / codes / geoFeatureSetCodes / geoGridCodes / agencies / dataProviders / dataConsumers / metadataProviders / organisationUnits / reportingCategories / customTypes / vtlMappings / namePersonalisations / rulesets / transformations / userDefinedOperators - Array optional. Provides a list of items if the resource inherits from the ItemScheme. Note that the order of items is significant. In the use case of a submission of a partial list is is necessary to include preceding and succeeding items to allow determining the correct positioning of the submitted items.

Example

{
    "id": "MY_DOMAINS",
    "isPartial": false,
    "categories": [
        {
            # item object #
        }
    ]
}

item¶

Object optional. Abstract generic item within the ItemScheme (if the resource is a CategoryScheme, ConceptScheme, Codelist, GeographicCodelist, GeoGridCodelist, AgencyScheme, DataProviderScheme, MetadataProviderSchemes, DataConsumerScheme, OrganisationUnitScheme, ReportingTaxonomy, CustomTypeScheme, VtlMappingScheme, NamePersonalisationScheme, RulesetScheme or UserDefinedOperatorScheme).

id - String. Identifier for the item.
name - String. Human-readable (best-language-match) name of the item.
names - Object optional. Human-readable localised names of the item.
description - String optional. Human-readable (best-language-match) description of the item. The description is typically longer than the text provided for the name field.
descriptions - Object optional. Human-readable localised descriptions (see names) of the item. A descriptions is typically longer than the text provided for the name field.
parent - String optional. Contains the ID or the URN for the parent of the item (which is itself an item) enabling the reconstruction of the ordered item hierarchy. Prohibited in certain item scheme types.
annotations - Array optional. Provides a list of annotation objects. See the section annotation.
links - Array optional. A collection of links to additional resources for the item. See the section link.
categories / concepts / codes / geoFeatureSetCodes / geoGridCodes / agencies / dataProviders / dataConsumers / metadataProviders / organisationUnits / reportingCategories / customTypes / vtlMappings / namePersonalisations / rulesets / transformations / userDefinedOperators - Array optional. Provides a list of child items of the item. Note that the order of items is significant. In the use case of a submission of a partial list is is necessary to include preceding and succeeding items to allow determining the correct positioning of the submitted items.

See the section on localised text elements on how the message deals with languages.

Example

{
    "id": "01",
    "name": "Population and migration",
    "names": {
        "en": "Population and migration",
        "fr": "Population et migration"
    },
    "description": "Description for Population and migration",
    "descriptions": {
        "en": "Description pour Population et migration",
        "fr": "Description for Population and migration"
    },
    "parent": "T",
    "links":[
        {
            # link object#
        }
    ],
    "annotations": [
        {
            # annotation object #
        }
    ],
    "categories": [
        {
            # item object (recursive) #
        }
    ]
}

dataStructure¶

Object. Describes the structure of a data structure definition. A data structure definition is defined as a collection of metadata concepts, their structure and usage when used to collect or disseminate data.

Field Guide to SDMX-JSON Structure Message 2.1.0 Objects (aligned with SDMX 3.1)¶

message¶

meta¶

sender¶

names¶

contact¶

receiver¶

link¶

data¶

Common SDMX artefact properties¶

annotation¶

Common properties of SDMX artefacts of base type “ItemScheme”¶

item¶

dataStructure¶

dataStructureComponents¶

attributeList¶

attribute¶

attributeRelationship¶

localRepresentation¶

enumerationFormat¶

format¶

sentinelValue¶

metadataAttributeUsage¶

dimensionList¶

dimension¶

timeDimension¶

timeDimensionFormat¶

group¶

measureList¶

measure¶

metadataStructure¶

metadataStructureComponents¶

metadataAttributeList¶

metadataAttribute¶

categoryScheme¶

conceptScheme¶

coreRepresentation¶

isoConceptReference¶

codelist¶

geographicCodelist¶

geoGridCodelist¶

valueList¶

hierarchy¶

hierarchyAssociation¶

agencyScheme¶

dataProviderScheme¶

dataConsumerScheme¶

metadataProviderScheme¶

organisationUnitScheme¶

dataflow¶

metadataflow¶

reportingTaxonomy¶

provisionAgreement¶

metadataProvisionAgreement¶

structureMap¶

representationMap¶

conceptSchemeMap¶

categorySchemeMap¶

organisationSchemeMap¶

reportingTaxonomyMap¶

process¶

categorisation¶

dataConstraint¶

availabilityConstraint¶

metadataConstraint¶

constraintAttachment¶

cubeRegion¶

ComponentValueSet¶

TimeRangeValue¶

TimePeriodRange¶

SimpleComponentValue¶

CubeRegionKey¶

dataKeySet¶

dataKey¶

dataKeyValue¶

dataComponentValueSet¶

DataComponentValue¶

metadataTargetRegion¶

MetadataAttributeValueSet¶

customTypeScheme¶