SOH GDTF extension .soh.json — version 1

Specification, 26 October 2026. Published by SOH Stage Studio (gdtf-lights.com). Anyone may read, write and implement this format. Machine-readable: JSON Schema (draft 2020-12).

Why a sidecar file

GDTF 1.2 (DIN SPEC 15800:2022) describes most fixtures well, but some real optics have no place in it: a rotating bee-eye lens whose colour zones are effect layers of the same LEDs, an LED ball that sprays many weak beams, laser diodes behind a star grating, or how long a reset value must be held. Writing such data into description.xml would either break the XSD or change how existing programs read the fixture.

The extension therefore lives in a separate JSON file next to the GDTF. The GDTF stays a normal, valid GDTF that every program opens as before. A program that knows the extension reads it in addition; a program that does not know it never sees it.

Files and placement

Binding to exactly one GDTF

An extension is valid only for the exact GDTF it was written for. Two keys bind it:

Any change to description.xml — a new revision, a repair by another tool, re-saving in an editor — invalidates the extension. A consumer that finds a mismatch must ignore the whole file. Whoever changes the GDTF writes a new extension.

Envelope (normative)

KeyTypeRule
schemastringrequired, exactly "soh-gdtf-extension"
versionintegerrequired, 1; consumers accept only versions they know
gdtfobjectrequired: fixtureTypeId, descriptionSha256; optional file (informative file name)
productstringmanufacturer product code, e.g. LED585
generatorobjectname, code, generatedAt (RFC 3339); informative

Unknown keys at any level are ignored. New optional keys can be added without changing version; a change that an existing reader would misread gets a new version number.

Content keys, version 1

The content keys are defined together with 3D Stage Visualizer, the first program that reads them. This section reflects that definition as of 26 October 2026.

roles — object, geometry name → role

RoleMeaning
layerThe geometry is an effect layer of the same LEDs (e.g. a bee-eye background, foreground or shape zone). Channels on it are effect channels, not a separate light source; a renderer must not add light for it.
auxiliaryAn additional light source beside the main optics, e.g. an LED ribbon around the head.

Other role values are reserved and ignored.

optics — array of optical systems

Each entry has model and usually source. A geometry or laser belongs to at most one entry. An entry with an unknown model is skipped.

ModelKeys
beeEye
rotating bee-eye lens
head geometry name of the head; cells geometry names of the LED cells in order; indexPeriodDeg rotational period of the lens pattern (60 for a hexagonal lens)
ledBall
LED ball
beam (required) one Beam geometry of the mode, not Glow or None; spreadDeg (0–180], default the BeamAngle of that beam; count 2–64, default 16; beamAngleDeg (0–min(30, spreadDeg)], default 4; source (required)
laserGrating
laser diode behind a grating
lasers (required) names of <Laser> geometries; figure "stars" (other values reserved); spreadDeg (0–120], default the ScanAngle of the laser, else 60; points 8–128, default 64; source (required). Not used in a mode where a gobo, media or object-slot channel reaches the laser.

reset, notes, source

Rules for consumers

  1. Check the envelope and the binding. If anything fails, ignore the whole file and keep using the GDTF alone.
  2. Ignore unknown keys and reserved values.
  3. Replace an invalid optional value with its default and report it; skip an entry whose required value is invalid.
  4. Never let the extension contradict the DMX data of the GDTF: it adds rendering knowledge, it does not remap channels.

How the MVR generator on this site uses it

The MVR generator (version 2.5) looks for X.soh.json next to every GDTF it packs. If the extension is valid, the GDTF is only audited, never repaired, in every target program profile, so it goes into the MVR byte-identical and the extension is packed next to it. If the extension does not apply, the generator says why in the report and warning V-W24. Details: How the MVR generator treats GDTF files (rule R5).

Examples

Live files, each next to its GDTF in the SOH library:

{
  "schema": "soh-gdtf-extension",
  "version": 1,
  "gdtf": {
    "file": "SOH_Moving_LED_head_ZOOM_Beam_Wash_Bee_Eye_7x_40_W_RGBW_4in1_silent_DMX_LED585.gdtf",
    "fixtureTypeId": "9A769523-09BD-5185-9B87-CED710EDCE40",
    "descriptionSha256": "5b32bb0a0abccb3775bb9e47fe76f4b7385e53825f97b8fd3c82716660e69668"
  },
  "product": "LED585",
  "generator": { "name": "SOH GDTF generator", "code": "f888e379", "generatedAt": "2026-10-24T13:37:29Z" },
  "roles": { "Zone Background": "layer", "Zone Foreground": "layer", "Zone Shape": "layer" },
  "optics": [
    { "model": "beeEye", "head": "Head",
      "cells": ["Zone 1", "Zone 2", "Zone 3", "Zone 4", "Zone 5", "Zone 6", "Zone 7"],
      "indexPeriodDeg": 60,
      "source": { "kind": "rules", "ref": "rules/attribute_overrides.json LED585" } }
  ],
  "reset": { "holdSec": 5, "source": { "kind": "owner", "ref": "…" } }
}

Status and feedback

Version 1 is used in the SOH GDTF library and read by 3D Stage Visualizer. If you write or read GDTF and want to use or extend the format, or think part of it belongs in a future GDTF version, contact us. The goal is for the useful parts to move into the GDTF standard itself.