@imferno/schema 2.4.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imferno/schema",
-  "version": "2.4.1",
+  "version": "3.0.0",
   "description": "JSON Schema definitions for SMPTE ST 2067 IMF types — validates imferno export output",
   "main": "index.js",
   "types": "index.d.ts",

package/schemas/composition-playlist.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "CompositionPlaylist",
-  "description": "Root CPL structure - defines a complete IMF composition",
+  "description": "Root CPL structure — defines a complete IMF composition.\n\n# Spec-required vs `Option<T>` policy (FIX-7 audit)\n\nThe parser is intentionally lenient: every spec-required element that isn't strictly necessary to **construct** a valid `CompositionPlaylist` is exposed as `Option<T>` (or via a `default = \"…\"` serde attribute). Missing-required-field violations are surfaced as catalogue diagnostics by the validator (`validate_cpl`) rather than as parse errors, so a caller can still inspect the parsed structure of a non-conformant CPL.\n\nField-by-field map against ST 2067-3 §6 / §7 (2013 / 2016 — the 2020 edition reuses the 2016 schema verbatim):\n\n| Field                     | Type             | Spec status                               | |---------------------------|------------------|-------------------------------------------| | `id`                      | `ImfUuid`        | required §6.1 — parse error if missing    | | `annotation`              | `Option<…>`      | optional §6.2                             | | `issue_date`              | `String`         | required §6.3 — parse error if missing    | | `issuer`                  | `Option<…>`      | optional §6.4                             | | `creator`                 | `Option<…>`      | optional §6.5                             | | `content_originator`      | `Option<…>`      | optional §6.6                             | | `content_title`           | `LanguageString` | required §6.7 — parse error if missing    | | `content_kind`            | concrete (default) | required §6.8 — `default_content_kind`  | | `content_version_list`    | `Option<…>`      | optional §6.10                            | | `essence_descriptor_list` | `Option<…>`      | **required** per ST 2067-2 §6.1.5 —       | |                           |                  | parser-lenient; absence is reported by    | |                           |                  | `validate_cpl` as Error                   | | `edit_rate`               | `Option<…>`      | required §6.13 — parser-lenient; absence  | |                           |                  | reported by `validate_cpl`                | | `total_running_time`      | `Option<String>` | optional §6.14                            | | `locale_list`             | `Option<…>`      | optional §6.15                            | | `extension_properties`    | `Option<…>`      | optional §6.16                            | | `composition_timecode`    | `Option<…>`      | optional §6.9                             | | `segment_list`            | `SegmentList`    | required §6.17 — parse error if missing   | | `has_signer`/`has_signature` | `bool`        | reflect presence in raw XML (§8 signatures unparsed) | | `source_xml`              | `Option<String>` | retained when parsed from XML; absent for JSON-deserialised |\n\nFive fields are spec-required but stored as `Option<T>` (with `default` on the serde side) to support the parser-lenient model: `content_kind` (defaults via `default_content_kind`), `content_version_list`, `essence_descriptor_list`, `edit_rate`, `locale_list`. The validator surfaces missing-required findings against the ST 2067-3 prose.",
   "type": "object",
   "required": [
     "ContentTitle",
@@ -1013,6 +1013,32 @@
         }
       }
     },
