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 alongside this schema.

The glossary is reference material — it is not the registry of WAI capabilities (that is ../SPEC.md §5, published in machine-readable form as ../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

{
  "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

{
  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 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.