jsonstat

Reading JSON-stat datasets

JSON-stat is a JSON format for statistical data used by official statistics providers (Idescat, Eurostat, national statistical institutes). Its key feature — and the most common source of mistakes — is that all cell values live in a single flat array whose order is determined by the dataset's dimensions. Follow this guide to read values reliably.

Dataset structure

A JSON-stat dataset ("class": "dataset") has these essential properties:

• id: ORDERED list of dimension names. This order governs all position calculations (NOT the key order of the dimension object, which is irrelevant).
• size: number of categories per dimension, in the same order as id.
• dimension.{name}.category.index: 0-based position of each category code within the dimension. It comes in one of two forms:
  • an object {code: position}, e.g. {"M": 0, "F": 1}, or
  • a list [code0, code1, ...] (the position is the list index). ALWAYS use this index; never assume alphabetical or label order. If category.index is absent and category.label has a single key, the dimension has one category at position 0.
• dimension.{name}.category.label: map from category code to human-readable label.
• value: FLAT array with all cell values in row-major order: the LAST dimension of id varies fastest and the first varies slowest.
• status: flags special values (e.g. provisional or confidential data). It can be a string (applies to all values), an array (parallel to value) or an object keyed by value position.

Reading the value of a category combination

To read the value for a specific combination of categories (one per dimension):

1. For each dimension, take the position p of the chosen category from category.index.
2. Compute each dimension's stride = product of the size of ALL later dimensions (in id order); the last dimension has stride = 1.
3. offset = sum of (p × stride) over all dimensions.
4. The value is value[offset].