+    "IABChannelSubDescriptor": {
+      "description": "Presence-only stub for ST 2067-201:2026 Annex E `IABChannelSubDescriptor`.\n\nThe 2026 spec defines the full item set in Table E.1 (`IABBedMetaID`, `IABChannelID`, `IABAudioDescription`, `IABAudioDescriptionText`); imferno's CPL parser only needs to count occurrences to fire the `IabChannelSubDescriptorRecommended` warning, so the inner shape is intentionally permissive — any nested content deserialises into the catch-all map without affecting presence.",
+      "type": "object",
+      "properties": {
+        "IABBedMetaID": {
+          "description": "Annex E §E.2 — IAB Bed MetaID of the associated BedDefinition.",
+          "default": null,
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "IABChannelID": {
+          "description": "Annex E §E.2 — Channel ID within the bed.",
+          "default": null,
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0.0
+        }
+      }
+    },
     "IABEssenceDescriptor": {
       "description": "IAB (Immersive Audio Bitstream) essence descriptor — Dolby Atmos",
       "type": "object",
@@ -1193,6 +1219,14 @@
       "description": "SubDescriptors for IAB essence",
       "type": "object",
       "properties": {
+        "IABChannelSubDescriptor": {
+          "description": "ST 2067-201:2026 Annex E — IAB Channel SubDescriptor entries. Optional in 2021 (and earlier — silently dropped), recommended in 2026 (\"should contain one instance for each channel of each BedDefinition\"). Captured as a raw count via a bag struct so downstream code can probe presence without the parser needing to model every field defined in Annex E Table E.1.",
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/IABChannelSubDescriptor"
+          }
+        },
         "IABSoundfieldLabelSubDescriptor": {
           "default": null,
           "anyOf": [
@@ -1619,11 +1653,9 @@
     "LocaleList": {
       "description": "LocaleList - Content locale information",
       "type": "object",
-      "required": [
-        "Locale"
-      ],
       "properties": {
         "Locale": {
+          "default": [],
           "type": "array",
           "items": {
             "$ref": "#/definitions/Locale"
@@ -2344,11 +2376,9 @@
     },
     "SegmentList": {
       "type": "object",
-      "required": [
-        "Segment"
-      ],
       "properties": {
         "Segment": {
+          "default": [],
           "type": "array",
           "items": {
             "$ref": "#/definitions/Segment"

package/schemas/imf-report.json

@@ -63,12 +63,19 @@
           ]
         },
         {
-          "description": "Encoding and codec issues",
+          "description": "Codec-level encoding issues (J2K profiles, JPEG-XS, AAC params, PCM bit depth, etc.). For *container*-level concerns (MXF wrapping, partition layout) use `Container`.",
           "type": "string",
           "enum": [
             "Encoding"
           ]
         },
+        {
+          "description": "MXF / wrapping container constraints — distinct from `Encoding` which covers the codec carried inside the container.",
+          "type": "string",
+          "enum": [
+            "Container"
+          ]
+        },
         {
           "description": "Audio configuration issues",
           "type": "string",
@@ -90,6 +97,13 @@
             "Subtitle"
           ]
         },
+        {
+          "description": "Data essence (ISXD, dynamic metadata sidecars, ancillary data tracks). NOT for *metadata about* essence — that's `Metadata`.",
+          "type": "string",
+          "enum": [
+            "Data"
+          ]
+        },
         {
           "description": "Metadata and labeling issues",
           "type": "string",
@@ -320,6 +334,32 @@
       "type": "string",
       "format": "uuid"
     },
+    "IssueSource": {
+      "description": "Which authority produced a validation finding.\n\nEncodes the \"prose vs XSD\" provenance distinction that SMPTE ST 2067-3 §5.1 calls out (\"the prose document takes precedence on conflict\"), so callers can filter, group, or apply per-source severity overrides without inspecting the code string.\n\nCurrently *inferred* from the code prefix on a `ValidationIssue` (see `ValidationIssue::source`) — no engine code needs to set it explicitly. If inference ever becomes ambiguous (e.g. a non-XSD engine internal rule that wants the `XSD/` prefix for catalogue reasons), we can add a `with_source()` builder without changing the public shape.",
+      "oneOf": [
+        {
+          "description": "Came from the runtime XSD validator (uppsala). Schema-layer: the structural subset of the spec that the XSD DSL can express.",
+          "type": "string",
+          "enum": [
+            "XsdLayer"
+          ]
+        },
+        {
+          "description": "Came from a hand-rolled prose-cited rule. Semantic/cross-field/ value-set checks that XSD can't express; the rule's code typically cites a SMPTE prose section (e.g. `ST2067-2:2020:6.4.2`).",
+          "type": "string",
+          "enum": [
+            "ProseRule"
+          ]
+        },
+        {
+          "description": "Came from imferno engine internals — parse failures, package structure checks, manifest issues — not directly traceable to a single SMPTE spec section.",
+          "type": "string",
+          "enum": [
+            "EngineInternal"
+          ]
+        }
+      ]
+    },
     "Location": {
       "description": "Location where the issue was found",
       "type": "object",
@@ -534,6 +574,13 @@
         "severity"
       ],
       "properties": {
+        "additional_instances": {
+          "description": "Other `Location`s when this issue represents an aggregation of multiple identical-code occurrences (see [`ValidationReport::aggregate`]). Empty for fresh, un-aggregated issues. Skipped during serialisation when empty so the on-wire shape stays back-compatible for callers that don't aggregate.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Location"
+          }
+        },
         "category": {
           "description": "Category of issue",
           "allOf": [
@@ -573,6 +620,15 @@
             }
           ]
         },
+        "source": {
+          "description": "Authority that emitted this issue (XSD layer, prose rule, engine internal). Inferred from `code` at construction time so the field is always consistent with the code prefix — JS consumers can filter on `issue.source` directly without re-implementing the inference. Deserialised with a default so old reports without the field round-trip cleanly.",
+          "default": "EngineInternal",
+          "allOf": [
+            {
+              "$ref": "#/definitions/IssueSource"
+            }
+          ]
+        },
         "suggestion": {
           "description": "Suggestion for how to fix",
           "type": [
@@ -659,6 +715,13 @@
             }
           ]
         },
+        "suppressed": {
+          "description": "Issues that were suppressed by a `RuleSeverity::Off` override. These are not counted toward `is_playable`/`is_compliant` or surfaced by `has_errors`/`summary` — they exist so operators can debug their `RulesConfig` (`--show-suppressed`) without re-running validation. Each carries a `context[\"suppressed_by\"]` annotation naming the rule key that matched.\n\nSkipped during serialisation when empty so reports without suppressed rules keep the previous on-wire shape.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ValidationIssue"
+          }
+        },
         "timestamp": {
           "description": "Timestamp of validation",
           "type": "string"

package/schemas/validation-report.json

@@ -51,6 +51,13 @@
         }
       ]
     },
+    "suppressed": {
+      "description": "Issues that were suppressed by a `RuleSeverity::Off` override. These are not counted toward `is_playable`/`is_compliant` or surfaced by `has_errors`/`summary` — they exist so operators can debug their `RulesConfig` (`--show-suppressed`) without re-running validation. Each carries a `context[\"suppressed_by\"]` annotation naming the rule key that matched.\n\nSkipped during serialisation when empty so reports without suppressed rules keep the previous on-wire shape.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ValidationIssue"
+      }
+    },
     "timestamp": {
       "description": "Timestamp of validation",
       "type": "string"
@@ -103,12 +110,19 @@
           ]
         },
         {
-          "description": "Encoding and codec issues",
+          "description": "Codec-level encoding issues (J2K profiles, JPEG-XS, AAC params, PCM bit depth, etc.). For *container*-level concerns (MXF wrapping, partition layout) use `Container`.",
           "type": "string",
           "enum": [
             "Encoding"
           ]
         },
+        {
+          "description": "MXF / wrapping container constraints — distinct from `Encoding` which covers the codec carried inside the container.",
+          "type": "string",
+          "enum": [
+            "Container"
+          ]
+        },
         {
           "description": "Audio configuration issues",
           "type": "string",
@@ -130,6 +144,13 @@
             "Subtitle"
           ]
         },
