metadata.schema.json

{
  "meta:license": [
    "SPDX-FileCopyrightText: (C) 2021 - 2026 Intel Corporation",
    "SPDX-License-Identifier: Apache-2.0"
  ],
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "type": "object",
  "definitions": {
    "id": {
      "title": "Object ID",
      "type": "string",
      "description": "Unique ID of the object in the scene.",
      "examples": ["sensor1", "AB:CD:EF:12:34:56.0"]
    },
    "timestamp": {
      "title": "Timestamp",
      "type": "string",
      "format": "date-time",
      "description": "Timestamp in ISO 8601 UTC format at time of data acquisition.",
      "examples": [
        "2021-01-25T23:26:12Z",
        "2021-01-25T23:26:12.424Z",
        "2021-01-25T23:26:12.424659Z"
      ]
    },
    "rate": {
      "title": "Sensor rate",
      "type": "number",
      "description": "The rate at which the sensor is producing data.",
      "minimum": 0.0
    },
    "bounding_box": {
      "type": "object",
      "title": "Bounding Box",
      "description": "Bounding box for signaling the normalized camera coordinates of a detected object. These coordinates should be in normalized camera space.",
      "properties": {
        "x": {
          "type": "number",
          "description": "x coordinate of the top-left corner of bounding box."
        },
        "y": {
          "type": "number",
          "description": "y coordinate of the top-left corner of bounding box."
        },
        "width": {
          "type": "number",
          "description": "Horizontal width of the bounding box.",
          "minimum": 0
        },
        "height": {
          "type": "number",
          "description": "Vertical height of the bounding box.",
          "minimum": 0
        }
      },
      "required": ["x", "y", "width", "height"]
    },
    "bounding_box_px": {
      "type": "object",
      "title": "Bounding Box",
      "description": "Bounding box for signaling the normalized camera coordinates of a detected object. These coordinates should be in camera pixel space.",
      "properties": {
        "x": {
          "type": "number",
          "description": "x coordinate of the top-left corner of bounding box."
        },
        "y": {
          "type": "number",
          "description": "y coordinate of the top-left corner of bounding box."
        },
        "z": {
          "type": "number",
          "description": "z coordinate of the top-left corner of bounding box."
        },
        "width": {
          "type": "number",
          "description": "Horizontal width of the bounding box.",
          "minimum": 0
        },
        "height": {
          "type": "number",
          "description": "Vertical height of the bounding box.",
          "minimum": 0
        },
        "depth": {
          "type": "number",
          "description": "Depth of the bounding box.",
          "minimum": 0
        }
      },
      "required": ["x", "y", "width", "height"]
    },
    "semantic_metadata_attribute": {
      "type": "object",
      "title": "Semantic Metadata Attribute",
      "description": "A semantic attribute detected by an analytics model with label, confidence, and model source.",
      "additionalProperties": true,
      "properties": {
        "label": {
          "title": "Label",
          "description": "The detected value or label for this attribute (e.g., 'Female' for gender, 'blue' for color, true/false for boolean attributes)."
        },
        "confidence": {
          "title": "Confidence",
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Confidence score of the detected attribute (0.0 to 1.0)."
        },
        "model_name": {
          "title": "Model Name",
          "type": "string",
          "description": "Name or identifier of the model that generated this attribute (e.g., 'age-gender-recognition-retail-0013')."
        }
      },
      "required": ["label", "model_name"]
    },
    "semantic_metadata": {
      "type": "object",
      "title": "Semantic Metadata",
      "description": "Semantic attributes describing what an object is. Contains the extensible set of all semantic properties detected by analytics models. Each attribute follows the structure: {label, confidence, model_name}.",
      "additionalProperties": {
        "oneOf": [
          {
            "$ref": "#/definitions/semantic_metadata_attribute"
          },
          {
            "type": "object",
            "properties": {
              "embedding_vector": {
                "type": "string"
              },
              "model_name": {
                "type": "string"
              }
            },
            "required": ["embedding_vector", "model_name"],
            "description": "Special case for reid embedding vectors"
          }
        ]
      },
      "meta:extensible": true
    },
    "detection": {
      "type": "object",
      "title": "Object Detection",
      "description": "Metadata of an object detected in an image frame.",
      "additionalProperties": true,
      "meta:extensible": true,
      "properties": {
        "bounding_box": {
          "$ref": "#/definitions/bounding_box"
        },
        "translation": {
          "title": "Translation",
          "type": "array",
          "description": "Translation of the object from coordinate space origin (x, y, z)",
          "items": {
            "type": "number"
          },
          "minItems": 3,
          "maxItems": 3
        },
        "rotation": {
          "title": "Rotation",
          "type": "array",
          "description": "Rotation of the object in quaternion",
          "items": {
            "type": "number",
            "exclusiveMinimum": -1,
            "exclusiveMaximum": 1
          },
          "minItems": 4,
          "maxItems": 4
        },
        "size": {
          "title": "Size",
          "type": "array",
          "description": "Size of the object (x, y, z)",
          "items": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "minItems": 3,
          "maxItems": 3
        },
        "category": {
          "title": "Category",
          "type": "string",
          "description": "Category or class of object being detected.",
          "examples": ["person", "vehicle", "object"]
        },
        "confidence": {
          "title": "Confidence",
          "type": "number",
          "description": "Inferencing confidence result for this detection.",
          "examples": [0.899463546, 0.93243],
          "exclusiveMinimum": 0.0
        },
        "id": {
          "title": "Detection ID",
          "type": "integer",
          "description": "Detection ID. Not expected to track the same detection from one frame to the next.",
          "minimum": 0
        },
        "metadata": {
          "$ref": "#/definitions/semantic_metadata",
          "description": "Semantic metadata describing what an object is (age, gender, clothing, embedding vectors, etc)."
        },
        "distance": {
          "title": "Distance to Object",
          "type": "number",
          "description": "Distance from the camera/sensor to the detection in meters, for example when using RealSense or Lidar.",
          "examples": [1.2, 3.56]
        }
      },
      "required": ["category"],
      "oneOf": [
        { "required": ["translation", "size"] },
        { "required": ["lat_long_alt", "size"] },
        {
          "anyOf": [
            { "required": ["bounding_box"] },
            { "required": ["bounding_box_px"] }
          ]
        }
      ]
    },
    "mac": {
      "title": "System MAC Address",
      "type": "string",
      "description": "MAC address of system that acquired the data.",
      "examples": ["AB:CD:EF:12:34:56", "ab-cd-ef-12-34-56"]
    },
    "singleton": {
      "title": "Sensor Metadata",
      "description": "Many types of sensors exist for generating data from the physical world. This schema defines the composition of metadata for publishing sensor data into SceneScape.",
      "type": "object",
      "properties": {
        "timestamp": {
          "$ref": "#/definitions/timestamp"
        },
        "id": {
          "$ref": "#/definitions/id"
        },
        "value": {
          "title": "Sensor reading",
          "description": "Value of the sensor reading."
        },
        "subtype": {
          "title": "Sensor Subtype",
          "type": "string",
          "examples": ["humidity", "temperature"]
        },
        "rate": {
          "$ref": "#/definitions/rate"
        }
      },
      "required": ["timestamp", "id", "value"]
    },
    "detector": {
      "title": "Detector Metadata",
      "description": "Many types of detectors exist for generating bounding boxes around objects from image-like sources. This schema defines the composition of metadata for publishing object detection results into SceneScape.",
      "type": "object",
      "properties": {
        "timestamp": {
          "$ref": "#/definitions/timestamp"
        },
        "id": {
          "$ref": "#/definitions/id"
        },
        "objects": {
          "title": "Detected Objects by Category",
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/detection"
            }
          }
        },
        "sub_detections": {
          "title": "Sub-Detections",
          "type": "array",
          "description": "Array of sub-detections associated with the detector output.",
          "items": {
            "type": "string"
          },
          "examples": [["license_plate"], ["person", "vest", "apriltag"]]
        }
      },
      "required": ["timestamp", "id", "objects"]
    }
  },
  "properties": {
    "singleton": {
      "$ref": "#/definitions/singleton"
    },
    "detector": {
      "$ref": "#/definitions/detector"
    }
  },
  "additionalProperties": true,
  "meta:extensible": true
}