Skip to content

Flesh out documentation and enrich models from BSP source.

Steve CAPELL requested to merge site-content into main

Summary

Rebuilds the documentation site's content and runs a full completeness pass over the UNSCRO ontology — closing the aggressive-cut gaps left by the initial BSP triage, wiring code lists to properties, and improving the generated domain diagrams. 26 commits; graph grows to 89 classes / 707 properties / 100 code lists, all gated by validate-vocab.

Site & documentation

  • External Vocabularies page is now generated from a machine-readable register (methodology/vocabulary-register.json + JSON schema), grouped by relation, with a build-time schema check; register + schema published as resolvable artifacts.
  • Architecture / Governance / Home pages reworked: Semantic-Web foundation, one-source-many-formats, well-governed-vocabulary criteria, clickable domain-only home map, menu reordering.

Repository structure

  • Renamed for clarity: vocabulary/ → diagrams/ (it holds diagrams + narrative, not the vocabulary); methodology/references/ → methodology/source-analysis/; root download tooling → scripts/acquire/.
  • README rewritten (authored vs generated split; corrected site/; documented out//dist//public/ and the two deployments).

Ontology — code-list & property completeness

  • Inventoried the 87 orphaned code lists; wired kept-but-string properties to their scheme; re-added dropped BSP properties across three rounds; retired 13 genuinely-empty / out-of-scope schemes to retired/.
  • Reframed the BSP drop policy to default-keep for cheap terms, default-drop-pending-review for class-coupled terms (recorded in alignment-strategy §6); restored ~130 review-bucket properties and added 17 new classes (DangerousGoods, TradePrice, Service, PaymentMeans, ProductBatch, …).
  • Per-property assessment of 18 previously under-assessed classes (+224 properties), each with a <class>-property-triage.csv verdict record; collapsed overloaded variant families to one-relationship-plus-type-code where a code list already served; simplified 15 redundant/overloaded property names (provenance kept in-band via dcterms:source).

Diagrams

  • Per-domain layout direction, then a full restructure: a relationship-only overview map plus per-big-class zoom diagrams, with full property detail in text tables — replacing the unreadable attribute-crammed diagrams; auto-balance flips layout for any diagram that renders as a thin strip.

Governance & manifests

  • New CI gate: code-list ledger drift (a bound scheme must be recorded as bound) — caught and reconciled ~30 drifts during this work.
  • Added scripts/build-migration-ledger.py to reconcile the §6 migration ledger from the graph + drops lists (re-runnable); regenerated to complete per-term coverage (140 → 2,023 rows, 0 curated rows lost).

Verification

  • validate-vocab.py passes all 7 gates; npm run build and build-vocab-site.py both export cleanly.

Merge request reports