The normative shape of GET /manifest and the shared vocabulary that requires and provides name across modules. canon/11 says why; this says exactly what. Written 2026-08-17 at the session's default effort (high) as a first cut; the field registry in particular wants a deeper pass before the first two modules build against it (../PLAN.md, nudges).

Audience: anyone publishing a manifest, generating UI from one, or writing the composer that will read them.

Top level#

A capability#

Capability ids are <domain>.<verb>[.<qualifier>], lowercase, dotted: content.generate, parttype.match, attribute.normalize, image.generate, extract.pages, judge.copy. A judge is a capability. Batching is not a qualifier: a capability that prefers batches declares a run_batch entry point (runner-verbs.md) under the same id.

Requirements#

A requirement names an input the capability wants beyond the raw item, and where it may come from. It is a table so the generator builds it the way it builds the two above; the hand-written example that used to sit here is now canon/11.

Where a field lives. A registry id IS its path. part.type is read at items[].input.part.type on the way in and written at output.part.type on the way out, dotted id as nested path, so a composer holding two manifests can move a value from one module's outcome into the next module's item without opening either schema. A capability whose output schema puts a provided field anywhere else is not conforming (Banned, below).

This is the whole composability hook. A standalone caller supplies the field in the item input and never reads from. The console (or the future composer) reads from to know that a parttype.match job before this one can fill it. The field id names the value; the path rule places it.

The field registry#

A shared vocabulary of item field ids, so provides in one module and requires in another, and the console's own Field concept, name the same thing. Registry entries are <domain>.<name>, lowercase, dotted, with a type and a one-line meaning. The registry lives in this file until it outgrows it.

First cut, from what the three instances and the owner's draft actually pass around. Marked seed because the first two modules will change it:

Each registry entry will also carry a presentation hint (type family, unit, tone) mapping onto kit cell types (text, number with unit, status tone, timestamp, link, chip list), so an app can render fields with the kit's column factories without a module ever describing layout (vb-fable, 2026-08-18; ../BACKLOG.md).

Rules for the registry:

