SKOS vocabulary emission

Context and Problem Statement

ODR-0011 ratifies the SKOS substrate: every JSON enum becomes a skos:ConceptScheme; per-member skos:prefLabel @en + skos:notation + skos:definition @en; per-scheme UFO meta-category declaration (seven-category framework — Quale-in-Region; Role label; Phase label; Method/plan code; Quality Region; Substance Kind label; Quality Value).

This ADR ratifies the engineering emission of those schemes as opda-vocabularies.ttl. The substrate must land before any module ADR (ADR-0011) because every kind: pattern module references SKOS schemes for category-like attributes.

Inputs to the emission:

• ~160 enum leaves from pdtf-transaction.json + overlay schemas (built-form; council-tax band; EPC band; tenure kind; central-heating fuel type; participant status; assurance level; etc.).
• ODR-0011 §8a seven-category UFO framework (which category each scheme commits to).
• Per-scheme dct:source to glossary or regulator (ODR-0011 §4a verbatim-citation for regulator-governed concepts).
• ODR-0011 §5a SHACL-AF deprecation-chain rule (Cagle).
• A9 per-kind discipline output (UFO category + IC + artefact realisation).

Decision space:

• Scheme-level structure: per-scheme skos:ConceptScheme + per-member skos:Concept.
• Naming convention for scheme URIs (opda:BuiltFormScheme) and member URIs (opda:builtForm/Detached).
• Per-member metadata depth (prefLabel + notation + definition; optional broader/narrower; deprecation lifecycle).
• UFO category declaration mechanism (dct:source + skos:scopeNote).
• Cross-vocab mapping placement (deferred per Phase-3.5 audit; admission case-by-case).

Decision Drivers

• ODR-0011 ratification is dense — every member metadata field, every UFO category, every regulator-citation rule is in ## Rules or ## Operational specifications. Engineering applies; it does not re-deliberate.
• A9 per-kind discipline (ODR-0001 §What an ODR records) requires the UFO category + IC + artefact realisation MUST land for kind: pattern schemes. ODR-0011 is the meta-ODR; each scheme is itself a pattern instance.
• Regulator-governed concepts (ODR-0011 §4a) require verbatim-citation discipline for PII categories (DPV-PD scope-note discipline; Pandit’s S011 Q4 amendment).
• Deprecation lifecycle (ODR-0011 §5a — Cagle SHACL-AF deprecation-chain rule): retired members carry dct:isReplacedBy / prov:wasDerivedFrom / dct:modified per case.
• Cross-vocab mapping is case-by-case admission per Phase-3.5 audit. Initial emission does NOT include skos:exactMatch to external vocabs; admission triggers convene per-scheme mini-sessions.

Considered Options

• A — One skos:ConceptScheme per JSON enum, separate file per scheme. Pro: per-scheme isolation. Con: ~160 files; file-naming churn; downstream owl:imports overhead.
• B — One unified opda-vocabularies.ttl with all schemes (chosen). Pro: single file; one owl:imports from each module; CI byte-identity straightforward. Con: large file (~3000 lines projected); but TTL is text — large is fine.
• C — Per-module vocabularies (vocabularies.ttl per module ADR). Pro: scope-local. Con: cross-module reused schemes (e.g. participantStatus used by Agent + Transaction) duplicated; reconciliation overhead.

Decision Outcome

Chosen option: B — One unified opda-vocabularies.ttl, because cross-module reuse is high (the same Phase label scheme drives Agent + Transaction; the same Quale-in-Region scheme drives Property + Address Variants), single-file emission has lower import overhead, and CI byte-identity is mechanically straightforward.

Emission structure

# opda-vocabularies.ttl — OPDA SKOS Concept Schemes
# Generated by opda-gen <version>; DO NOT HAND-EDIT.
# Schemes per ODR-0011 §1a + ODR-0011 §8a seven-category UFO framework.
# Per-scheme deprecation lifecycle per ODR-0011 §5a SHACL-AF pattern.