+        {
+          "description": "Data essence (ISXD, dynamic metadata sidecars, ancillary data tracks). NOT for *metadata about* essence — that's `Metadata`.",
+          "type": "string",
+          "enum": [
+            "Data"
+          ]
+        },
         {
           "description": "Metadata and labeling issues",
           "type": "string",
@@ -164,6 +185,32 @@
       "type": "string",
       "format": "uuid"
     },
+    "IssueSource": {
+      "description": "Which authority produced a validation finding.\n\nEncodes the \"prose vs XSD\" provenance distinction that SMPTE ST 2067-3 §5.1 calls out (\"the prose document takes precedence on conflict\"), so callers can filter, group, or apply per-source severity overrides without inspecting the code string.\n\nCurrently *inferred* from the code prefix on a `ValidationIssue` (see `ValidationIssue::source`) — no engine code needs to set it explicitly. If inference ever becomes ambiguous (e.g. a non-XSD engine internal rule that wants the `XSD/` prefix for catalogue reasons), we can add a `with_source()` builder without changing the public shape.",
+      "oneOf": [
+        {
+          "description": "Came from the runtime XSD validator (uppsala). Schema-layer: the structural subset of the spec that the XSD DSL can express.",
+          "type": "string",
+          "enum": [
+            "XsdLayer"
+          ]
+        },
+        {
+          "description": "Came from a hand-rolled prose-cited rule. Semantic/cross-field/ value-set checks that XSD can't express; the rule's code typically cites a SMPTE prose section (e.g. `ST2067-2:2020:6.4.2`).",
+          "type": "string",
+          "enum": [
+            "ProseRule"
+          ]
+        },
+        {
+          "description": "Came from imferno engine internals — parse failures, package structure checks, manifest issues — not directly traceable to a single SMPTE spec section.",
+          "type": "string",
+          "enum": [
+            "EngineInternal"
+          ]
+        }
+      ]
+    },
     "Location": {
       "description": "Location where the issue was found",
       "type": "object",
@@ -293,6 +340,13 @@
         "severity"
       ],
       "properties": {
+        "additional_instances": {
+          "description": "Other `Location`s when this issue represents an aggregation of multiple identical-code occurrences (see [`ValidationReport::aggregate`]). Empty for fresh, un-aggregated issues. Skipped during serialisation when empty so the on-wire shape stays back-compatible for callers that don't aggregate.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Location"
+          }
+        },
         "category": {
           "description": "Category of issue",
           "allOf": [
@@ -332,6 +386,15 @@
             }
           ]
         },
+        "source": {
+          "description": "Authority that emitted this issue (XSD layer, prose rule, engine internal). Inferred from `code` at construction time so the field is always consistent with the code prefix — JS consumers can filter on `issue.source` directly without re-implementing the inference. Deserialised with a default so old reports without the field round-trip cleanly.",
+          "default": "EngineInternal",
+          "allOf": [
+            {
+              "$ref": "#/definitions/IssueSource"
+            }
+          ]
+        },
         "suggestion": {
           "description": "Suggestion for how to fix",
           "type": [