version

string reserved word required

The value of this property is "2.0".

{
   "version" : "2.0",
   …
}

class

string reserved word required

The value of this property is "dataset".

{
   "version" : "2.0",
   "class" : "dataset",
   "label" : "Unemployment rate in the OECD countries 2003-2014",
   "source" : "Economic Outlook No 92 - December 2012 - OECD Annual Projections",
   "updated" : "2012-11-27",
   "id" : ["concept", "area", "year"],
   "size" : [1, 36, 12],
   "dimension" : { … },
   "value" : [ … ]
}

id

array reserved word required

It contains an ordered list of dimension IDs.

{
   "version" : "2.0",
   "class": "dataset",
   "id" : ["metric", "time", "geo", "sex"],
   …
}

Dimension IDs can be any string and have no special meaning in JSON-stat.

size

array reserved word required

It contains the number (integer) of categories (possible values) of each dimension in the dataset. It has the same number of elements and in the same order as in id.

{
   "version" : "2.0",
   "class" : "dataset",
   "id" : ["metric", "time", "geo", "sex"],
   "size" : [1, 1, 1, 3],
   …
}

value

array object reserved word required

It contains the data sorted according to the dataset dimensions. It usually takes the form of an array where missing values are expressed as nulls.

{
   "version" : "2.0",
   "class" : "dataset",
   "value" : [105.3, 104.3, null, 177.2, …],
   …
}

When too many cube cells are empty (sparse cube), the value array is populated with nulls.

{
   "version" : "2.0",
   "class" : "dataset",
   "value" : [1.3587, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, 1.5849],
   …
}

To avoid this, the value property can take the form of an object.

{
   "version" : "2.0",
   "class" : "dataset",
   "value" : { "0": 1.3587, "18": 1.5849 },
   …
}

Value order follows the “What does not change, first” criterion. According to this criterion, values are ordered by combination of category dimensions keeping fixed the first categories of the first dimensions and iterating through the categories of the last dimension in the id array (and so forth).

For example, if we have three dimensions (A, B and C) with 3, 2 and 4 categories respectively, the values should be ordered iterating first by the 4 categories of C, then by the 2 categories of B and finally by the 3 categories of A:

A1B1C1   A1B1C2   A1B1C3   A1B1C4
A1B2C1   A1B2C2   A1B2C3   A1B2C4

A2B1C1   A2B1C2   A2B1C3   A1B1C4
A2B2C1   A2B2C2   A2B2C3   A2B2C4

A3B1C1   A3B1C2   A3B1C3   A3B1C4
A3B2C1   A3B2C2   A3B2C3   A3B2C4

This flattening method is known as row-major order.

The order.json file is provided as a JSON-stat example of value and dimension sorting.

The value property is required but it can be an empty array (for example, when a dataset response is used to only disseminate metadata).

status

array object string reserved word optional

It contains metadata at the observation level. When it takes an array form of the same size of value, it assigns a status to each data by position.

{
   "version" : "2.0",
   "class" : "dataset",
   "value" : [100, null, 102, 103, 104],
   "status" : ["a", "m", "a", "a", "p"],
   …
}

To assign the same status to all data, a string can be used.

{
   "version" : "2.0",
   "class" : "dataset",
   "value" : [100, 99, 102, 103, 104],
   "status" : "e",
   …
}

An object can also be used to provide status information for specific cells.

{
   "version" : "2.0",
   "class" : "dataset",
   "value" : [100, null, 102, 103, 104],
   "status" : { "1" : "m" },
   …
}

Meaning can be assigned to the status codes using extension.

dimension

object reserved word required

JSON-stat follows a cube model: the values are organized in cells, and a cell is the intersection of various dimensions. The dimension property contains information about the dimensions of the dataset.

{
   "version" : "2.0",
   "class" : "dataset",
   "value" : [4729, 4832, 9561],
   "dimension" : {
      …
   }
}