@prefix opda:    <https://w3id.org/opda/#> .
@prefix opda-v:  <https://w3id.org/opda/vocabularies/> .
@prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
@prefix dct:     <http://purl.org/dc/terms/> .
@prefix prov:    <http://www.w3.org/ns/prov#> .

# --------------------------------------------------------------------
# Scheme 1 of N: BuiltFormScheme — Quale-in-Region
# Source ODR: ODR-0008 §Q5a + ODR-0011 §8a
# --------------------------------------------------------------------

opda:BuiltFormScheme
    a skos:ConceptScheme ;
    skos:prefLabel "Built Form"@en ;
    dct:title "Property built-form classification"@en ;
    skos:definition "Classification of a Property's structural built-form (detached, semi-detached, terraced, etc.)."@en ;
    dct:source <https://w3id.org/opda/odr/ODR-0008#section-q5a> ;
    opda:ufoCategory "Quale-in-Region" ;
    skos:scopeNote "UFO: Quale-in-Region (Guizzardi 2005 Ch. 4). DOLCE: Quality-Region (Masolo D18 §4.3)."@en ;
    opda:hasSteward "Allemang (property-qualities sub-module steward per S008 Q2)"@en ;
    .

opda:builtForm/Detached
    a skos:Concept ;
    skos:inScheme opda:BuiltFormScheme ;
    skos:prefLabel "Detached"@en ;
    skos:notation "Detached" ;
    skos:definition "Free-standing dwelling sharing no walls with neighbouring properties."@en ;
    dct:source <https://w3id.org/opda/data-dictionary#builtForm.Detached> ;
    .

opda:builtForm/Semi-detached
    a skos:Concept ;
    # ... (similar structure)

# Continue per scheme + per member …

# --------------------------------------------------------------------
# Scheme N: CouncilTaxBandScheme — Quale-in-Region
# --------------------------------------------------------------------

opda:CouncilTaxBandScheme
    a skos:ConceptScheme ;
    skos:prefLabel "Council Tax Band"@en ;
    dct:source <https://www.gov.uk/council-tax-bands> ;  # Regulator-cited per ODR-0011 §4a
    opda:ufoCategory "Quale-in-Region" ;
    skos:scopeNote "Verbatim source: Valuation Office Agency banding for England + Wales (Bands A-H); Scottish equivalent (Bands A-I) handled as separate scheme."@en ;
    .

# … (full per-scheme emission per ODR-0011 §1a)

Scheme catalogue (initial first batch)

Per-scheme emission inherits ODR-0011 §8a categories. Initial first-batch schemes from the data dictionary:

Plus per-scheme deprecation tracking via ODR-0011 §5a SHACL-AF rule (Cagle’s opda:DeprecationChainRule).

Per-scheme metadata MUST-haves (per ODR-0011 §1a + §8a + A9)

For every scheme, the emission MUST land:

1. skos:prefLabel @en — exactly 1 (ODR-0011 §S14/S15).
2. dct:title @en (catalogue display).
3. skos:definition @en (one canonical definition).
4. dct:source to authoritative origin (W3C spec / OPDA TF / business glossary / data dictionary / external regulator — five-line precedence per ODR-0004 §7a).
5. opda:ufoCategory declaration (one of seven; ODR-0011 §8a).
6. skos:scopeNote @en with UFO + DOLCE backing reference (Guizzardi 2005 chapter / Masolo D18 section).
7. opda:hasSteward (per S008 Q2 module-owner-proposes; ODR-0011 §1a).

For every member, the emission MUST land:

1. skos:inScheme (scheme URI).
2. skos:prefLabel @en — exactly 1.
3. skos:notation — exactly 1 (canonical machine-readable form).
4. skos:definition @en — exactly 1 (per ODR-0011 §S14/S15).
5. dct:source to per-member canonical origin.

Deprecated members additionally carry one of three lifecycle predicates per ODR-0011 §5a:

