jdata_format_schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "JData JSON Schema",
  "description": "JSON schema for JData - a general-purpose data annotation and interchange format (Draft-4)",
  "type": "object",
  "properties": {
    "_DataGroup_": {
      "$ref": "#/definitions/DataGroupDef"
    },
    "_Dataset_": {
      "$ref": "#/definitions/DatasetDef"
    },
    "_DataRecord_": {
      "$ref": "#/definitions/DataRecordDef"
    },
    "_DataInfo_": {
      "$ref": "#/definitions/DataInfoDef"
    },
    ".datainfo": {
      "$ref": "#/definitions/DataInfoDef",
      "description": "CouchDB-compatible alias for _DataInfo_"
    },
    "_DataSchema_": {
      "$ref": "#/definitions/DataSchemaDef"
    },
    ".dataschema": {
      "$ref": "#/definitions/DataSchemaDef",
      "description": "CouchDB-compatible alias for _DataSchema_"
    },
    "_DataLink_": {
      "$ref": "#/definitions/DataLinkDef"
    },
    "_DataAnchor_": {
      "type": "string",
      "description": "Named anchor for referencing by _DataLink_"
    },
    "_NaN_": {
      "type": "string",
      "enum": ["_NaN_"],
      "description": "IEEE 754 NaN constant"
    },
    "_Inf_": {
      "type": "string",
      "enum": ["_Inf_", "+_Inf_"],
      "description": "IEEE 754 positive infinity constant"
    },
    "-_Inf_": {
      "type": "string",
      "enum": ["-_Inf_"],
      "description": "IEEE 754 negative infinity constant"
    },
    "_ByteStream_": {
      "$ref": "#/definitions/ByteStreamDef"
    }
  },
  "patternProperties": {
    "^_DataGroup_\\(.+\\)$": {
      "$ref": "#/definitions/DataGroupDef"
    },
    "^_Dataset_\\(.+\\)$": {
      "$ref": "#/definitions/DatasetDef"
    },
    "^_DataRecord_\\(.+\\)$": {
      "$ref": "#/definitions/DataRecordDef"
    },
    "^_TableData_\\(.+\\)$": {
      "$ref": "#/definitions/TableDataDef"
    },
    "^_TreeData_\\(.+\\)$": {
      "$ref": "#/definitions/TreeDataDef"
    },
    "^_LinkedList_\\(.+\\)$": {
      "$ref": "#/definitions/LinkedListDef"
    },
    "^_LinkedList_\\(.+\\)(::.*)?$": {
      "$ref": "#/definitions/LinkedListDef"
    },
    "^_GraphData_\\(.+\\)_$": {
      "$ref": "#/definitions/GraphDataDef"
    },
    "^_ListNode_\\(.+\\)$": {
      "$ref": "#/definitions/ListNodeDef"
    },
    "^_TreeNode_\\(.+\\)$": {
      "$ref": "#/definitions/TreeNodeDef"
    },
    "^[^_].*::[^:]*$": {
      "description": "Inline metadata annotation: item_name::Property1=value1,Property2=value2,..."
    }
  },
  "additionalProperties": true,
  "definitions": {
    "DataGroupDef": {
      "title": "DataGroup",
      "description": "Container for organizing logically connected datasets",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": true
        }
      ]
    },
    "DatasetDef": {
      "title": "Dataset",
      "description": "Container for logically connected data records",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": true
        }
      ]
    },
    "DataRecordDef": {
      "title": "DataRecord",
      "description": "Container for meaningful data units",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": true
        }
      ]
    },
    "DataInfoDef": {
      "type": "object",
      "title": "DataInfo",
      "description": "Metadata record for data annotation",
      "properties": {
        "Version": {
          "type": "string",
          "description": "Version string of the data or the generating software"
        },
        "Author": {
          "type": "string",
          "description": "Name(s) of the data creator(s)"
        },
        "Comment": {
          "type": "string",
          "description": "Free-text description"
        },
        "UniqueID": {
          "type": "string",
          "description": "Globally unique identifier (e.g., UUID v4)"
        },
        "CreateTime": {
          "type": "string",
          "description": "ISO 8601 creation timestamp (e.g., \"2024-03-15T14:32:00Z\")"
        },
        "ModifiedTime": {
          "type": "string",
          "description": "ISO 8601 last-modification timestamp"
        },
        "License": {
          "type": "string",
          "description": "SPDX license identifier (e.g., \"CC-BY-4.0\", \"Apache-2.0\")"
        },
        "GeneratedBy": {
          "type": "string",
          "description": "Name and version of the software that produced the data"
        },
        "DerivedFrom": {
          "type": "string",
          "description": "URI or identifier of the source data from which this was derived"
        },
        "SourceFormat": {
          "type": "string",
          "description": "Original file format before conversion (e.g., \"NIfTI-1\", \"HDF5\")"
        },
        "_DataAnchor_": {
          "type": "string",
          "description": "Named anchor for referencing"
        }
      },
      "additionalProperties": true
    },
    "DataSchemaDef": {
      "title": "DataSchema",
      "description": "Associates a JSON Schema document with a data node for formal structure validation. The value must be either a valid JSON Schema object or a URI string pointing to an external schema document. Parsers that do not recognize _DataSchema_ must silently ignore it.",
      "oneOf": [
        {
          "type": "string",
          "description": "URI pointing to an external JSON Schema document"
        },
        {
          "type": "object",
          "description": "Inline JSON Schema object",
          "properties": {
            "$schema": {
              "type": "string"
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "DataLinkDef": {
      "title": "DataLink",
      "description": "Reference to internal or external data",
      "oneOf": [
        {
          "type": "string",
          "description": "URI path to referenced data"
        },
        {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Local index vector reference"
        },
        {
          "type": "object",
          "properties": {
            "URI": {
              "type": "string",
              "description": "URI path to referenced data"
            },
            "Parameters": {
              "type": "string",
              "description": "JSONPath expression to a specific element"
            },
            "MaxRecursion": {
              "type": "integer",
              "description": "Maximum recursion depth for link resolution"
            }
          },
          "required": ["URI"],
          "additionalProperties": true
        }
      ]
    },
    "ArrayTypeDef": {
      "type": "string",
      "enum": [
        "uint8",   "int8",
        "uint16",  "int16",
        "uint32",  "int32",
        "uint64",  "int64",
        "half",    "single",  "double",
        "float16", "float32", "float64",
        "byte", "char", "logical"
      ],
      "description": "Numeric data type. float16/float32/float64 are aliases for half/single/double (NumPy/Arrow interoperability). byte/char/logical are aliases for uint8."
    },
    "ArrayShapeIdDef": {
      "type": "string",
      "enum": [
        "diag",
        "upper",        "lower",
        "uppersymm",    "lowersymm",
        "upperband",    "lowerband",
        "uppersymmband","lowersymmband",
        "band",
        "toeplitz",
        "upperherm",    "lowerherm",
        "upperhermband","lowerhermband",
        "circulant",
        "hankel",
        "identity",
        "zero",
        "range"
      ],
      "description": "Special matrix/array shape identifier"
    },
    "AnnotatedArrayDef": {
      "type": "object",
      "title": "AnnotatedArray",
      "description": "JData annotated N-dimensional array format",
      "properties": {
        "_ArrayType_": {
          "$ref": "#/definitions/ArrayTypeDef"
        },
        "_ArraySize_": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0
          },
          "minItems": 1,
          "description": "Dimensions of the N-D array"
        },
        "_ArrayOrder_": {
          "type": "string",
          "enum": ["r", "row", "c", "col", "column"],
          "description": "Array serialization order: row-major (r/row, default) or column-major (c/col/column)"
        },
        "_ArrayData_": {
          "description": "Raw array data. When _ArrayChunks_ is present, this is a 1-D array of per-chunk payloads in row-major order."
        },
        "_ArrayIsComplex_": {
          "type": "boolean",
          "description": "True if array contains complex numbers (real and imaginary parts interleaved)"
        },
        "_ArrayIsSparse_": {
          "type": "boolean",
          "description": "True if array is sparse (row-indices, col-indices, values format)"
        },
        "_ArrayLabel_": {
          "type": "array",
          "description": "Dimension labels. Each element is a string name or a [name, start, width] tuple.",
          "items": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "array",
                "items": [
                  { "type": "string" },
                  { "type": "integer" },
                  { "type": "integer" }
                ],
                "minItems": 1
              }
            ]
          }
        },
        "_ArrayCoords_": {
          "type": "object",
          "description": "Maps each dimension name (as defined in _ArrayLabel_) to a 1-D coordinate array of the same length as that dimension. Mirrors the coordinate-variable model of xarray and NetCDF.",
          "additionalProperties": {
            "oneOf": [
              {
                "type": "array",
                "description": "Plain 1-D coordinate array"
              },
              {
                "$ref": "#/definitions/AnnotatedArrayDef",
                "description": "Annotated JData array (preserves binary type information)"
              }
            ]
          }
        },
        "_ArrayUnits_": {
          "oneOf": [
            {
              "type": "string",
              "description": "Single unit string applied uniformly to all dimensions (UDUNITS-2 convention, e.g. \"mm\", \"ms\", \"kg/m^3\"). An empty string denotes dimensionless or undefined."
            },
            {
              "type": "array",
              "items": { "type": "string" },
              "description": "Per-dimension unit strings with length equal to length(_ArraySize_)"
            }
          ],
          "description": "Physical unit(s) of the array dimensions (UDUNITS-2 convention)"
        },
        "_ArrayFillValue_": {
          "type": "number",
          "description": "Scalar sentinel for missing or invalid entries of the same numeric type as _ArrayType_. Important for integer types where IEEE 754 NaN cannot be represented. Both _ArrayFillValue_ and NaN entries (if present) are treated as missing."
        },
        "_ArrayShape_": {
          "oneOf": [
            {
              "$ref": "#/definitions/ArrayShapeIdDef"
            },
            {
              "type": "array",
              "items": [
                { "$ref": "#/definitions/ArrayShapeIdDef" }
              ],
              "additionalItems": {
                "type": "number"
              },
              "description": "Shape ID followed by optional numeric parameters (e.g. bandwidth for band/toeplitz)"
            }
          ],
          "description": "Special matrix or array shape descriptor. Shapes: diag, upper/lower (triangular), uppersymm/lowersymm, band variants, toeplitz, circulant, hankel, identity, zero, range."
        },
        "_ArrayChunks_": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 1
          },
          "description": "Tile (chunk) shape for partitioning the pre-processed array into independently compressible blocks. Length must equal the number of dimensions of the pre-processed array. When present, _ArrayData_ or _ArrayZipData_ becomes a 1-D array of per-chunk payloads in row-major order. The last chunk along any dimension may be smaller than the declared shape."
        },
        "_ArrayZipType_": {
          "type": "string",
          "enum": [
            "zlib", "gzip", "bz2", "lzma",
            "zstd", "lz4",
            "blosc2", "blosc2lz4", "blosc2lz4hc",
            "blosc2blosclz", "blosc2zstd", "blosc2zlib",
            "base64"
          ],
          "description": "Compression codec identifier following the Numcodecs registry (also used by Zarr). Note: zlib (RFC 1950) and gzip (RFC 1952) are distinct formats. Only Blosc2 (not Blosc v1) is supported. blosc2 defaults to BloscLZ internal codec."
        },
        "_ArrayZipSize_": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0
              },
              "description": "Dimensions of the pre-processed array (multi-dimensional)"
            },
            {
              "type": "integer",
              "minimum": 0,
              "description": "Total element count of the pre-processed array (scalar shorthand)"
            }
          ],
          "description": "Dimensions of the pre-processed array before compression. When _ArrayChunks_ is present, gives the shape of a full (non-boundary) chunk."
        },
        "_ArrayZipData_": {
          "oneOf": [
            {
              "type": "string",
              "description": "Base64-encoded compressed byte stream (unchunked array)"
            },
            {
              "type": "array",
              "items": { "type": "string" },
              "description": "1-D array of Base64-encoded per-chunk compressed payloads (chunked array, when _ArrayChunks_ is present)"
            }
          ],
          "description": "Compressed and Base64-encoded array data"
        },
        "_ArrayZipEndian_": {
          "type": "string",
          "enum": ["little", "big"],
          "description": "Byte order of the array elements before compression (default: little-endian)"
        },
        "_ArrayZipLevel_": {
          "type": "number",
          "description": "Compression level (typically 0-9, interpretation is codec-dependent)"
        },
        "_ArrayZipOptions_": {
          "type": "object",
          "description": "Additional codec-specific parameters (e.g., for Blosc2: typesize, clevel, shuffle, nthreads)",
          "additionalProperties": true
        },
        "_ArrayShuffle_": {
          "type": "integer",
          "not": { "enum": [0] },
          "description": "Byte or bit shuffle applied before compression. A positive integer N specifies byte shuffle with stride N (e.g., 4 reorders [1,2,3,4,5,6,7,8,...] to [1,5,...,2,6,...,3,7,...,4,8,...]). A negative integer -N specifies bit-wise shuffle with spacing N. Must be applied before compression; unshuffle applied on decompression."
        }
      },
      "required": ["_ArrayType_", "_ArraySize_"],
      "if": {
        "properties": {
          "_ArrayShape_": { "type": "string", "enum": ["zero"] }
        },
        "required": ["_ArrayShape_"]
      },
      "then": {},
      "else": {
        "oneOf": [
          { "required": ["_ArrayData_"] },
          { "required": ["_ArrayZipData_", "_ArrayZipType_", "_ArrayZipSize_"] }
        ]
      },
      "not": {
        "allOf": [
          { "required": ["_ArrayData_"] },
          { "required": ["_ArrayZipData_"] }
        ]
      },
      "additionalProperties": false
    },
    "MapDataDef": {
      "type": "object",
      "title": "MapData",
      "description": "Associative array (hash/map) with non-string keys",
      "properties": {
        "_MapData_": {
          "type": "array",
          "items": {
            "type": "array",
            "minItems": 2
          },
          "description": "Array of [key, value, ...] pairs"
        }
      },
      "required": ["_MapData_"],
      "additionalProperties": true
    },
    "TableColumnDef": {
      "oneOf": [
        {
          "type": "string",
          "description": "Column/row name (plain string form)"
        },
        {
          "type": "object",
          "properties": {
            "DataName": {
              "type": "string",
              "description": "Column or row name"
            },
            "DataType": {
              "type": "string",
              "enum": [
                "uint8",   "int8",
                "uint16",  "int16",
                "uint32",  "int32",
                "uint64",  "int64",
                "half",    "single",  "double",
                "float16", "float32", "float64",
                "string", "bool", "blob", "datetime"
              ],
              "description": "Data type of this column/row. datetime values are ISO 8601 strings; values without an explicit time-zone offset are interpreted as UTC."
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "TableDataDef": {
      "type": "object",
      "title": "TableData",
      "description": "2D table data structure",
      "properties": {
        "_TableCols_": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TableColumnDef"
          },
          "description": "Column names and types"
        },
        "_TableRows_": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TableColumnDef"
          },
          "description": "Row names and types"
        },
        "_TableRecords_": {
          "type": "array",
          "items": {
            "type": "array"
          },
          "description": "2D array storing table entries (rows of column values)"
        },
        "_TableIndex_": {
          "oneOf": [
            {
              "type": "string",
              "description": "Single column name forming the unique row index"
            },
            {
              "type": "array",
              "items": { "type": "string" },
              "minItems": 1,
              "description": "Ordered list of column names forming a composite unique row index"
            }
          ],
          "description": "Names of one or more columns in _TableCols_ that together form the unique row index (analogous to a SQL primary key or pandas DataFrame.index). If absent, the implicit index is the 1-based row position."
        },
        "_TableSortOrder_": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Declared sort order of the stored records. Each element is a column name; a leading \"-\" prefix denotes descending order (e.g., [\"-Age\", \"Height\"] means descending Age then ascending Height). Parsers may rely on this to skip re-sorting for binary-search or merge operations."
        }
      },
      "required": ["_TableRecords_"],
      "additionalProperties": true
    },
    "EnumDataDef": {
      "type": "object",
      "title": "EnumData",
      "description": "Enumeration (categorical) data structure for arrays with repeated values from a finite set",
      "properties": {
        "_EnumKey_": {
          "type": "array",
          "description": "Array of unique category values (may have mixed data types)"
        },
        "_EnumValue_": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 1
              },
              "description": "1-D integer array of 1-based indices into _EnumKey_"
            },
            {
              "$ref": "#/definitions/AnnotatedArrayDef",
              "description": "N-D annotated integer array of 1-based indices (may use array compression)"
            }
          ],
          "description": "1-based indices into _EnumKey_. Note: this differs from 0-based indexing used by JSONPath and Apache Arrow DictionaryArray; subtract 1 when converting."
        },
        "_EnumOrdered_": {
          "type": "boolean",
          "description": "When true, categories in _EnumKey_ are treated as an ordered (ordinal) sequence where position defines ranking (first entry is lowest). Equivalent to ordered=True in pandas CategoricalDtype or an R ordered factor. If absent or false, the enumeration is unordered (nominal)."
        }
      },
      "required": ["_EnumKey_", "_EnumValue_"],
      "additionalProperties": false
    },
    "TreeDataDef": {
      "type": "object",
      "title": "TreeData",
      "description": "Tree data structure container",
      "patternProperties": {
        "^_TreeNode_\\(.+\\)$": {
          "description": "Tree node with data"
        }
      },
      "properties": {
        "_TreeChildren_": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TreeNodeContainerDef"
          },
          "description": "Array of child nodes"
        }
      },
      "additionalProperties": true
    },
    "TreeNodeDef": {
      "title": "TreeNode",
      "description": "Individual tree node",
      "additionalProperties": true
    },
    "TreeNodeContainerDef": {
      "type": "object",
      "title": "TreeNodeContainer",
      "description": "Container for a tree node with optional children",
      "patternProperties": {
        "^_TreeNode_\\(.+\\)$": {
          "description": "Tree node data"
        }
      },
      "properties": {
        "_TreeChildren_": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TreeNodeContainerDef"
          },
          "description": "Array of child nodes"
        }
      },
      "additionalProperties": true
    },
    "LinkedListDef": {
      "type": "array",
      "title": "LinkedList",
      "description": "Singly or doubly linked list structure. The container key may carry inline metadata to declare the node count: \"_LinkedList_(name)::Length=N\".",
      "items": {
        "$ref": "#/definitions/ListNodeDef"
      }
    },
    "ListNodeDef": {
      "type": "object",
      "title": "ListNode",
      "description": "Node in a linked list",
      "patternProperties": {
        "^_ListNode_\\(.+\\)$": {
          "description": "Node data with unique name within the list"
        }
      },
      "properties": {
        "_ListNext_": {
          "oneOf": [
            { "type": "string" },
            { "type": "null" }
          ],
          "description": "Name of the next node (null if this is the last node)"
        },
        "_ListPrior_": {
          "oneOf": [
            { "type": "string" },
            { "type": "null" }
          ],
          "description": "Name of the previous node (null if this is the first node)"
        }
      },
      "additionalProperties": true
    },
    "GraphDataDef": {
      "type": "object",
      "title": "GraphData",
      "description": "Graph data structure with nodes and edges",
      "properties": {
        "_GraphNodes_": {
          "type": "object",
          "description": "Graph nodes with their associated data",
          "additionalProperties": true
        },
        "_GraphEdges_": {
          "type": "array",
          "items": {
            "type": "array",
            "minItems": 2,
            "items": [
              {
                "type": "string",
                "description": "Source node name"
              },
              {
                "type": "string",
                "description": "Destination node name"
              }
            ],
            "additionalItems": {
              "description": "Optional edge data (scalar edge data is interpreted as edge weight)"
            }
          },
          "description": "Directed graph edges. Each entry is [source, destination, optional_data]."
        },
        "_GraphEdges0_": {
          "type": "array",
          "items": {
            "type": "array",
            "minItems": 2,
            "items": [
              {
                "type": "string",
                "description": "First node name"
              },
              {
                "type": "string",
                "description": "Second node name"
              }
            ],
            "additionalItems": {
              "description": "Optional edge data (scalar edge data is interpreted as edge weight)"
            }
          },
          "description": "Undirected graph edges. Each entry [A, B, ...] implies the reverse edge [B, A, ...]; parsers must not double-store edge data. _GraphMatrix_ is symmetric when paired with _GraphEdges0_."
        },
        "_GraphMatrix_": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "type": "array",
                "items": { "type": "number" }
              },
              "description": "Adjacency matrix in direct 2-D array format"
            },
            {
              "$ref": "#/definitions/AnnotatedArrayDef",
              "description": "Adjacency matrix in annotated JData array format (supports sparse representation)"
            }
          ],
          "description": "Graph adjacency matrix. Interpreted as symmetric when paired with _GraphEdges0_."
        }
      },
      "required": ["_GraphNodes_"],
      "oneOf": [
        { "required": ["_GraphEdges_"] },
        { "required": ["_GraphEdges0_"] },
        { "required": ["_GraphMatrix_"] }
      ],
      "additionalProperties": true
    },
    "ByteStreamDef": {
      "title": "ByteStream",
      "description": "Generic binary byte-stream data",
      "oneOf": [
        {
          "type": "string",
          "description": "Base64-encoded byte stream (simple form)"
        },
        {
          "type": "object",
          "properties": {
            "_DataInfo_": {
              "type": "object",
              "properties": {
                "MediaType": {
                  "type": "string",
                  "description": "MIME type of the original data (e.g., \"image/png\")"
                },
                "Encoding": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "Ordered list of encoding steps applied to the byte stream"
                },
                "ByteLength": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Length of the encoded data in bytes"
                }
              },
              "additionalProperties": true
            },
            "Data": {
              "type": "string",
              "description": "Base64-encoded byte stream data"
            }
          },
          "required": ["Data"],
          "additionalProperties": true
        }
      ]
    }
  }
}