RML as OPDA’s Bidirectional Schema-Provenance Verification Mechanism

Context and Problem Statement

ODR-0004 §7a establishes the term-sourcing-and-provenance convention: every minted opda: term carries a dct:source citation to its authoritative origin, resolved by a five-tier precedence (W3C spec > OPDA Trust Framework > regulator > business glossary > canonical schema-dictionary leaf). This is a real, working discipline — but it has two structural limits that ODR-0004 does not address.

First, dct:source is a single-valued citation of a term’s authoritative definitional origin, not a record of every place the term’s data actually occurs in the PDTF v3 JSON schemas. A shared, domain-less property (opda:name, opda:price, opda:amount) legitimately occurs at dozens of distinct schema locations, but carries exactly one dct:source — the convention has no way to express “and also here, and here.” Second, and more materially: nothing independently verifies that a dct:source citation actually resolves to something real. Auditing the ontology’s own dct:source citations against the canonical schema dictionary this session found 8 citations with a precise, locatable path drift (the field exists, cited under a stale or incomplete nesting) and 16 with no matching field anywhere in the current v3 schema at all — defects that predate this work and that the generator’s own emission process never caught, because nothing checked the citations back against the schema.

Dublin Core Terms itself gives no help here: dct:source is formally “a related resource from which the described resource is derived” — a plain resource-to-resource relationship. DCMI is silent on structural or positional references within a document; OPDA’s practice of encoding a dotted JSON path into the citation target’s IRI local name is an internal convention, not something DCMI provides or requires.

The problem: OPDA needs a mechanism that (a) can express many-to-one and one-to-many correspondence between schema locations and ontology terms, (b) is independently, mechanically checkable in both directions — every resource traces to a real schema location, and every schema location that has been used traces to a resource — and (c) does not require inventing a bespoke correspondence format when a W3C-track standard already exists for exactly this problem.

Considered Options

Option A — Rely solely on the existing dct:source convention (status quo). Rejected: single-valued, cannot express multiplicity, and — demonstrated this session — nothing verifies the citations resolve to anything real. The drift found (8 stale, 16 unresolved of 570 citations) was invisible under this convention alone.
Option B (chosen) — Adopt RML (RDF Mapping Language) as an independent, bidirectional, machine-checkable provenance trace, used purely as declarative documentation. RML is a W3C submission purpose-built for expressing structural correspondence between a source format (here, JSON Schema) and RDF — native support for iteration, joins, and per-value multiplicity that dct:source’s single citation cannot express. Adopted here explicitly as a documentation and verification artefact, not an executable ETL pipeline — no PDTF transaction instance data is used or generated as part of this decision; the mapping is validated structurally against the ontology and the canonical schema dictionary, never against live instance data.
Option C — Invent a bespoke correspondence format (e.g. custom JSON-Pointer annotations, ad hoc SPARQL CONSTRUCT rules). Rejected: reinvents a solved problem. RML already has tooling (morph-kgc), a test-suite lineage, and a community of implementations; a bespoke format would have none of that and would need its own parser, validator, and documentation from scratch.

Decision Outcome

Chosen option: “Adopt RML as an independent, bidirectional, machine-checkable provenance trace” (Option B), because it is the only option that both expresses the real multiplicity dct:source cannot and is independently, mechanically verifiable — and because a purpose-built W3C-track standard exists for exactly this correspondence problem, so inventing a bespoke format would be pure waste.

RML does not replace dct:source. The two mechanisms answer different questions and are verified independently, by design:

dct:source answers “which single authoritative source defines this term’s meaning” — an editorial/precedence decision that is frequently not the schema at all (89 of 570 dct:source citations across the ontology resolve to an ODR/council decision, not a JSON location).
RML answers “where, structurally, does this term’s data actually live in the PDTF v3 schemas, and how many places” — a positional/navigational question dct:source’s single-valued convention cannot express.

Where both exist for the same term, they are expected to usually agree (verified this session: 68 of 73 directly comparable predicates do) but are not required to — a shared property citing one authoritative dct:source while RML legitimately records several real schema occurrences is correct behaviour, not drift.

Consequences

Good, because it caught real, previously-invisible defects in the existing dct:source discipline: 8 stale-path citations and 16 unresolved citations, none of which the generator’s own emission process had ever verified.
Good, because it can express what dct:source’s single-valued convention structurally cannot — every real occurrence of a shared/collapsed property, not just its one authoritative origin.
Good, because it reuses a purpose-built, W3C-track standard (RML) rather than inventing a bespoke correspondence format.
Bad, because it introduces a second provenance-recording mechanism alongside dct:source, which future contributors must understand are complementary, not redundant, and are not expected to always agree.
Neutral, because the RML mapping’s own coverage of the full schema-generated ontology surface is partial as of this record (roughly a third of resources traced) — closing the remainder is ongoing, separate work, not a precondition of adopting the mechanism itself.

Confirmation

Verified by the RML-provenance validation harness (see the companion ADR for the concrete engineering: engine, checks, and file locations) — three checks: RML-to-ontology term consistency, resource-to-schema-location tracing, and schema-location-to-resource tracing; plus an independent audit of the ontology’s own dct:source citations against the canonical schema dictionary.

Rules

RML mapping content lives under source/03-standards/rml/, alongside the ontology and the schemas it traces (not under tools/) — it is a standards artefact, not a build tool.
The RML mapping is documentation and verification tooling. It MUST NOT be treated as, or repurposed into, an executable ETL pipeline against PDTF transaction instance data as part of this decision; no instance data is required for, or produced by, verifying it.
dct:source and the RML mapping are independently verified and are not required to agree term-for-term. A disagreement is only a defect if the RML-cited path fails to resolve in the canonical schema dictionary at all (a broken trace), not merely because it differs from that term’s single dct:source citation.
Where a schema location is referenced by RML but does not correspond to any minted opda: term, that is a genuine, honestly-reported gap — not silently dropped and not fabricated to close it.

More Information

Depends on ODR-0004 (term-sourcing/dct:source five-tier precedence, which this record extends with independent verification, not replacement).
Depends on ODR-0011 (SKOS concept schemes for enums) — the RML mapping traces enum-value bindings against schemes this record establishes; the concrete RML technique for that binding is an engineering decision recorded in the companion ADR, not here.
Companion engineering record: ADR-0057 (RML mapping implementation — engine, validation harness, file layout).
Related principle: ODR-0026 “model-but-don’t-evaluate” — the same shape of idea applies here: RML traces are documentary/verification content that coexists with dct:source without either evaluating or superseding the other.