SOH GDTF extension .soh.json — version 1
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
- Next to the GDTF:
X.soh.jsonin the same folder asX.gdtf(same stem, regular file, UTF-8 JSON object, 2 bytes to 64 KiB). - Inside an MVR: at the archive root next to the GDTF member, with the stem of that member
(
X.gdtf→X.soh.json,X~2.gdtf→X~2.soh.json).GeneralSceneDescription.xmldoes not reference it, so MVR readers that do not know it ignore it. - Media type:
application/json.
Binding to exactly one GDTF
An extension is valid only for the exact GDTF it was written for. Two keys bind it:
gdtf.descriptionSha256— SHA-256 (64 hex digits) of the exact bytes ofdescription.xmlinside the GDTF archive. Other archive members (models, wheels, thumbnails) are not part of the hash.gdtf.fixtureTypeId—FixtureType/@FixtureTypeID, compared case-insensitively.
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)
| Key | Type | Rule |
|---|---|---|
schema | string | required, exactly "soh-gdtf-extension" |
version | integer | required, 1; consumers accept only versions they know |
gdtf | object | required: fixtureTypeId, descriptionSha256; optional file (informative file name) |
product | string | manufacturer product code, e.g. LED585 |
generator | object | name, 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
| Role | Meaning |
|---|---|
layer | The 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. |
auxiliary | An 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.
| Model | Keys |
|---|---|
beeEyerotating 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) |
ledBallLED 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) |
laserGratinglaser 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
reset.holdSec— how many seconds the reset DMX value must be held for the fixture to reset.notes— array of plain-text remarks, typically values that are placeholders because no source states them.source—{kind, ref}: where a value comes from (manual,owner,rules, …) and a human-readable reference.
Rules for consumers
- Check the envelope and the binding. If anything fails, ignore the whole file and keep using the GDTF alone.
- Ignore unknown keys and reserved values.
- Replace an invalid optional value with its default and report it; skip an entry whose required value is invalid.
- 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:
- LED585 — bee-eye lens, three effect layers, reset hold 5 s
- LED690 — bee-eye lens with an auxiliary LED ribbon
- LED703 — 19-cell bee-eye lens
- LED701 — LED ball and three lasers behind star gratings
{
"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.