Descriptive-Layer Import Strategy & Property Categorisation

Context and Problem Statement

ODR-0008 ratified Declare-once-reconcile-overlays: flatten the propertyPack tree and declare each descriptive property once on the Property/legal-estate classes. Session 021 then scheduled the 935-leaf descriptive walk as a “~90 %-mechanical” emission — one annotated PDTF base leaf → one flat owl:DatatypeProperty (ADR-0028). The 2026-05-30 build pass proved the walk is not mechanical: there is no leaf→term map, the existing ~23 descriptive properties were hand-curated, and naive last-segment naming collapses 1,521 distinct leaves into ~351 colliding, permanent, unreversible opda: IRIs. The walk was deferred to “a curated WG pass” — exposing a prior question the schedule had skipped: before curating, what should be imported at all, and at what granularity?

The empirical answer (reproducible from data-dictionary-canonical.json; see the evidence pack): of ~1,493 annotated base leaves, 56 % (840) are ~16 generic recurring tail-segments (details×269, price×99, comments×96, isIncludedExcludedOrNone×89…); 378 enum leaves carry only 54 distinct value-sets; 809 leaf names appear in ≥2 of the 16 schemas (393 in ≥3); the project’s own audit.json flags yesNo as “referenced 1,135 times — not 1,135 unique concepts.” Three structures recur: fixtures = an ~89-item chattel checklist ×3 fields; searches/environmental = one six-field risk-result ×~24 datasets; disclosure = one details slot ×269. The leaf explosion is form-ergonomics + repeated micro-structure, not conceptual richness — PDTF is correct-for-a-form-transport, wrong-altitude-for-a-TBox. Only ~181 distinct names (~12 %) are genuine descriptive concepts. This decision was deliberated by the Linked Data Council at session-023 (Full Council; Queen Allemang; DA Davis; near-unanimous, Q1/Q3/Q4/Q5/Q6 11–0–0, Q2 10–0–1).

Considered Options

• Option A (chosen) — Category-based descriptive-layer import (seven categories A–G). Classify every annotated base descriptive leaf into one of seven property categories and apply each category’s fixed treatment, reserving expensive per-leaf curation for Category G and a regulatory-salience allow-list.
• Option B — Import 1:1 — the mechanical 935-leaf walk (S021 / ADR-0028 as written). Rejected: neither mechanical (collides 1,521 leaves into ~351 colliding permanent IRIs; no leaf→term map) nor governable nor reversible; it is the strictly worse collapse, by accident and without provenance.
• Option C — Import nothing / leave the descriptive layer to forms only. Rejected: fails ODR-0008’s ratified attachment of descriptive facts to real classes and the BASPI5 round-trip MVP gate; consumers get no descriptive vocabulary.
• Option D — Promote every checklist item and search dataset to an OWL class. Rejected: over-engineering — fixture items and enum value-spaces have no per-item identity criterion or lifecycle (Kendall & McGuinness Ch. 5 — SKOS for controlled value/reference sets); a class earns its keep only on a named §Q4a consumer query.
• Option E — Collapse by last path-segment. Rejected: catastrophic mis-binning (swallows the headline priceInformation.price into the chattel price bucket); permanent and unreversible.
• Option F — Curate all ~935 leaves by hand up front. Rejected: the expensive operation this record bounds; ~88 % of leaves are structure with no domain identity criterion, so per-leaf WG judgment on them is wasted.

Decision Outcome

Chosen option: “Option A — Category-based descriptive-layer import”, because the 1:1 walk is the strictly worse collapse (colliding ~1,521 leaves into ~351 accidental provenance-less permanent IRIs), whereas category import collapses by design with provenance preserved, ~5× fewer permanent IRIs, and more query power, while a lean TBox + SKOS schemes + a few classes carry every competency question the 935-leaf version answers.

Adopt category-based descriptive-layer import: classify every annotated base descriptive leaf into one of seven property categories (A–G); apply each category’s fixed treatment (collapse-to-pattern / reuse-upstream / map-to-SKOS-scheme / promote-to-class / curate-per-leaf) realised in the named record; reserve expensive per-leaf curation for Category G (~181 genuine descriptive concepts) plus a small regulatory-salience allow-list carved from A/E; and do NOT import the ~935/1,493 leaves 1:1 as flat datatype properties — chosen because the 1:1 walk is the strictly worse collapse (it collides ~1,521 leaves into ~351 accidental provenance-less permanent IRIs), whereas category import collapses by design with provenance preserved, ~5× fewer permanent IRIs, and more query power, while a lean TBox + SKOS schemes + a few classes carry every competency question the 935-leaf version answers. The collapse is ratified behind three enforceable gates (path-aware binning, schema-leaf-path traceability, coverage-by-test) that convert the Devil’s-Advocate completeness dissent into acceptance criteria rather than a veto.

