open-standards/wai/glossary/SCHEMA.md

# WAI codec glossary — schema

Canonical, machine-readable catalog of media codecs surveyed for WAI capability registration. Lives in [`codecs.json`](codecs.json) alongside this schema.

The glossary is reference material — it is **not** the registry of WAI capabilities (that is [`../SPEC.md §5`](../SPEC.md), published in machine-readable form as [`../registry/capabilities.json`](../registry/capabilities.json)). Listing a codec here means it exists and is documented; listing a codec in the spec means a conforming sink MAY or MUST implement it.

## Provenance

Originally extracted from the inline JavaScript array of an earlier reference page (`wai-info-page/wai-glossary.html`, not part of this repository) into typed form, then ported to JSON for language-neutral consumption.

The site's glossary page (https://wai.transaction.science/glossary) renders a hand-ported copy of this file, so a change here reaches the site only when that copy is updated to match.

## Top-level shape

```json
{
  "schema":         "https://git.transaction.science/Transaction-Science/open-standards/src/branch/main/wai/glossary/SCHEMA.md",
  "schema_version": 2,
  "entries":        [ Codec, ... ]
}
```

`schema_version` is the version of this schema the file follows. Version 2 is the form described here. The earlier form carried no `schema_version`, and its entries had an `org` field where version 2 has `body`; a reader that finds no `schema_version` has that form. A change that renames or removes a field, or changes what a field means, raises the version.

## `Codec` entry

```ts
{
  name:     string;          // the format's name or designation, e.g. "AV1", "HEVC / H.265"
  year:     number;          // year of first published spec or first release
  body:     string | null;   // the standards body, standard designation or open-source
                             // project the format belongs to, from the allowlist below;
                             // null when it has none (a proprietary format, a paper)
  modality: "image" | "video" | "audio" | "speech" | "text" | "volumetric" | "haptic" | "metadata";
  era:      "classical" | "neural";
  status:   "success" | "niche" | "superseded" | "failed" | "academic" | "emerging";
  lineage:  "industry" | "standards" | "academic" | "opensource";
  desc:     string;          // 1–3 sentence factual summary — what it is, the specification
                             // that defines it, its design choice, its current footprint.
                             // Self-referential only: no comparisons, no company, product
                             // or person names.
  wai?:     WaiLink[];       // OPTIONAL: present only on an entry whose bitstream a
                             // registered WAI capability carries (SPEC §5)
}

WaiLink = {
  capability: string;        // a payload or companion capability SPEC §5 registers
  licence:    "royalty-free" | "patent-pool" | "proprietary" | "non-commercial";
  replicate:  "standard-defined" | "standard-tolerance" | "standard-unclassified" | "neural-int-exact"
            | "neural-entropy-exact" | "generative-exact" | "neural-float" | "behavioral";
}
```

### Field values

- **`name`** identifies the format. A format's own name, its FourCC, its file extension and its standard designation are the identifiers a reader recognises the bitstream by, and an entry is titled by one of them. Where the format's name embeds the name of a company, of a company's product line, or of the product it shipped in (a player, a framework, a platform, a capture tool), the entry is titled by its standard designation where it has one (for example "AC-3 (ATSC A/52)", "VC-1 (SMPTE 421M)", "SMPTE RDD 36", "ETSI TS 103 491"), otherwise by its FourCC or file-format name ("BIK video (.bik)", "RV10–RV40 (FourCC)"), otherwise by what it is ("Layered height-channel cinema audio (2010)"). A research codec is titled by its paper's method, not its authors ("Scale hyperprior (2018)").
- **No entry names a company, a product or a person**, in `name` or `desc`. A `desc` describes the platform a format shipped in by its function ("a desktop video framework", "a 2000s browser-plugin multimedia platform", "the FLV container"), and cites a paper by its title and venue. The public-name check (`scripts/check-public-names.sh`, with the private pattern list) scans this file, so an entry that breaks the rule fails CI; JSON has no comments, so no line here can carry an `allow-name` opt-out.
- **`body`** is a value from the allowlist below, or `null`. It is never a company or a person.
- **`modality`** is the media class. `text` is general-purpose byte compression; `volumetric` is meshes, point clouds and Gaussian splats; `haptic` is haptic signals; `metadata` is data applied with another payload (HDR dynamic metadata). A linked entry's modality is the registry's media class of the capability it links (`speech` counts as `audio`).
- **`status`** is descriptive, not normative:
  - `success` — the codec carries non-trivial production traffic today.
  - `niche` — alive in specific contexts (icons, pipelines, debug tools, particular hardware).
  - `superseded` — readable everywhere, written nowhere modern.
  - `failed` — shipped, did not achieve adoption.
  - `academic` — published only in research; no production deployment.
  - `emerging` — recent enough that adoption trajectory is undetermined.