dimension must have properties (see dimension ID) with the same names of each element in the id array.

dimension ID

object free word required

It is used to describe a particular dimension. The name of this object must be one of the strings in the id array. There must be one and only one dimension ID object for every dimension in the id array.

"dimension" : {
   "metric" : { … },
   "time" : { … },
   "geo" : { … },
   "sex" : { … },
   …
}

category

object reserved word required

It is used to describe the possible values of a dimension.

"sex" : {
   "category" : { … }
}

index

object array reserved word required (optional in special cases)

It is used to order the possible values (categories) of a dimension. The order of the categories and the order of the dimensions themselves determine the order of the data in the value array. While the dimensions’ order has only this functional role (and therefore any order chosen by the provider is valid), the categories’ order has also a presentation role: it is assumed that the categories are sorted in a meaningful order and that the consumer can rely on it when displaying the information.

To provide the category IDs and their order, an array can be used.

"sex" : {
   "category" : {
      "index" : ["M", "F", "T"]
   }
}

An object that attaches a position to every ID can also be used.

"sex" : {
   "category" : {
      "index" : {
          "M" : 0,
          "F" : 1,
          "T" : 2
      }
   }
}

label

string object reserved word required (optional in special cases)

It is used to assign a very short (one line) descriptive text to IDs at different levels of the response tree. It is language-dependent.

When it is a root property or a child of dimension ID, it is a string.

{
   "version" : "2.0",
   "class" : "dataset",
   "label" : "Tuvalu population by sex in the 2002 Census",
   "dimension" : {
      "sex" : {
          "label" : "sex",
          …
      },
      …
   },
   …
}

When it is a child of category, it is an object where the keys are the category IDs and the values are the labels.

"sex" : {
   "label" : "sex",
   "category" : {
      "index" : {
         "M" : 0,
         "F" : 1,
         "T" : 2
      },
      "label" : {
         "M" : "men",
         "F" : "women",
         "T" : "total"
      }
   }
}

label content should be written in lowercase except when it is a dataset label. It’s the client’s job to capitalize it when needed according to the display context.

updated

string reserved word optional

It contains the update time of the dataset. It is a string representing a date in an ISO 8601 format recognized by the Javascript Date.parse method (see ECMA-262 Date Time String Format).

{
   "version" : "2.0",
   "class" : "dataset",
   "updated" : "2012-01-22T12:30:02Z",
   …
}

source

string reserved word optional

It contains a language-dependent short text describing the source of the dataset.

{
   "version" : "2.0",
   "class" : "dataset",
   "source" : "Economic Outlook No 92 - December 2012 - OECD Annual Projections",
   …
}

extension

object reserved word optional

extension allows JSON-stat to be extended for particular needs. Providers are free to define where they include this property and what children are allowed in each case.

{
   "version" : "2.0",
   "class" : "dataset",
   "label" : "Unemployment rate in the OECD countries 2003-2014",
   "source" : "Economic Outlook No 92 - December 2012 - OECD Annual Projections",
   "updated" : "2012-11-27",

   "extension" : {
      "contact" : "EcoOutlook@oecd.org",
      "metadata" : [
          {
               "title" : "Economic Outlook Policy and other assumptions underlying the projections Box 1.2 in General assessment",
               "href" : "http://www.oecd.org/eco/economicoutlookanalysisandforecasts/EO92macroeconomicsituation.pdf"
          },
          {
               "title" : "Economic Outlook Sources and Methods",
               "href" : "http://www.oecd.org/document/22/0,3343,en_2649_34109_33702486_1_1_1_1,00.html"
          },
          {
               "title" : "Database inventory (forthcoming)",
               "href" : "http://www.oecd.org/eco/databaseinventory"
          },
          {
               "title" : "OECD Glossary",
               "href" : "http://stats.oecd.org/glossary/"
          }
      ]
   },

   "value" : [ … ],
   "id" : [ … ],
   "size" : [ … ],
   "dimension" : { … }
}