Spec-companion vocabulary
Minimal terms for machine-readable normative-statement companions to the @jeswr specification family. Complements (never replaces) http://www.w3.org/ns/spec#: the companion model is the Solid Protocol's RDFa requirement model, published as a sidecar Turtle graph, extended with the certification testability spine and honest test-gap accounting.
Companion document
A machine-readable normative-statement graph published ALONGSIDE a full-text specification, which it describes but never replaces. Carries provenance (who extracted it, from which pinned spec version) and the extraction notes (ambiguities the extraction surfaced).
Conformance class
A class of products the specification binds requirements to (e.g. a resource server, a client). Every spec:requirementSubject in a companion MUST be one of the companion's declared conformance classes — this is what makes the actor binding closed and checkable.
Testability level
The testability spine: HOW conformance to a normative statement can be checked. Ported from the Solid-certification v2 testability spine (E / A-int / A-exist / P). Exactly one level per statement; the level is a claim about the statement as written, not about whether a test currently exists.
Test gap
An honest, described justification for a normative statement having no linked conformance test (the per-statement analogue of agentic-solid-conformance's GAPS.md). A mandatory (MUST/MUST NOT) statement tagged Enforceable must link a test case OR a test gap — never neither.
Enforceable / deterministically testable
Conformance is checkable by a deterministic black-box test: a conformance vector or request/response exchange whose expected outcome is fixed by the statement (a conformant implementation refuses the non-conformant action, or produces the pinned output).
Accountable, integrity-verifiable
Conformance is checkable by independently verifying an artifact the implementation produces (a signature, a derivation, a hash, a provenance chain) — the action itself is not refused at request time, but its trail re-verifies cryptographically or structurally.
Accountable, audit/inspection only
Conformance is observable only by audit or inspection, not by a deterministic black-box vector: negative internal properties (MUST NOT log/persist a key), timing disciplines (constant-time comparison), concurrency properties (atomicity under race), and deployment topology (where TLS terminates). Never certifiable as a guarantee; disclosed, not proven.
Premature / not testable as specified
The statement has no testable property as written (the behaviour is unreachable in practice, the hook is unspecified, or the referenced mechanism is not yet stable). A P tag is a signal to the spec editor, not a licence to skip: it must carry a justification.
companion of
Links the companion document to the IRI of the full-text specification it describes. Exactly one.
spec version
The exact version of the full text this companion was extracted from — a git commit sha or a dated-version identifier. The companion is stale (and its repo's gate should fail) when the spec moves without the companion.
testability
Exactly one testability-spine level per normative statement.
anchor
The resolvable section (or element) anchor in the PUBLISHED full-text specification where this statement lives — always under the spec's own base IRI, always carrying a fragment. This is the human path back from the graph to the prose.
defined by (anchor)
The anchor in the full-text specification where this conformance class is defined.
test gap
Links a statement with no conformance test to its honest justification. The guardrail: an Enforceable MUST/MUST NOT statement carries spec:testCase or sc:testGap — never neither. Multiple statements may share one gap node.
restates
This statement restates (consolidates, or is the consolidated form of) another statement in the same specification — e.g. a fail-closed rules section repeating a requirement stated where the mechanism is defined. Keeps the statement inventory deduplicated without hiding that the prose says it twice.
extraction note
An ambiguity or authoring defect the extraction SURFACED in the full text: normative-by-context algorithms with no BCP 14 keyword, lowercase 'may/should' used normatively, non-BCP14 keyword forms ('REQUIRES'), multi-keyword sentences. Extraction notes are errata candidates for the spec editor — the companion records them rather than silently papering over them.
formal model
Optional link from a specification or statement to a machine-checked formal model of the behaviour (TLA+, Alloy, or an executable state-machine description). A seam, not a phase-1 requirement: protocol/state-machine specs with a security core (session establishment, anti-replay windows) are the intended users.