f93f7074d8
Brings link 12's three follow-up commits onto link 13: the restated ranking phrases in the research notes, extensions and source comments, with five more phrases in the comparative-prose check; the WAI name list given only to the push-to-main run; and the codec glossary's schema_version. One conflict, wai/vocab/README.md: link 13's rows (the prior term in the JSON-LD context, the parameter-set pin in the shapes) are kept, and link 12's sentence on what a violation for an unregistered string means is added before the pin sentence. REGISTRY.md's row for the v2 files now also names the parameter-set pins the shapes check. Co-Authored-By: Claude Opus 5.5 <[email protected]>
54 lines
4.7 KiB
Markdown
54 lines
4.7 KiB
Markdown
# 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.
|