# WAI vocabulary

Stable IRIs for the Web AI Media Transport & Execution open standard, in two
versions. A WAI manifest that carries one of the JSON-LD contexts below expands
into typed RDF triples for any JSON-LD or SPARQL consumer without changing its
wire form. Licence Apache-2.0, matching the reference implementation.

## v2 — generated from the registry

Namespace: `https://wai.transaction.science/vocab/v2#`.

| File | Format | What |
|------|--------|------|
| [`v2.ttl`](v2.ttl) | Turtle (RDF) | One IRI per string SPEC §5 registers, with its kind, status, media class, role, fidelity tier, licence class, replicate class, registering section, edition and registration date (`registeredOn`); the enumerations as individuals named `<class prefix>-<label>` (`kind-companion`, `role-companion`, `media-image`, …), so no two terms share an IRI; and the manifest terms the context maps. |
| [`v2.jsonld`](v2.jsonld) | JSON-LD `@context` | For a WAI manifest, `WAI1` or `WAI2`, as written on the wire: `capability`, `fallback` and a component's `companion_of` expand to capability IRIs, `media` to a media-class individual; `kind` and a component's `role` are plain strings under terms of their own (`payloadKind`, `componentRole`), and `target` is a JSON literal. `prior` (`conditioning.prior`, or a component's) maps its members to the pin terms below. |
| [`v2.shapes.ttl`](v2.shapes.ttl) | SHACL Core | Applies to a manifest with or without an `@type` (it targets every node with a `wai` or `intent` field, and every component of `renditions`). Checks that a `WAI1` names a capability and a `WAI2` a component list, never both; the `capability` and every component's capability against the registered payload and companion capabilities that are not candidates; the `fallback` and a companion's base against the registered payload capabilities that are not candidates. `media` is informational and a reader accepts a value it does not know (SPEC §3, §8), so only its form is checked. The shapes check a manifest against this revision's registry: a violation for a capability or fallback this revision does not register means the string is not registered in this revision, not that the envelope fails to conform or cannot be dispatched, since a later MINOR revision may register it (SPEC §4, §8). Also checks every parameter-set pin, wherever the manifest carries one (below). |

The three files are generated by `wai registry export` from the reference
implementation's registry (`wai-rs/src/codecs/registry.rs`), together with
[`../registry/capabilities.json`](../registry/capabilities.json); a library test
and a CI step fail when they drift. [`check_shapes.py`](check_shapes.py) expands
sample manifests, typed and untyped, through the context and validates them
against the shapes, each with the result it must give; CI runs it
(`.github/workflows/wai-conformance.yml`). Do not edit the generated files by hand —
[`../REGISTRY.md`](../REGISTRY.md) says how a string is registered. The v2 IRIs
resolve only once the website publishes the files.

## v1 — stable

Namespace: `https://wai.transaction.science/vocab/v1#`. The v1 files
([`v1.jsonld`](v1.jsonld), [`v1.ttl`](v1.ttl), [`v1.shapes.ttl`](v1.shapes.ttl))
are stable in this sense: no v1 IRI is removed, and no term changes what it
means, so nothing that already names them breaks. A label or comment may be
corrected, and a term may be added. They cover the first codec menu only (PNG, JPEG, AVIF,
JPEG XL, FLAC, Opus, AV1, zstd, XZ) and model the neural and zeroth paths as
classes; they are not the registry. v1's SHACL shape rejects a manifest that
names any other registered capability, so a validator of current manifests uses
v2.

## The parameter-set pin, in both versions

The parameter-set pin (`wai:ParameterSetPin`, SPEC §3.1) is in v1 as additive terms,
and `wai registry export` writes the same terms into v2: `wai:prior` and the members
`wai:pinId`, `wai:pinSha256`, `wai:pinDeterminism`, `wai:pinForm`, `wai:pinTier` (a
closed vocabulary: `decode-equivalence`, `entropy-consistency`, `none`) and
`wai:pinSupersedes`, with a scoped JSON-LD term `prior` whose members are the
manifest's own names, a `ParameterSetPinShape` and a `SupersedesShape`. In v2 the
tier list is generated from the registered tokens (`codecs::TIER_TOKENS`).
`wai:sharedPriorUri` and `wai:sharedPriorHash` (v1 only) describe a located prior
with a BLAKE3 hash; they are not the manifest's pin. A library test in `wai-rs`
(`container::tests::vocab_pin_terms_match_prior_members`) reads both v1 and v2 and
holds each scoped term's members equal to the pin's serialized members and each
shape's tier list equal to the registered tokens; `check_shapes.py` validates
conforming and non-conforming pins against the v2 shapes.