• dct:isReplacedBy <new-member> (clean supersession).
• prov:wasDerivedFrom <prior-form> (lineage-only; no supersession).
• dct:modified <date> (in-place modification with audit trail).

SHACL-AF rule emission (Cagle’s deprecation-chain rule)

Per ODR-0011 §5a + ODR-0017, the deprecation discipline is enforced by a SHACL-AF rule. The rule emits into opda-shapes.ttl (per ADR-0012 emission); the rule body is:

# DeprecationChainRule — non-blocking sh:Info
PREFIX opda: <https://w3id.org/opda/#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

CONSTRUCT {
  ?member opda:hasDeprecationChainStatus "missing-replacement-link"^^xsd:string .
}
WHERE {
  ?member a skos:Concept ;
          skos:inScheme ?scheme .
  FILTER NOT EXISTS {
    ?member dct:isReplacedBy|prov:wasDerivedFrom|dct:modified ?lineage .
  }
  FILTER NOT EXISTS {
    ?member skos:hasTopConcept ?member .  # Active concepts allowed
  }
  # ... (full rule per ODR-0011 §5a)
}

Materialised at sh:Info severity (ODR-0017 non-blocking).

Consequences

• Good, because the SKOS substrate is one file, atomically emitted; downstream module ADRs cite it once via owl:imports.
• Good, because A9 per-kind discipline output is mechanical — every scheme carries opda:ufoCategory + skos:scopeNote UFO + DOLCE citations.
• Good, because regulator-cited schemes (CouncilTaxBand, EPC band, etc.) honour ODR-0011 §4a verbatim-citation discipline at emission time.
• Good, because deprecation-chain SHACL-AF rule (Cagle) emits into the shapes graph for non-blocking quality monitoring.
• Good, because per-scheme steward attribution (per S008 Q2) lands in metadata, supporting downstream amendment proposals.
• Bad, because the file is large (~3000 lines projected for ~160 schemes). Mitigation: rdflib + canonical serialiser handle large TTL fine; reviewer cognition is the cost, not parser.
• Bad, because skos:exactMatch to external vocabs is deferred (per Phase-3.5 audit). Some downstream consumers may request cross-vocab mapping earlier than expected. Mitigation: per-scheme admission via Author-only mini-sessions per Phase-3.5 audit Item 2.
• Neutral, because some schemes have ratified UFO categories (per ODR-0011 §8a explicit list) and others are inferred from the data dictionary; the inference rule is mechanical (data-dictionary leaf shape → category).

Confirmation

The ADR is honoured when all six hold:

1. Emission lands. opda-gen emit-vocabularies produces opda-vocabularies.ttl in source/03-standards/ontology/.
2. Byte-identity CI green. Regeneration produces zero diff.
3. Three-graph CI test green. No sh:* triples in vocabularies file (vocabularies live in classes-side per ODR-0004 §3a; deprecation-chain SHACL-AF rule lives in shapes file).
4. Every scheme carries UFO category. SPARQL: SELECT ?s WHERE { ?s a skos:ConceptScheme . FILTER NOT EXISTS { ?s opda:ufoCategory ?c } } returns empty.
5. Every scheme + member carries dct:source. SPARQL check on scheme + member levels.
6. Cardinality discipline honoured. SHACL validates that every skos:Concept has exactly 1 skos:prefLabel @en, exactly 1 skos:notation, exactly 1 skos:definition @en (per ODR-0011 §S14/S15).

Manual test: opda-gen emit-vocabularies && pyshacl -s opda-shapes.ttl -d opda-vocabularies.ttl → no violations.

Programme-wide validation gate (per ADR programme plan §9 — Validation discipline). In addition to the ADR-specific criteria above, this ADR moves proposed → accepted only when all four of the following hold (independent of the worker that implemented this ADR):

