firebird/dex-schema/firebird-dex-v1.schema.json

0001 {
0002   "$schema": "https://json-schema.org/draft/2020-12/schema",
0003   "$id": "https://raw.githubusercontent.com/eic/firebird/main/dex-schema/firebird-dex-v1.schema.json",
0004   "title": "Firebird DEX v1",
0005   "description": "Firebird Data Exchange format, version 1.0. An event is a list of pieces. A piece holds entity data as parallel column arrays (entity id equals array index). References between pieces are declared index columns. Ragged per-entity payloads (trajectory point lists) stay nested.",
0006   "type": "object",
0007   "required": ["type", "version", "events"],
0008   "properties": {
0009     "type": { "const": "firebird-dex-json" },
0010     "version": { "const": "1.0" },
0011     "origin": {
0012       "description": "Free-form provenance: source file, producing program, timestamps.",
0013       "type": ["object", "array", "string", "null"]
0014     },
0015     "events": {
0016       "type": "array",
0017       "items": { "$ref": "#/$defs/event" }
0018     }
0019   },
0020   "$defs": {
0021     "event": {
0022       "type": "object",
0023       "required": ["id", "pieces"],
0024       "properties": {
0025         "id": {
0026           "description": "Event identifier, unique within the file.",
0027           "type": ["string", "integer"]
0028         },
0029         "pieces": {
0030           "type": "array",
0031           "items": { "$ref": "#/$defs/piece" }
0032         }
0033       }
0034     },
0035     "piece": {
0036       "description": "One named block of typed entity data. `count` entities live in parallel `columns` arrays; a scalar column has `count` values, a fixed-width vector column (like an xyz position) has a whole multiple of `count` values, flattened. A writer declares only the columns it has (a simulation writer omits reconstruction columns); readers bind to declared columns, never to a fixed set.",
0037       "type": "object",
0038       "required": ["name", "type", "version", "count", "columns"],
0039       "properties": {
0040         "name": {
0041           "description": "Piece identifier, unique within the event. `refs` in other pieces target this name.",
0042           "type": "string"
0043         },
0044         "type": {
0045           "description": "Piece type, selects the reader/painter. Core types use bare names (BoxHit, PointTrajectory); extension types use a namespace prefix (example.CherenkovRing).",
0046           "type": "string"
0047         },
0048         "version": {
0049           "description": "Schema version of this piece type.",
0050           "type": "string"
0051         },
0052         "origin": {
0053           "description": "Free-form provenance, e.g. the original EDM4hep/EDM4eic collection type.",
0054           "type": ["object", "array", "string", "null"]
0055         },
0056         "count": {
0057           "description": "Number of entities. Every column length is `count` (scalar) or a whole multiple of `count` (flattened fixed-width vector).",
0058           "type": "integer",
0059           "minimum": 0
0060         },
0061         "columns": {
0062           "type": "object",
0063           "additionalProperties": { "$ref": "#/$defs/column" }
0064         },
0065         "refs": {
0066           "description": "Declares reference columns: column name -> target piece name (in the same event). Values in a reference column are entity indexes into the target piece; -1 means no reference.",
0067           "type": "object",
0068           "additionalProperties": { "type": "string" }
0069         }
0070       },
0071       "allOf": [
0072         { "$ref": "#/$defs/boxHitPiece" },
0073         { "$ref": "#/$defs/pointTrajectoryPiece" }
0074       ]
0075     },
0076     "column": {
0077       "description": "One parallel array. Homogeneous per column: numbers for measured values and references, strings for labels.",
0078       "type": "array",
0079       "items": { "type": ["number", "string", "null"] }
0080     },
0081     "boxHitPiece": {
0082       "description": "BoxHit: box-shaped hits. Required columns: pos (flat x,y,z per hit, 3*count values, mm), dim (flat dx,dy,dz box size per hit, 3*count, mm). Optional: time (ns), timeError (ns), edep (GeV), edepError (GeV), each `count` values.",
0083       "if": { "properties": { "type": { "const": "BoxHit" } }, "required": ["type"] },
0084       "then": {
0085         "properties": {
0086           "columns": {
0087             "type": "object",
0088             "required": ["pos", "dim"],
0089             "properties": {
0090               "pos": { "$ref": "#/$defs/numberColumn" },
0091               "dim": { "$ref": "#/$defs/numberColumn" },
0092               "time": { "$ref": "#/$defs/numberColumn" },
0093               "timeError": { "$ref": "#/$defs/numberColumn" },
0094               "edep": { "$ref": "#/$defs/numberColumn" },
0095               "edepError": { "$ref": "#/$defs/numberColumn" }
0096             }
0097           }
0098         }
0099       }
0100     },
0101     "pointTrajectoryPiece": {
0102       "description": "PointTrajectory: polyline trajectories. Track parameters are ordinary columns (a writer declares the ones it has: theta, phi, qOverP for reconstruction; pdg, charge, momentum for simulation). The per-trajectory point lists are ragged, so they stay nested in `points`: one list of point tuples per entity, tuple layout declared by `pointColumns`.",
0103       "if": { "properties": { "type": { "const": "PointTrajectory" } }, "required": ["type"] },
0104       "then": {
0105         "required": ["pointColumns", "points"],
0106         "properties": {
0107           "pointColumns": {
0108             "description": "Meaning of each position in a point tuple, e.g. [\"x\",\"y\",\"z\",\"t\",\"dx\",\"dy\",\"dz\",\"dt\"].",
0109             "type": "array",
0110             "items": { "type": "string" }
0111           },
0112           "points": {
0113             "description": "Ragged: points[i] is the point-tuple list of entity i; length equals `count`.",
0114             "type": "array",
0115             "items": {
0116               "type": "array",
0117               "items": {
0118                 "type": "array",
0119                 "items": { "type": "number" }
0120               }
0121             }
0122           }
0123         }
0124       }
0125     },
0126     "numberColumn": {
0127       "type": "array",
0128       "items": { "type": "number" }
0129     }
0130   }
0131 }