JsonStat2

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/stat-fi/json-schema/stat-fi-json-stat2-schema.json",
  "title": "JsonStat2",
  "description": "Represents a JSON-stat 2.0 dataset response. See https://json-stat.org/ for full specification details.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stat-fi-pxapi-beta-openapi.yml#/components/schemas/JsonStat2",
  "required": [
    "class",
    "dimension",
    "id",
    "label",
    "size",
    "source",
    "updated",
    "value",
    "version"
  ],
  "type": "object",
  "properties": {
    "version": {
      "minLength": 1,
      "type": "string",
      "description": "The JSON-stat version string."
    },
    "class": {
      "minLength": 1,
      "type": "string",
      "description": "The object class of the JSON-stat response. For data queries this is always 'dataset'.",
      "readOnly": true
    },
    "id": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ordered list of dimension identifiers. The order defines the major-to-minor traversal used to produce the PxApi.Models.JsonStat.JsonStat2.Value array."
    },
    "label": {
      "minLength": 1,
      "type": "string",
      "description": "Short, language-dependent dataset label."
    },
    "note": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "Optional annotations about the dataset (language dependent)."
    },
    "source": {
      "type": [
        "string",
        "null"
      ],
      "description": "The source of the dataset. Language-dependent."
    },
    "updated": {
      "type": [
        "string",
        "null"
      ],
      "description": "Timestamp indicating when the dataset was last updated (ISO 8601, UTC recommended)."
    },
    "dimension": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/Dimension"
      },
      "description": "Map from dimension identifier to its metadata (categories, labels, units, etc.)."
    },
    "value": {
      "type": "array",
      "items": {
        "type": [
          "number",
          "null"
        ],
        "format": "double"
      },
      "description": "Flattened array of data values following the Cartesian product of dimensions in the order given by PxApi.Models.JsonStat.JsonStat2.Id. Missing values are encoded as null."
    },
    "status": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {
        "type": "string"
      },
      "description": "Optional status information for data values. Keys are zero-based indexes into PxApi.Models.JsonStat.JsonStat2.Value; values are arbitrary status codes."
    },
    "extension": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {},
      "description": "Optional extension object for additional, non-standard metadata. Keys and value types are unrestricted."
    },
    "size": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int32"
      },
      "description": "Size of each dimension in the same order as PxApi.Models.JsonStat.JsonStat2.Id. Product of all elements equals PxApi.Models.JsonStat.JsonStat2.Value length."
    },
    "role": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "description": "Optional mapping declaring special roles for certain dimensions (e.g. time, metric). Each role maps to a list of dimension identifiers."
    }
  },
  "additionalProperties": false,
  "$defs": {
    "Category": {
      "required": [
        "index",
        "label"
      ],
      "type": "object",
      "properties": {
        "index": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The index array of the category."
        },
        "label": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "The labels for each category value."
        },
        "note": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "description": "Possible annotations related to some category values."
        },
        "unit": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": {
            "$ref": "#/$defs/Unit"
          },
          "description": "The unit of measurement for each category."
        }
      },
      "additionalProperties": false,
      "description": "Represents a category in a dimension."
    },
    "Dimension": {
      "required": [
        "category",
        "label"
      ],
      "type": "object",
      "properties": {
        "label": {
          "minLength": 1,
          "type": "string",
          "description": "The label of the dimension."
        },
        "note": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "Annotations about the dimension. Language-dependent."
        },
        "category": {
          "$ref": "#/$defs/Category"
        }
      },
      "additionalProperties": false,
      "description": "Represents a dimension in the JSON-stat format."
    },
    "Unit": {
      "required": [
        "decimals",
        "label"
      ],
      "type": "object",
      "properties": {
        "label": {
          "minLength": 1,
          "type": "string",
          "description": "Localized label of the unit (e.g., Persons)."
        },
        "symbol": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional symbol for the unit (e.g., %, �)."
        },
        "position": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional symbol position relative to value. Allowed values: start, end."
        },
        "decimals": {
          "type": "integer",
          "description": "Number of decimals to display for this unit (>= 0).",
          "format": "int32"
        }
      },
      "additionalProperties": false,
      "description": "Represents a unit of measurement in the JSON-stat format."
    }
  }
}