- **`lineage`** captures origin culture (affects how the codec evolves):
  - `industry` — developed by a company for its product.
  - `standards` — a formal standards body (ISO, ITU-T, IETF, IEEE, SMPTE).
  - `academic` — research lab.
  - `opensource` — community-led from inception.
- **`era`** marks the discontinuity: `classical` = handcrafted DCT/wavelet/predictive, `neural` = end-to-end learned bitstream.

### `body` allowlist

- `ISO/IEC JTC 1/SC 29 (MPEG)`
- `ISO/IEC JTC 1/SC 29 (JPEG)`
- `ITU-T`
- `ITU-T and ISO/IEC JTC 1/SC 29 (MPEG)`
- `ITU-T and ISO/IEC JTC 1/SC 29 (JPEG)`
- `ISO`
- `IEC`
- `IEEE`
- `IETF`
- `W3C`
- `ETSI`
- `3GPP`
- `3GPP2`
- `TIA`
- `ATSC`
- `SMPTE`
- `Alliance for Open Media`
- `Xiph.Org Foundation`
- `WebM Project`
- `Khronos Group`
- `Bluetooth SIG`
- `IAU FITS Working Group`
- `Interactive Multimedia Association`
- `PNG Development Group`
- `FS-1015`
- `MIL-STD-3005`
- `T/AI 109.2-2021`
- `T/AI 109.3-2023`
- `X Window System`
- `Netpbm`
- `OpenEXR`
- `Radiance`
- `QOI`
- `MozJPEG`
- `FLIF`
- `FFmpeg`
- `Xvid`
- `Ut Video`
- `ScummVM`
- `Musepack`
- `WavPack`
- `TTA`
- `lossyWAV`
- `Codec 2`
- `LPCNet`
- `Lyra`
- `EnCodec`
- `SNAC`
- `Draco`
- `SPZ`
- `XZ Utils`

A value is a standards body, a standard designation (for a format whose issuing body was not read from a primary source, the designation stands in for it), or an open-source project. Adding one is a change to this list and to nothing else.

### `wai` — the link to the registry

The registry of capabilities is SPEC §5 and the reference implementation's `wai-rs/src/codecs`. An entry's `wai` field records which registered capability decodes the codec the entry describes, and the two classes the registry gives that capability.

- `licence` and `replicate` are the registry's classes for `capability`, spelled as `wai capabilities` prints them and as [`../registry/capabilities.json`](../registry/capabilities.json) records them (`codecs::capability_license` with `LicenseClass::label`; `codecs::capability_replicate_class` with `ReplicateClass::label`). The registry is the source; the glossary repeats the classes so a reader of this file sees them, and a test holds the two equal.
- An entry links a capability when that capability's payload is the entry's bitstream, in the framing SPEC §5 pins for it. Several entries may link one capability (AAC, HE-AAC and HE-AAC v2 all link `wai.audio.aac`), and one entry may link several (EVC links `wai.video.evc` and `wai.video.evc.baseline`). An entry SPEC §5 excludes from a capability does not link it: xHE-AAC and MPEG-D USAC do not link `wai.audio.aac`.
- The links are a reviewed table in the test (`GLOSSARY_LINKS`), so a reviewer judges each mapping once; the file must match it exactly.
- Every payload and companion capability is linked from at least one entry, or is listed in the test's `GLOSSARY_NO_ENTRY` table with the reason (a WAI-native class, a candidate, a model with no entry yet).

`glossary_links_agree_with_the_registry`, a unit test in `wai-rs/src/codecs/glossary_check.rs`, checks this file against this schema, the allowlist and the registry: the schema version, the fields and values above, unique names, the body allowlist, the link table, the classes, the media class, coverage, the excluded pairs, and the no-comparison rule for `desc`. Each failure names the entry and the rule it breaks.

## Contributing

Two operations:

1. **Add a codec** — append a new entry to `entries[]`. Keep entries roughly chronological within their modality block.
2. **Correct a description** — edit `desc`. Aim for factual density over flair: spec year, the specification or body that defines it, the architectural choice that defines it, its current deployment footprint. No comparisons, no company names, no opinions about quality unless backed by a citation in the description.

A patch that touches `codecs.json` must pass `glossary_links_agree_with_the_registry` (from `wai-rs/`: `cargo test --lib --no-default-features glossary`); the conformance workflow runs it on every change under `wai/glossary/`. A patch that adds a field, an enum value or a `body` value updates this file first, then the test's tables (`GLOSSARY_FIELDS`, `GLOSSARY_ENUMS`), then the site's copy.

## Relationship to the WAI spec

A codec listed here becomes a WAI capability (e.g., `wai.image.jxl`) only when the spec registers it in `SPEC.md §5`. A registration fixes the capability string, its payload format and its role (SPEC §5, §8), and the registry gives the capability a licence class and a replicate class. How a decode of it conforms depends on that class (SPEC §7): bit-exact decode-equivalence for some classes, the named standard's own criterion for others. The glossary documents the wider landscape; the spec selects from it, and an entry the spec has selected says so in its `wai` field.