{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gdtf-lights.com/soh-gdtf-extension/schema-v1.json",
  "title": "SOH GDTF extension (.soh.json), version 1",
  "description": "Sidecar file X.soh.json next to X.gdtf. It adds data that GDTF 1.2 cannot express and never changes the GDTF itself. The envelope (schema, version, gdtf binding) is normative; consumers ignore unknown keys. Specification: https://gdtf-lights.com/soh-gdtf-extension/",
  "type": "object",
  "required": ["schema", "version", "gdtf"],
  "properties": {
    "schema": { "const": "soh-gdtf-extension" },
    "version": { "const": 1, "description": "Integer. Consumers accept only versions they know." },
    "gdtf": {
      "type": "object",
      "description": "Binding to exactly one GDTF file. If it does not match, the extension does not apply.",
      "required": ["fixtureTypeId", "descriptionSha256"],
      "properties": {
        "file": { "type": "string", "description": "File name of the GDTF the extension was generated for (informative; the binding is the hash and the FixtureTypeID)." },
        "fixtureTypeId": { "type": "string", "minLength": 1, "description": "FixtureType/@FixtureTypeID of the GDTF; compared case-insensitively." },
        "descriptionSha256": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$", "description": "SHA-256 of the exact bytes of description.xml inside the GDTF archive." }
      }
    },
    "product": { "type": "string", "description": "Product code of the manufacturer (for SOH e.g. LED585)." },
    "generator": {
      "type": "object",
      "description": "Tool that wrote the file (informative).",
      "properties": {
        "name": { "type": "string" },
        "code": { "type": "string", "description": "Version or commit of the generator." },
        "generatedAt": { "type": "string", "format": "date-time" }
      }
    },
    "roles": {
      "type": "object",
      "description": "Geometry name (Geometry/@Name in the GDTF) -> role. Defined in version 1: \"layer\" (an effect layer of the same LEDs, e.g. a bee-eye colour zone; its channels are effect channels, not a separate light source) and \"auxiliary\" (an additional light source next to the main beam, e.g. an LED ribbon). Other values are reserved; consumers ignore them.",
      "additionalProperties": { "type": "string" }
    },
    "optics": {
      "type": "array",
      "description": "Optical systems that GDTF 1.2 cannot describe. One entry per system; a geometry or laser belongs to at most one entry.",
      "items": { "$ref": "#/$defs/optic" }
    },
    "reset": {
      "type": "object",
      "description": "Behaviour of the fixture reset function.",
      "properties": {
        "holdSec": { "type": "number", "exclusiveMinimum": 0, "description": "How long the reset DMX value must be held, in seconds." },
        "source": { "$ref": "#/$defs/source" }
      }
    },
    "notes": {
      "type": "array",
      "description": "Plain-text remarks, e.g. values that are placeholders because no source states them.",
      "items": { "type": "string" }
    }
  },
  "$defs": {
    "source": {
      "type": "object",
      "description": "Where a value comes from: kind (e.g. \"manual\", \"owner\", \"rules\") and a human-readable reference.",
      "required": ["kind", "ref"],
      "properties": {
        "kind": { "type": "string" },
        "ref": { "type": "string" }
      }
    },
    "optic": {
      "type": "object",
      "required": ["model"],
      "properties": {
        "model": { "type": "string", "description": "Defined in version 1: beeEye, ledBall, laserGrating. Other values are reserved; consumers skip the entry." },
        "source": { "$ref": "#/$defs/source" }
      },
      "allOf": [
        {
          "if": { "properties": { "model": { "const": "beeEye" } } },
          "then": {
            "description": "Rotating bee-eye lens: one head with a ring of LED cells behind a common lens.",
            "properties": {
              "head": { "type": "string", "description": "Geometry name of the head that carries the lens." },
              "cells": { "type": "array", "items": { "type": "string" }, "uniqueItems": true, "description": "Geometry names of the LED cells, in order." },
              "indexPeriodDeg": { "type": "number", "exclusiveMinimum": 0, "maximum": 360, "description": "Rotational period of the lens pattern in degrees (e.g. 60 for a hexagonal lens)." }
            }
          }
        },
        {
          "if": { "properties": { "model": { "const": "ledBall" } } },
          "then": {
            "description": "LED ball: one Beam rendered as several weak single beams spread into a half space.",
            "required": ["beam", "source"],
            "properties": {
              "beam": { "type": "string", "description": "Name of exactly one Beam geometry in the mode (not Glow or None, not an auxiliary geometry, not used by another optics entry)." },
              "spreadDeg": { "type": "number", "exclusiveMinimum": 0, "maximum": 180, "description": "Total spread; if missing, the BeamAngle of the beam." },
              "count": { "type": "integer", "minimum": 2, "maximum": 64, "default": 16 },
              "beamAngleDeg": { "type": "number", "exclusiveMinimum": 0, "maximum": 30, "default": 4, "description": "Angle of each single beam, at most min(30, spreadDeg)." }
            }
          }
        },
        {
          "if": { "properties": { "model": { "const": "laserGrating" } } },
          "then": {
            "description": "Laser diode behind a diffraction grating: a figure of many points instead of one dot.",
            "required": ["lasers", "source"],
            "properties": {
              "lasers": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" }, "description": "Names of <Laser> geometries; none may appear in another optics entry." },
              "figure": { "type": "string", "default": "stars", "description": "Defined in version 1: \"stars\". Other values are reserved." },
              "spreadDeg": { "type": "number", "exclusiveMinimum": 0, "maximum": 120, "description": "Cone of the figure; if missing, the ScanAngle of the laser, otherwise 60." },
              "points": { "type": "integer", "minimum": 8, "maximum": 128, "default": 64 }
            }
          }
        }
      ]
    }
  }
}