Consequences

• The ADR-0028 walk is re-scoped, not executed as written. Its target becomes Category G (~181) + the regulatory-salience allow-list, emitted under the path-aware binning rule (G1) with schema-leaf-path dct:source (G2), gated by G3 — not a 935-leaf flat emission. Amend ADR-0028 (or author a successor) to record the bounded, gated scope; the walk stays deferred to the curated WG pass.
• The ADR-0029 overlay profiles MUST enumerate each form’s leaves in their sh:path/sh:minCount/dct:source shapes (they are currently emitted thin) — this is what carries round-trip under G3. The C/D SKOS schemes and the E class become emitter targets alongside the G walk.
• The engineering realization is owned by ADR-0030 (implements: [ODR-0022]): the path-aware classifier (G1), the category emitters (A disclosureDetail / C status-enum schemes / D FixtureItemScheme), the schema-leaf-path sourcing (G2), the ci-descriptive-roundtrip coverage gate (G3), and the in-code holds that keep the curated Category-G IRIs unminted (Categories E and D were emitted 2026-05-30 once their councils discharged — R1 / ODR-0008d and R4 — so only the curated Category-G walk stays held). This ODR decides what is imported and at what granularity; ADR-0030 owns how the generator realizes and enforces it.
• ODR-0011 grows ~54 status-enum schemes + the FixtureItemScheme, each with a named steward; regulator-governed schemes carry authority dct:source. ODR-0009 absorbs Category B and E provenance with no new local terms beyond the E class. A new pattern ODR discharges the E class’s UFO commitment + IC (fires ODR-0008 §Q2a(b)).
• The expensive WG operation shrinks ~80 %: from “evaluate 935 leaves” to “ratify ~5 treatments + curate ~181 G-leaves + a small salience allow-list.” Per-leaf WG judgment is spent only where a domain identity criterion exists.
• Status proposed; adoption flows through the OPDA WG → Modelling Sub-Committee (adoption.md §3). The build may proceed in parallel; status flips on ratification. The three gates are the WG’s acceptance checklist.

More Information

• Council: session-023 — Descriptive-Layer Import Strategy & Property Categorisation (Full Council; Queen Allemang; DA Davis; Q1/Q3/Q4/Q5/Q6 11–0–0, Q2 10–0–1; the DA’s completeness dissent converted into gates G1–G3). Shared evidence: working/session-023/EVIDENCE.md.
• Operationalises: ODR-0008 — Property Descriptive Attributes (Declare-once-reconcile-overlays; §Q1a residue register, §Q2a(b) authority-artefact spawn, §Q3a schema-leaf-path dct:source = G2, §Q4a class-promotion, §Q5a datatype-vs-SKOS, §Q6a flat-default, §Q7a per-form variation → profiles).
• Realizing records: ODR-0009 (B, E provenance); ODR-0011 (C 54 schemes, D FixtureItemScheme); ODR-0010 (per-form profiles carry round-trip); ODR-0015 + ODR-0006 (F reuse); ODR-0007 (D inclusion Mode).
• Realizing engineering ADR: ADR-0030 — Category-Based Descriptive Emission Pipeline & Import Gates (G1–G3) — the opda-gen realization of this strategy (the path-aware classifier, the category emitters, G1/G2/G3 as CI, the in-code boundary holds); implements: [ODR-0022].
• Cross-corpus ADRs: ADR-0007 — Ontology generator specification (the deterministic-emission + byte-identity discipline ADR-0030 extends); ADR-0028 (re-scoped to G + salience allow-list); ADR-0029 (profiles enumerate per-form leaves).
• Data: source/00-deliverables/semantic-models/data-dictionary-canonical.json (8,458 entries / 16 schemas), audit.json (the reusable-pattern inflation: yesNo ×1,135, etc.), business-glossary.md (trust-framework/API terms — does NOT define the descriptive properties; their meaning is the schema title).
• External citations (from the session, per ODR-0001 §Citation grounding): Kendall & McGuinness 2019 Ontology Engineering (message-model vs reference-ontology; identifiers are commitments); Guizzardi 2005 + Guarino & Welty 2002 OntoClean (no-IC ⇒ not a sortal worth minting); SKOS Reference (W3C 2009) §3 + Singapore Framework (Nilsson/Baker/Johnston 2008, reuse-before-mint); W3C SHACL Recommendation + TopBraid EDG (shapes describe what data looks like, not what it is); Linked Data principles + Cool URIs Don’t Change (Berners-Lee) + Hendler 2003 “A Little Semantics Goes a Long Way”; BBC /programmes/ ontology (Davis 2009).

