Skip to content

Mappings: add BSP-peer skos:exactMatch back-links; complete UNVTD coverage

Steve CAPELL requested to merge untp-unvtd-mapping into main

Summary

Grounds UNSCRO against the credentials and documents it must serve: completes the UNTP/UNVTD @context re-pointing test to 100% for both, closing every gap with authentic source terms (or clearly-marked proposed additions), and publishes the full provenance trail on the site. 8 commits; graph grows to 89 classes / 744 properties / 101 code lists, validate green throughout.

The grounding test — can the frozen credential/document schemas re-point their @context at UNSCRO?

  • UNTP: 100% re-pointable (5 credential schemas, 0 gaps).
  • UNVTD: 53% → 100% re-pointable (21 trade-document schemas, 0 distinct gaps).

How the gaps were closed (in order, each the authentic BSP/UNTP term)

  • Class back-links — the renamed UNSCRO classes lacked skos:exactMatch to the BSP peer they replace (PartyTradeParty, ConsignmentItemSupplyChainTradeLineItem, …17); adding them is both the Phase-5 mapping and the join key (57% → 79%).
  • Bring-backs — 14 excluded-but-existing BSP properties restored, then 9 more attached to existing classes where their BSP home was a dissolved aggregation node (*MonetarySummation) or a niche/misfiled class (locationName was on a maritime-health class) — reviving those would re-bloat, so attach-to-existing (79% → 86%).
  • TradeDocument reference anchor (principle 9) — one thin document class (documentType + identifier + name + referencedDocument) that the 11 BSP document classes + 4 *ReferencedDocument terms exactMatch to, instead of 17 structural document classes (86% → 93%).
  • Proposed additions — 12 genuinely-new terms (roles, locations, temperatures, bookingReference, dangerousGoodsClassCode + a new UN-hazard-class SKOS list, …), each marked dcterms:provenance "Proposed UNSCRO addition" (no dcterms:source) to distinguish them from governance-approved BSP/UNTP terms (93% → 100%).
  • Context-corrections — the generic-typeCode and mis-pointed cases re-point to existing specific terms via a UNVTD_OVERRIDE map in the generator; hsCode recorded as external reuse (HS/WCO — parked to-do).

Provenance & manifests

  • Every kept term carries dcterms:source (BSP/UNTP origin) + skos:exactMatch (peer mapping) in-band; proposed additions carry dcterms:provenance instead — a clean, queryable governance distinction.
  • UNSCRO-migration-ledger.csv regenerated (2,043 rows — one per source term) and code-list-ledger.csv reconciled; both stay current via their reconciler scripts and are gate-enforced.

Site — auditable trail published

  • Mappings page gains a "How UNSCRO was built — an auditable trail" section linking the methodology docs, the CSV manifests, and the UNTP/UNVTD coverage + per-schema mappings (repo-blob links, matching the code-list pattern).
  • Ontology overview: each domain sub-heading now links to its domain page.

Verification

  • validate-vocab.py passes all 7 gates (incl. code-list ledger-drift).
  • npm run build exports the static site cleanly.

Follow-ups (parked)

  • HS commodity code list — external (WCO); local SKOS copy if not published as linked data (big job).
  • Governance ratification of the 12 proposed additions.
  • Optional: bundle methodology/ + mappings/ into the static export if a self-contained (repo-independent) audit trail is wanted.

Merge request reports

Loading