Axis

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://opendevelopmentstandards.org/schema/1.0.0-rc.2/core/Axis.json",
  "title": "Axis",
  "description": "An axis: one dimension of a Value's amount, such as frequency, time, height or wind speed. It gives the coordinate of each element along it.",
  "type": "object",
  "properties": {
    "quantity": {
      "type": "string",
      "pattern": "^[a-z0-9]+(_[a-z0-9]+)*(\\.[a-z0-9]+(_[a-z0-9]+)*)*$",
      "x-ods-vocabulary": "*/quantities",
      "description": "What the axis measures, as a code from a quantities vocabulary, such as `frequency` or `height`."
    },
    "name": {
      "type": "string",
      "description": "A readable name, when two axes have the same quantity."
    },
    "unit": {
      "type": "string",
      "x-ods-vocabulary": "*/units",
      "description": "The unit of the coordinates. Leave it out when they are codes or have no unit."
    },
    "values": {
      "type": "array",
      "minItems": 1,
      "items": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "description": "The coordinate of each element, in order: numbers, date-times or codes. For bins, the nominal centre of each bin."
    },
    "start": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "format": "date-time"
        }
      ],
      "description": "For a regular axis: the first coordinate, a number or a date-time."
    },
    "step": {
      "anyOf": [
        {
          "type": "number",
          "not": {
            "const": 0
          }
        },
        {
          "type": "string",
          "pattern": "^-?P(?!$)(\\d+(\\.\\d+)?Y)?(\\d+(\\.\\d+)?M)?(\\d+(\\.\\d+)?W)?(\\d+(\\.\\d+)?D)?(T(?=\\d)(\\d+(\\.\\d+)?H)?(\\d+(\\.\\d+)?M)?(\\d+(\\.\\d+)?S)?)?$"
        }
      ],
      "description": "For a regular axis: the distance from one coordinate to the next, a number or an ISO 8601 duration. A negative step runs the coordinates down, such as the rows of a raster stored north up. It is never 0."
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "description": "For a regular axis: the number of elements."
    },
    "vocabulary": {
      "type": "string",
      "description": "When the coordinates are codes: the vocabulary they come from, as `<module>/<name>`.",
      "pattern": "^[a-z0-9_]+/[a-z0-9_]+$"
    },
    "bins": {
      "$ref": "#/$defs/Bins"
    }
  },
  "required": [
    "quantity"
  ],
  "oneOf": [
    {
      "properties": {
        "values": true
      },
      "required": [
        "values"
      ]
    },
    {
      "properties": {
        "start": true,
        "step": true,
        "count": true
      },
      "required": [
        "start",
        "step",
        "count"
      ]
    }
  ],
  "patternProperties": {
    "^x-": {}
  },
  "unevaluatedProperties": false,
  "$defs": {
    "Bins": {
      "type": "object",
      "properties": {
        "set": {
          "type": "string",
          "pattern": "^[a-z0-9]+(_[a-z0-9]+)*(\\.[a-z0-9]+(_[a-z0-9]+)*)*$",
          "x-ods-vocabulary": "*/bin_sets",
          "description": "A standard set the bins come from, such as `octave` or `third_octave`."
        },
        "width": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "A fixed bin width, centred on each coordinate, in the axis's unit. A grid's cell size is its bin width."
        },
        "edges": {
          "type": "array",
          "minItems": 2,
          "items": {
            "type": "number"
          },
          "description": "The bin edges in order: one more than the coordinates."
        },
        "statistic": {
          "$ref": "Statistic.json",
          "description": "How each bin's value was made from finer data, such as an energy sum of three third-octave bands. Leave it out when each value is at the bin's centre."
        },
        "count": {
          "type": "integer",
          "minimum": 1,
          "description": "How many finer points or bins each bin combines."
        }
      },
      "description": "Present when each element stands for a range of the axis (a bin), not one point.",
      "patternProperties": {
        "^x-": {}
      },
      "unevaluatedProperties": false
    }
  },
  "examples": [
    {
      "quantity": "frequency",
      "unit": "Hz",
      "values": [
        63,
        125,
        250,
        500,
        1000,
        2000,
        4000,
        8000
      ],
      "bins": {
        "set": "octave"
      }
    },
    {
      "quantity": "time",
      "start": "2025-07-01T00:00:00Z",
      "step": "PT1H",
      "count": 8760
    },
    {
      "quantity": "easting",
      "unit": "m",
      "start": 512005,
      "step": 10,
      "count": 200,
      "bins": {
        "width": 10
      }
    },
    {
      "quantity": "complex_part",
      "values": [
        "real",
        "imaginary"
      ]
    }
  ],
  "x-ods-status": "draft",
  "x-ods-kind": "datatype",
  "x-ods-module": "core",
  "x-ods-changes": {
    "0.1.0": "First version."
  }
}