Rules

Normative for the descriptive-layer import (propertyPack tree + participant/chain descriptive leaves). This record decides granularity, routing, and acceptance gates; each category’s binding ontological commitment (UFO meta-category + identity criterion) is discharged in its realizing pattern record, cited below.

1. The property-category taxonomy (A–G) — treatment + realizing record

Every annotated base descriptive leaf MUST be assigned to exactly one category. The treatment is fixed per category; the per-category ontological commitment is owned by the realizing record.

Net: ~5 reusable patterns + ~56 SKOS schemes + ~2 classes + upstream reuse replace ~750 flat properties; only Category G + the salience allow-list is curated per-leaf.

C vs G — the binning boundary (clarified after session-025). A leaf is G when it is a genuine Property/estate attribute even if it carries an enum — currentEnergyRating, councilTaxBand, builtForm, tenureKind are G, their value-space becoming a SKOS range (ODR-0008 §Q5a: “Quale-in-Region → SKOS scheme; Quality of opda:Property”), not Category-C membership. C is reserved for the reused status value-spaces (Yes/No, Included/Excluded/None, Attached/To-follow) that recur as cross-cutting flags. A path-aware binner MUST NOT route an enum-bearing genuine attribute to C on the strength of the enum alone — the ADR-0030 §G1 categoriser defect (if has_enum → C) over-captured these flagship Quale attributes. The binner has since been corrected (S025 fix applied — the §Q5a-named Quale attributes route to G before the enum fallback), lifting the candidate-G count from 182 to 188 (C 159 → 153).

2. The three ratification gates (the collapse is ratified only behind these)

These are the acceptance requirements the import must satisfy — what must hold for the collapse to be sound. Their realization and CI enforcement live in ADR-0030 (the path-aware classifier, the schema-leaf-path sourcing, the ci-descriptive-roundtrip gate, the byte-identity discipline): this ODR states the requirement, ADR-0030 states the mechanism.

On G1 + G2 + G3 passing, the DA’s S021 completeness-as-a-gate dissent is withdrawn in full.

3. Regulatory-salience carve-out

The A↔G and E↔G boundaries are drawn by regulatory salience, not segment name. A generic-tailed leaf (details, result) whose parent question is regulator-named — Building Safety Act, EWS1/cladding, spray-foam, Japanese knotweed, a named CON29 search peril, a regulator-governed value-space (EPC band A–G is DESNZ-governed; council-tax band A–I is VOA-governed) — is curated as Category G regardless of its tail, and its value-space scheme carries dct:source to the governing authority. Generic shape collapses; regulatory substance does not. This realises ODR-0008 §Q4a (distinct-lifecycle / distinct-PII promotion) at binning time.

4. The D Object/Mode split (normative)

A fixtures-checklist item is NOT a datatype Quality of opda:Property. The item (boilerImmersionHeater) is an Object/Kind → a skos:Concept in opda:FixtureItemScheme. Its inclusion (“Included / Excluded / None”) is a Mode/Relator of the sale transaction (ODR-0007 territory) — the same boiler is included in one sale and absent from the next — modelled as opda:inclusionStatus on a transaction-scoped fixtures list, never as a property of the brick-and-mortar. price reuses a MonetaryAmount pattern.

5. The residue register (no silent loss)

Categories A–F are not exhaustive by construction. A leaf that resists every pattern routes to the ODR-0008 §Q1a reconciliation register with a recorded disposition. “Collapsed” MUST mean recorded as collapsed; a leaf is never silently dropped.

6. Anti-patterns (the reasons this record exists)

• Do NOT mint one owl:DatatypeProperty per annotated leaf (the S021 1:1 walk). It is neither mechanical (no leaf→term map; collides 1,521→~351) nor governable (900 permanent form-slot IRIs) nor reversible. Its only argument was one-time generator convenience; the build pass removed even that.
• Do NOT bin by last path-segment (G1). details×269 and price×99 are not one concept each.
• Do NOT collapse Category G or the salience allow-list — these keep term-grain, one dereferenceable opda: IRI per concept.
• Do NOT flatten the peril/dataset axis (E) or a regulator-named disclosure (A) into an opaque string — flatten the shape, keep the scheme.
• Do NOT re-mint Category F (address/contact/geo) — reuse ODR-0015/0006.
• Do NOT point dct:source at the deciding ODR (G2) — point at the schema leaf path.