JSON was introduced as a transmission format for both structures and data as an addition to SDMX 2.1. Unlike XML there are only two versions of the data message.
In this unit we’ll look at the general principles of the JSON data message and note the differences between the two versions.
The SDMX-JSON v1 data message specification was added to SDMX 2.1 principally to satisfy the use case for data dissemination on the Internet where JSON is easier to use for websites and web data publication applications.
SDMX-JSON differs from its XML counterparts in that it transmits both the classification identifiers and their labels. This has the advantage of packaging all the information required to display a dataset in a single message. The XML messages by contrast require applications also have access to the dataset’s structural metadata in order to decode enumerated values in particular.
The basic structure of a message is as follows:
{
"meta" : { header information },
"data" : {
"datasets" : [ {array of one or more datasets} ],
"structures" : { the structural metadata for the datasets}
}
}
The datasets element carries an array of one or more datasets with their accompanying series and observation values. However, the metadata in terms of the component Ids, Names, Descriptions, and the observation time period values are under the structures element and referenced using a zero-based index string of the form 0:0:1:0.
The exerpt of a single series below shows this in context. The 0:0:1:0 indicates there are four dimensions respectively referencing the first, first, second and first codes in their codelists defined in the structures section.
"series": {
"0:0:1:0": {
"attributes": [],
"observations": {
"0": ["102"],
"1": ["114"],
"2": ["114"],
"3": ["114"],
"4": ["103"],
"5": ["114"],
"6": ["111"],
"7": ["119"],
"8": ["114"],
"9": ["111"]
}
},
This approach of decoupling the metadata from the data is designed to minimise the size of the message by avoiding duplication.
The SDMX-JSON v2 data message was introduced with SDMX 3.0 and follows the same principles and structure but with additions to support the new information model features, principally:
SDMX-JSON can be used for any data transmission use case, but is best suited for web data discovery and retrieval applications because it carries all of the data and metadata needed to build an effective user interface.
The SDMX-JSON message is equivalent to SDMX-ML Generic in that its JSON schema is fixed and not dependent on the datasets’ DSDs.
Like SDMX-ML, the ‘series keys only’ messages carry just the series keys and omit the observation values.
In the next unit we’ll look at the options for using CSV for SDMX data transmission.