• A capability's provides and requires use registry ids only. A new field is a registry change, reviewed like a schema change.
• The registry does not fix the JSON Schema of every field's value; it fixes the id, the type family, and the meaning. Capabilities that write attributes.normalized all mean the same thing by it, and their output schemas say the exact shape.
• Tenant-specific vocabularies (a customer's taxonomy ids, their attribute names) are values, not registry ids. part.type is the field; the tenant's taxonomy is what fills it.
• Growth: adding a registry id is a contract_version minor bump; a validator that meets an id it does not know WARNS and does not reject, so an older console keeps working against a newer module. Renaming or retyping an id is a major bump.
• The x. prefix is reserved for ids that are deliberately not shared (one module's private field); an x. id may appear in provides and never in requires.
• review.reason is not a registry field: why an item was held is the outcome's needs_review.reason, an app mirrors it, and no capability provides or requires it.

Surface, identity, runtime#

"surface":  { "routes": ["POST /jobs", "GET /jobs", "GET /jobs/{job_id}", "GET /jobs/{job_id}/envelope",
                         "GET /jobs/{job_id}/outcomes", "GET /jobs/{job_id}/outcomes/{item_id}",
                         "GET /jobs/{job_id}/outcomes/{item_id}/log",
                         "GET /jobs/{job_id}/errors", "GET /jobs/{job_id}/review",
                         "GET /jobs/{job_id}/outputs", "GET /jobs/{job_id}/outputs/{name}",
                         "GET /jobs/{job_id}/stats", "POST /jobs/{job_id}/cancel",
                         "GET /stats", "GET /usage/events",
                         "GET /health", "GET /health/deep", "GET /build-info", "GET /manifest", "GET /guide"],
              "page_size": { "default": 100, "max": 1000 },
              "callbacks": { "events": ["job.state", "item.outcome", "usage"], "signature": "hmac-sha256", "max_batch": 500 } }
"identity": { "verifier": "jwks" | "keys" | "remote" | "local", "issuer": "https://id.versable.ai", "audience": "content",
              "scopes": ["jobs:submit", "jobs:read", "jobs:cancel", "stats:read", "stats:admin"] }
"runtime":  { "queue": "cloudtasks" | "arq" | "in-process", "storage": "gcs" | "s3" | "local",
              "in_process_supported": true, "topology": "self-push" | "api-worker" }

Validation#

A manifest is itself validated against contracts/manifest.schema.json, generated from the field tables in this file by scripts/build-manifest-schema.py (the runner template's step 1 produced it, ../plans/runner-template.md; --check exits 2 when the file is stale). The generator reads only the Field, Type and Required columns and the registry ids; a Meaning cell is prose and binds people, not the schema. Type cells therefore use a small grammar: string, integer, number, bool, RFC 3339 string, array of <type>, map of <key> to <type>, one of a, b, c for a closed set (never a bar, which breaks the table), >= n for a bound, at least one for a non-empty array, {name: type, other?: type} for members, map of one of a, b to <type> for a map whose keys are pinned, the named type registry id (the enum of field ids in this file's registry table), and the named type duration, a string matching ^([0-9]+[hdy]|never|ttl)$ (7d, 90d, 1y, never; ttl only for the caches class), the spelling canon/11 uses. Membership constraints written in prose (default one of options, default one of levels) are conformance checks, not schema. params, item and output are asserted to be objects and no more; the kit's lintSchema below owns their vocabulary. contracts/conformance.md checks that a live module's behaviour matches its manifest: every listed route exists, every emitted code is listed, every honoured setting is listed, ceilings are enforced.

The params, item and output schemas are full JSON Schema draft 2020-12 (owner ruling 2026-08-18: "the contract stays wide"). The kit's form vocabulary is GUIDANCE for a module that wants its params rendered by SchemaForm without a hand-built form, not a gate on the manifest: the kit's lintSchema(schema) (@versable-git/ui, packages/ui/src/schema-form/lint-schema.ts, contract doc packages/ui/docs/schema-form.md, subset per versable-builder docs/plan/65-schema-form-spec.md section 6) refuses by name, at a JSON Pointer, anything outside that subset and returns {ok, plan} or {ok, refusals[]}; a module runs it when it is ready to ship a generated form, and a params schema outside the subset is rendered by a hand-built form or the JSON view, never rejected by the runner. The four V1 modules' params schemas start from the fixtures at versable-builder docs/plan/65-schema-form-fixtures/{enhancement,image-generation,attribute-normalization,part-type-matching}.params.schema.json, which are the vocabulary's worked examples; a manifest that diverges from its fixture is either a lapse or a fixture correction, and the instance doc says which. contracts/conformance.md MAY run the lint over a published manifest as an advisory row (foundry-2), never a failing one.

Two rules that hold whatever vocabulary a params schema uses, because the runner validates the submitted params against the schema on create (canon/03) and knows nothing about form-only keys: a field hidden by a form-only condition (x-when, x-tier) MUST NOT be required at the schema level unless it sits inside a discriminated oneOf branch that JSON Schema itself selects, since a hidden required field is a guaranteed 422; and x-when may reference $settings.<key> only for keys the capability lists in settings, because that object is the job's settings block, not app-private context.

Standard settings#

The per-job overrides every module names the same way, so an app carries no translation table. A capability lists the ones it honours in settings; it may add settings under its own <domain>. prefix and may not rename these.

Banned#

• A capability id that is not <domain>.<verb>[.<qualifier>].
• A provides or requires entry that is not a registry id.
• A provided field whose value sits anywhere but at its id's path in output, or a required field read from anywhere but its id's path in items[].input.
• An x. registry id in requires.
• A meters list that repeats a standard meter.
• A skipped outcome whose reason is outside duplicate, filtered, cancelled, superseded.
• An error_type or review_reason emitted at runtime and absent here.
• A settings key honoured at runtime and absent here.
• A manifest at 0.2 or later that omits ceilings, cost_model, or retention; at 0.1 a capability may omit review_reasons, confidence, ceilings, settings, cost_model and log and its instance doc says which, so no invented number enters a machine-readable file (review v2 J4).
• Two capabilities in one module with the same id and different schemas; that is a version bump or a new id.