Skip to content

Add BSP-Update-2026: CCL D23B→D25A change/BSP/UNTP/discarded analysis

Steve CAPELL requested to merge docs-ccl-bsp-update-2026 into main

UNSCRO: vocabulary, code lists, and documentation site

Builds the UN Supply Chain Reference Ontology (UNSCRO) as a modern linked-data vocabulary forked from UN/CEFACT BSP + UNTP — from an empty scaffold to an MVP-ready vocabulary, a fully curated code-list set, a reproducible build pipeline, and a published documentation site. 67 commits · 303 files · +93.6k/−7.7k.

Methodology & strategy

  • alignment-strategy.md — the fork decision, 9 modelling principles, 6-phase pathway, migration ledger, versioning, repo layout and governance.
  • code-list-strategy.md — governs code values: relevance triage, one namespace, a SKOS TTL profile, hierarchy/collection restructuring, and a defensible change ledger.
  • Coexistence principle (6): UNSCRO keeps its own foundational terms even where schema.org/GS1/QUDT overlap, and reconciles by mapping, never deletion.
  • Structure/semantics decoupling: structural join nodes and code-carrier tuples (Country, Classification, PartyRole…) dissolve to untyped n-ary relations, not classes.

Vocabulary (ontology/)

  • 8 domain modules (core + identity, trade, transport, regulatory, finance, production, conformity) authored in Turtle — 72 classes, 324 properties.
  • Faithful refactor of the source vocabularies: UNTP for Production/Conformity (fidelity check: 0 gaps), BSP-deduped for the rest; schema.org leveraged and mapped in-band.
  • Flat term URIs (vocabulary.uncefact.org/<Term>), domain as metadata (rdfs:isDefinedBy), term lifecycle via unece:termStatus.
  • Grounding test: holding the UNTP/UNVTD schemas frozen, ~100% of UNTP credential terms can re-point their @context at UNSCRO (mappings/).

Code lists (156 pulled → clean, aligned set)

  • Pulled 141 BSP + 15 UNTP lists (13,556 concepts); pre-classified every one in methodology/code-list-ledger.csv (159 rows, keep/park/retire).
  • Profile pass to path URIs + owl:sameAs legacy aliases; merges/collisions resolved; 48 retired lists moved to /retired/ (deprecated, preserved).
  • document-type managed hierarchy (814 codes → family top concepts + skos:broader).
  • unit-of-measure sourced authoritatively from UNECE Rec 20 Rev 17 (1,383 units), enriched via QUDT with machine-readable conversion (multiplier/offset, UCUM code, dimension) + 30 coarse quantity-kind skos:Collections.
  • Imported the UNTP conformity-topics (101) and performance-metrics (79) SKOS taxonomies.
  • Status lifecycles kept URI-stable (MVP decision b — no split); party-role rebuilt as a semantic-token scheme (46 roles + broader + advisory domain collections; compositional roles → onBehalfOf).
  • Bound 30 Table-A property ranges to their schemes; added a validator code-list profile gate.

Repository & build

  • Reorganised ontology/ package-by-domain (vocabulary + code lists + generated docs per domain).
  • Tracked references/ folder makes all code-list builds reproducible from a clone with no network (BSP/UNTP dumps, Rec 20 xlsx, QUDT join, UNTP taxonomies).
  • Validator runs 6 gates (syntax, ref-integrity, file↔domain, term gate, URI uniqueness, code-list profile); fidelity check for UNTP faithfulness; both wired into CI.

Documentation site (GitLab Pages / Nextra)

  • Full page structure: Home, Architecture, Ontology (overview + one page per domain), Normative Mappings, External Vocabularies, Governance.
  • Per-domain pages generated from the vocabulary (class diagram + classes + code-lists table), single-sourced so they never drift.
  • The seven-domain overview diagram is now clickable — every concept box and domain region navigates to its domain page.

Merge request reports