Spec-companion vocabulary
type: Ontology
description: 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.
preferred namespace prefix: sc
created: 2026-07-06
license: MIT

Companion document
type: Class
comment: 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
type: Class
comment: 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
type: Class
comment: 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.
source: README.md

Test gap
type: Class
comment: 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
type: Testability level
notation: E
definition: 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
type: Testability level
notation: A-int
definition: 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
type: Testability level
notation: A-exist
definition: 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
type: Testability level
notation: P
definition: 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
type: Property
domain: Companion document
comment: Links the companion document to the IRI of the full-text specification it describes. Exactly one.

spec version
type: Property
domain: Companion document
comment: 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
type: Property
domain: Requirement
range: Testability level
comment: Exactly one testability-spine level per normative statement.

anchor
type: Property
comment: 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)
type: Property
domain: Conformance class
comment: The anchor in the full-text specification where this conformance class is defined.

test gap
type: Property
domain: Requirement
range: Test gap
comment: 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
type: Property
domain: Requirement
range: Requirement
comment: 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
type: Property
domain: Companion document
comment: 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
type: Property
comment: 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.