• (a) Soundness check PASS — every emitted artefact traces to a cited ODR/ADR ## Rules or ## Operational specifications clause via dct:source (for Turtle) or code-comment provenance header (for Python). The validation agent extracts emitted-artefact provenance and verifies each resolves to a ratified section.
• (b) Completeness check PASS — every cited ODR’s ## Rules and ## Operational specifications subsection is realised by an emitted artefact OR explicitly deferred with a named follow-up trigger. The validation agent enumerates cited subsections and checks coverage.
• (c) Cross-ADR consistency check PASS — every downstream ADR’s confirmation criteria can be met given this ADR’s emission (e.g. classes emitted here are referenceable by downstream shapes; shapes here are composable by downstream profiles). The validation agent simulates the downstream contract against this ADR’s output.
• (d) Validation report committed at docs/adr/validation/ADR-0010-validation-report.md, produced by an independent validation-agent spawn (NOT the implementing worker; mirrors the Council Devil’s Advocate independence per ODR-0001 §Roles for every session; see ADR programme plan §8 swarm orchestration topology).

A FAIL on any of (a)–(d) blocks accepted status; the implementing worker amends and validation re-runs. Two consecutive validation failures on the same ADR escalate to a Council mini-session per ODR-0001 §Self-amendment process — engineering does not re-deliberate; surfaced ## Rules ambiguity routes to Council ratification.

More Information

• Council-ratified inputs: ODR-0011 §1a + §4a + §5a + §7a + §8a. The full ratified substrate this ADR concretises.
• Predecessor ADR: ADR-0009 — Foundation TTL emission. Foundation must land first.
• Sibling content: ODR-0017 — SHACL-AF non-blocking quality rules. The deprecation-chain rule emits into opda-shapes.ttl per ADR-0012.
• Subsequent emission ADR: ADR-0011 — Module TBox emission. Module classes attach to the SKOS schemes emitted here.
• Phase-3.5 audit interaction: Per-scheme skos:exactMatch cross-vocab admission deferred to per-scheme Author-only mini-sessions; this ADR’s emission does NOT include cross-vocab mappings.
• Steward declaration source: S008 Q2 ratified per-sub-module stewardship; this ADR’s steward attribution per scheme inherits.

Amendments

• 2026-05-27 — Implementation landed (commit 75337ec). source/03-standards/ontology/opda-vocabularies.ttl emitted (879 LOC, 656 triples, 16 schemes, 88 concept members) via opda-gen-0.2.0. All six §Confirmation criteria PASS. Three-graph CI green (no sh:* in vocabularies); byte-identity CI green (foundation + vocabularies; per-file emit-vocabularies gate added in .github/workflows/ontology-byte-identity.yml). Foundation owl:versionIRI bumped 0.1.0 → 0.2.0 to track the substantive substrate addition. Closed queued follow-up G7 (two prefix-filter regression tests added covering gov.uk URLs in skos:scopeNote @en Literals). Queued G8 (scope expansion — admit additional schemes case-by-case per downstream demand) + G9 (data-dictionary enums for MilestoneKind / AssuranceLevel / EvidenceMethod / AddressVariant — emitted with PLACEHOLDER warnings per the brief’s option (a) routing). Test suite grew 34 → 51 (15 vocabularies + 2 G7 regression). Implementation report at docs/adr/implementation-reports/ADR-0010-implementation.md.
• 2026-05-27 — Independent validation PASS-WITH-FOLLOW-UPS (commit 55f09ad). Soundness 37 PASS items; Completeness 16 ODR-0011 subsections + 9 named-trigger deferrals + 0 silent gaps; Cross-ADR 6/6 + 8/8 probes. All four worker-flagged within-engineering ambiguities (TransactionStatus 5-phase canonical; dual dct:source; OwnershipType NTS2 4-set; CurrentEnergyRating A–G) independently affirmed as within-engineering — no Council Author-only sessions recommended. G7 closure verified. New follow-up G10 surfaced: 5 TransactionStatus members emit fabricated dct:source URI fragments (<...#status.Listed> etc.) that don’t appear in the data-dict status enum; three remediation options offered; MUST land before ADR-0014 BASPI5 round-trip. Status moves proposed → accepted. Validation report at docs/adr/validation/ADR-0010-validation-report.md.