Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
fix(case-studies): purge em dashes from case study docs, repair modip build artifact links
FABIOTESS0bbec657857a
diff --git a/case-studies/blast-furnace-ironmaking/README.md b/case-studies/blast-furnace-ironmaking/README.mdindex f843aedc..8bb1be5a 100644--- a/case-studies/blast-furnace-ironmaking/README.md+++ b/case-studies/blast-furnace-ironmaking/README.md@@ -1,4 +1,4 @@-# Case study: blast-furnace fault diagnosis — Open Ontologies vs Huang et al. 2024+# Case study: blast-furnace fault diagnosis, Open Ontologies vs Huang et al. 2024**Paper:** Huang, Yang, Zhang, Lou, Kong & Zhou. *Ontology guided multi-level knowledge graph construction and its applications in blast furnace ironmaking process.* Advanced Engineering Informatics 62 (2024), [DOI 10.1016/j.aei.2024.102927](https://doi.org/10.1016/j.aei.2024.102927). Authors: Zhejiang University (Chunjie Yang's process-control group).@@ -10,7 +10,7 @@1. **Multi-level ontology** for the blast furnace: physical structure (zones, sensors, tuyeres), operational states (fault classes), criticality.2. **KG construction** by tying real sensor streams + maintenance logs to the ontology.-3. **Embedding + ML classifier** (the specific ML choice isn't load-bearing — KG features feeding a tree-ensemble-style discriminative model).+3. **Embedding + ML classifier** (the specific ML choice isn't load-bearing: KG features feeding a tree-ensemble-style discriminative model).4. **Output:** discrete fault label per time-window. Accuracy 92.76%; diagnosis 58.44% faster than baseline.The whole pipeline is engineered toward one task: turn sensor readings into a fault label as fast and accurately as possible. State-changing reactive actions (slow down the blast, schedule a tap, swap a tuyere) are operator decisions downstream of the label.@@ -19,12 +19,12 @@ The whole pipeline is engineered toward one task: turn sensor readings into a faThree files in this directory plus a runnable script:-- [`blast-furnace-ontology.ttl`](blast-furnace-ontology.ttl) — the TBox, structurally identical to the paper's multi-level model (4 zones, 5 fault classes, criticality levels).-- [`sensor-snapshots.ttl`](sensor-snapshots.ttl) — 8 time-window snapshots (6 labelled, 2 unlabelled test).-- [`safety-invariants.ttl`](safety-invariants.ttl) — 4 SHACL constraints (descent-rate required, hearth temp floor 1300°C, stack pressure ceiling 320 kPa, tuyere lifetime 30000 h).-- [`run-demo.sh`](run-demo.sh) — load → query (5 SPARQL classifier rules) → reason → SHACL → print report.+- [`blast-furnace-ontology.ttl`](blast-furnace-ontology.ttl): the TBox, structurally identical to the paper's multi-level model (4 zones, 5 fault classes, criticality levels).+- [`sensor-snapshots.ttl`](sensor-snapshots.ttl): 8 time-window snapshots (6 labelled, 2 unlabelled test).+- [`safety-invariants.ttl`](safety-invariants.ttl): 4 SHACL constraints (descent-rate required, hearth temp floor 1300°C, stack pressure ceiling 320 kPa, tuyere lifetime 30000 h).+- [`run-demo.sh`](run-demo.sh): load → query (5 SPARQL classifier rules) → reason → SHACL → print report.-Classification is **declarative**, not learned: each fault class is a SPARQL pattern. No training data needed beyond the rules. No model retraining when a new fault class appears — add a SPARQL rule.+Classification is **declarative**, not learned: each fault class is a SPARQL pattern. No training data needed beyond the rules. No model retraining when a new fault class appears: add a SPARQL rule.## Empirical run on the synthetic 8-snapshot suite@@ -58,7 +58,7 @@ The SHACL safety check additionally caught a **data-model bug we didn't author i}```-That kind of finding is what SHACL invariants are for — independent verification of data shape against the ontology's domain/range declarations.+That kind of finding is what SHACL invariants are for: independent verification of data shape against the ontology's domain/range declarations.## What this comparison actually shows@@ -82,18 +82,18 @@ That kind of finding is what SHACL invariants are for — independent verificati3. **Probabilistic confidence per prediction.** ML returns a posterior; OO's rule either fires or doesn't. Operators downstream may want the probability.-4. **Threshold robustness.** The thresholds in `fault-rules.sparql` (700 mm/h, 1400°C, 0.75 CO ratio, 25000 h) are hand-set against the synthetic data. Real-furnace deployment requires per-site calibration — a real cost OO doesn't avoid.+4. **Threshold robustness.** The thresholds in `fault-rules.sparql` (700 mm/h, 1400°C, 0.75 CO ratio, 25000 h) are hand-set against the synthetic data. Real-furnace deployment requires per-site calibration, a real cost OO doesn't avoid.5. **The whole demonstrated benchmark.** Their evaluation says "we tested this on a real plant." Ours says "we tested this on 8 snapshots we wrote." The honest answer is: the paper is real engineering with measured performance; this case study is a methodological argument.-## Bridge attempt — what changes if Huang et al. add OO's strengths?+## Bridge attempt: what changes if Huang et al. add OO's strengths?| OO advantage | What they would add | Cost to their stack ||---|---|---|| SPARQL rules for auditable classification | Layer a rule-based explainer over their ML output | 2-3 weeks; doesn't remove the ML retraining cost || SHACL safety invariants | Add a SHACL validator before the ML classifier fires | ~1 week; high payoff |-| CIVeX-certified reactive actions | Wrap operator actions in a verifier | 2-4 weeks; requires authoring action schemas — they'd need an equivalent of our Dynamics layer |-| New-fault-type-as-SPARQL-rule | Drop ML retraining for some fault classes | Strategic — they probably resist because it undercuts their main contribution |+| CIVeX-certified reactive actions | Wrap operator actions in a verifier | 2-4 weeks; requires authoring action schemas; they'd need an equivalent of our Dynamics layer |+| New-fault-type-as-SPARQL-rule | Drop ML retraining for some fault classes | Strategic; they probably resist because it undercuts their main contribution |### Where OO does not catch up after their bridge attempt@@ -101,18 +101,18 @@ OO does not get a real-dataset benchmark from a bridge attempt by Huang's team.## Honest recommendation if a real Korean / Chinese steel-plant pilot were on the table-1. **Use OO's SHACL invariants from day one** — independent of any ML stack. Safety bounds are easy wins.-2. **Author the fault taxonomy as SPARQL rules in parallel with an ML classifier** — keep both, route the operator UI through whichever has higher confidence per case.-3. **Gate every reactive operator action through `onto_certify_action`** — the audit trail alone justifies the architecture.+1. **Use OO's SHACL invariants from day one**; they are independent of any ML stack. Safety bounds are easy wins.+2. **Author the fault taxonomy as SPARQL rules in parallel with an ML classifier**: keep both, route the operator UI through whichever has higher confidence per case.+3. **Gate every reactive operator action through `onto_certify_action`**: the audit trail alone justifies the architecture.4. **Don't claim to beat 92.76%** unless and until a plant trial says so.That's the honest position. The architectural argument is real; the empirical comparison is not yet.## Sources-- Huang et al. 2024 — [DOI 10.1016/j.aei.2024.102927](https://doi.org/10.1016/j.aei.2024.102927)-- Open Ontologies CIVeX certification — [arXiv 2605.09168](https://arxiv.org/abs/2605.09168)-- Open Ontologies CIVeX module — [`src/civex.rs`](../../src/civex.rs)-- Open Ontologies BC+ Dynamics — [`src/dynamics.rs`](../../src/dynamics.rs), [`src/dynamics_bcplus.rs`](../../src/dynamics_bcplus.rs)-- FLORA fuzzy alignment (ISWC 2025 Best Paper) — [`src/align_fuzzy.rs`](../../src/align_fuzzy.rs)-- SHACL co-evolution (K-CAP 2025) — [`src/coevolve.rs`](../../src/coevolve.rs)+- Huang et al. 2024: [DOI 10.1016/j.aei.2024.102927](https://doi.org/10.1016/j.aei.2024.102927)+- Open Ontologies CIVeX certification: [arXiv 2605.09168](https://arxiv.org/abs/2605.09168)+- Open Ontologies CIVeX module: [`src/civex.rs`](../../src/civex.rs)+- Open Ontologies BC+ Dynamics: [`src/dynamics.rs`](../../src/dynamics.rs), [`src/dynamics_bcplus.rs`](../../src/dynamics_bcplus.rs)+- FLORA fuzzy alignment (ISWC 2025 Best Paper): [`src/align_fuzzy.rs`](../../src/align_fuzzy.rs)+- SHACL co-evolution (K-CAP 2025): [`src/coevolve.rs`](../../src/coevolve.rs)diff --git a/case-studies/heritage-aerial/CHANGELOG.md b/case-studies/heritage-aerial/CHANGELOG.mdindex ee546ad1..b03452c9 100644--- a/case-studies/heritage-aerial/CHANGELOG.md+++ b/case-studies/heritage-aerial/CHANGELOG.md@@ -4,14 +4,14 @@ All notable changes to NAPH are documented here. The format follows [Keep a Chan## [Unreleased]-## [1.0.0] — 2026-04-30+## [1.0.0] - 2026-04-30Initial v1.0 release of the NAPH standard for aerial photography heritage.### Added-- NAPH ontology (`ontology/naph-core.ttl`) — 30 classes, 29 properties, 198 triples-- SHACL shapes (`ontology/naph-shapes.ttl`) — tiered Baseline / Enhanced / Aspirational + DigitalSurrogate + Place + RightsStatement+- NAPH ontology (`ontology/naph-core.ttl`): 30 classes, 29 properties, 198 triples+- SHACL shapes (`ontology/naph-shapes.ttl`): tiered Baseline / Enhanced / Aspirational + DigitalSurrogate + Place + RightsStatement- 10-record sample dataset modelled on NCAP collection structure- 6 module specifications (A: Capture, B: Metadata, C: Rights, D: Packaging, E: Paradata, F: QA)- Aerial Photography Profile (the single normative profile in v1.0)diff --git a/case-studies/heritage-aerial/CONTRIBUTING.md b/case-studies/heritage-aerial/CONTRIBUTING.mdindex 09a374b9..04b22f17 100644--- a/case-studies/heritage-aerial/CONTRIBUTING.md+++ b/case-studies/heritage-aerial/CONTRIBUTING.md@@ -59,7 +59,7 @@ NAPH should align cleanly with adjacent standards. We'd value contributions of:## Style notes- TTL files use 4-space indentation, one statement per logical group, comments explain non-obvious modelling choices-- Markdown follows the existing case-study tone — direct, evidence-led, no marketing fluff+- Markdown follows the existing case-study tone: direct, evidence-led, no marketing fluff- Python scripts are self-contained, type-hinted where it adds clarity, no external dependencies beyond the standard library## Questionsdiff --git a/case-studies/heritage-aerial/README.md b/case-studies/heritage-aerial/README.mdindex be1f3aac..3b89a041 100644--- a/case-studies/heritage-aerial/README.md+++ b/case-studies/heritage-aerial/README.md@@ -1,6 +1,6 @@-# NAPH — Computation-Ready Digitisation Standard for Aerial Photography Heritage+# NAPH: Computation-Ready Digitisation Standard for Aerial Photography Heritage-A focused, vertical, openly-licensed digitisation standard for **aerial photography heritage collections**. Provides ontology, validation shapes, transformation pipeline, IIIF bridge, governance model, and full deliverables — the complete A-to-Z system designed for institutions like NCAP, IWM, NARA-partnered archives, and equivalent national aerial photography holdings worldwide.+A focused, vertical, openly-licensed digitisation standard for **aerial photography heritage collections**. Provides ontology, validation shapes, transformation pipeline, IIIF bridge, governance model, and full deliverables: the complete A-to-Z system designed for institutions like NCAP, IWM, NARA-partnered archives, and equivalent national aerial photography holdings worldwide.Aligned with the goals of the **Towards a National Collection** programme (AHRC / UKRI) and the **N-RICH Prototype**. See [CHANGELOG](CHANGELOG.md).@@ -9,11 +9,11 @@ Aligned with the goals of the **Towards a National Collection** programme (AHRC> This case study no longer runs on synthetic records alone. It ingests a live,> reproducible sample of **292 real frames** harvested from NCAP's public> [Air Photo Finder API](https://airphotofinder.ncap.org/), reprojected from-> EPSG:3857 to WGS84 and auto-lifted to the NAPH Baseline tier — **0 SHACL+> EPSG:3857 to WGS84 and auto-lifted to the NAPH Baseline tier with **0 SHACL> violations**. Testing the standard against real holdings found (and fixed) a> real defect in the standard's own date-precision shape.>-> - **What the live API actually exposes:** [`docs/empirical-api-findings.md`](docs/empirical-api-findings.md) — 100% of records already carry a machine-readable footprint and an ISO-8601 date. NCAP is closer to Baseline than the browser suggests.+> - **What the live API actually exposes:** [`docs/empirical-api-findings.md`](docs/empirical-api-findings.md): 100% of records already carry a machine-readable footprint and an ISO-8601 date. NCAP is closer to Baseline than the browser suggests.> - **Harvester:** [`pipeline/scrapers/ncap_airphotofinder.py`](pipeline/scrapers/ncap_airphotofinder.py) (respectful, rate-limited, metadata only)> - **Real data:** [`data/real-ncap-sample.ttl`](data/real-ncap-sample.ttl) · **Live map:** [`demo/real.html`](demo/real.html) · **STAC + GeoJSON exports:** [`reports/`](reports/)@@ -23,7 +23,7 @@ Aligned with the goals of the **Towards a National Collection** programme (AHRC> around one archive, it was run against a second national collection: Canada's> **National Air Photo Library** (NAPL, Natural Resources Canada), via the open> **Government of Canada CKAN API** (no authentication). **40 dated orthophoto-> mosaics across 8 regions (1932–2004)** lifted to NAPH Baseline — **0 SHACL+> mosaics across 8 regions (1932–2004)** lifted to NAPH Baseline with **0 SHACL> violations**. The ontology, shapes and crosswalk were unchanged; only the> harvester adapter differs.>@@ -31,27 +31,27 @@ Aligned with the goals of the **Towards a National Collection** programme (AHRC> footprints but **0%** machine-readable rights, while NAPL (Canada) ships> **100%** machine-readable rights (Open Government Licence) and native-WGS84> footprints but at collection (mosaic) granularity. The two archives are missing-> opposite things — which is exactly what a shared Baseline test is for.+> opposite things, which is exactly what a shared Baseline test is for.>> - **Findings + cross-national table:** [`docs/canada-napl-findings.md`](docs/canada-napl-findings.md)> - **Harvester:** [`pipeline/scrapers/napl_opencanada.py`](pipeline/scrapers/napl_opencanada.py) (open CKAN API, metadata only, no auth)> - **Real data:** [`data/real-napl-sample.ttl`](data/real-napl-sample.ttl) · **GeoJSON:** [`reports/real-napl-footprints.geojson`](reports/real-napl-footprints.geojson)-> **And backed by real US data (WHAIFinder) — without the token-gated API**+> **And backed by real US data (WHAIFinder), without the token-gated API**>> The obvious US target, USGS EROS, has a token-gated M2M API. Rather than gate the> demo behind credentials, the third national collection uses an **openly queryable**> holding: the **Wisconsin Historic Aerial Imagery Finder** (~201k frame-level> records, largely public-domain USDA survey photography), via its public **ArcGIS-> FeatureServer** (no auth). **225 real frames (1937–1967)** lifted to NAPH Baseline —+> FeatureServer** (no auth). **225 real frames (1937–1967)** lifted to NAPH Baseline with> **0 SHACL violations**.>-> The US index publishes a **point centerpoint**, not a polygon — so the Baseline+> The US index publishes a **point centerpoint**, not a polygon, so the Baseline> footprint is a **closed-form reconstruction** from centerpoint + map scale (standard> 9×9-inch frame). That gives the full three-country result: each archive was missing> a *different* Baseline piece (rights in the UK, frame granularity in Canada, footprint-> geometry in the US) and each was closed by a *different* single transform — reproject,-> publish-as-is, reconstruct — with the ontology, shapes and crosswalk **unchanged**.+> geometry in the US) and each was closed by a *different* single transform (reproject,+> publish-as-is, reconstruct) with the ontology, shapes and crosswalk **unchanged**.>> - **Findings + three-country table:** [`docs/usa-whaifinder-findings.md`](docs/usa-whaifinder-findings.md)> - **Harvester:** [`pipeline/scrapers/whaifinder_arcgis.py`](pipeline/scrapers/whaifinder_arcgis.py) (open ArcGIS REST, no auth)@@ -60,15 +60,15 @@ Aligned with the goals of the **Towards a National Collection** programme (AHRC## Why narrow-Generic GLAM-wide digitisation standards exist. Aerial photography heritage has distinctive characteristics — stereo pairs, ground sample distance, declassification provenance, sortie metadata — that benefit from a focused, deep treatment rather than a generic framework. NAPH is deliberately one vertical, done well. See [ADR-0001](deliverables/06-knowledge-transfer/architecture-decision-records/0001-narrow-vertical.md).+Generic GLAM-wide digitisation standards exist. Aerial photography heritage has distinctive characteristics (stereo pairs, ground sample distance, declassification provenance, sortie metadata) that benefit from a focused, deep treatment rather than a generic framework. NAPH is deliberately one vertical, done well. See [ADR-0001](deliverables/06-knowledge-transfer/architecture-decision-records/0001-narrow-vertical.md).## Why this exists-The aerial photography heritage sector — NCAP, IWM, NARA, RAF Museum, RCAHMS, equivalent national institutions — holds collectively ~50 million records that are **digitised but not computable**. They sit on the web for human browsing but cannot be queried, aggregated, or analysed at scale by modern research tools.+The aerial photography heritage sector (NCAP, IWM, NARA, RAF Museum, RCAHMS, equivalent national institutions) holds collectively ~50 million records that are **digitised but not computable**. They sit on the web for human browsing but cannot be queried, aggregated, or analysed at scale by modern research tools.-NAPH is a focused vertical standard that closes that gap for aerial photography specifically, rather than chasing a generic GLAM-wide framework that has to compromise on every domain. Aerial photography has rich spatial, temporal, and event-linked context that becomes far more powerful when modelled as linked data — and that depth deserves a dedicated treatment.+NAPH is a focused vertical standard that closes that gap for aerial photography specifically, rather than chasing a generic GLAM-wide framework that has to compromise on every domain. Aerial photography has rich spatial, temporal, and event-linked context that becomes far more powerful when modelled as linked data, and that depth deserves a dedicated treatment.-This case study shows what a **3-tier digitisation standard** looks like when applied to a real-shaped heritage dataset — and what the gap is between current archive-cataloguing practice (ISAD-G, free-text fields, image-on-the-web) and computation-readiness.+This case study shows what a **3-tier digitisation standard** looks like when applied to a real-shaped heritage dataset, and what the gap is between current archive-cataloguing practice (ISAD-G, free-text fields, image-on-the-web) and computation-readiness.## The three tiers@@ -78,7 +78,7 @@ This case study shows what a **3-tier digitisation standard** looks like when ap| **Enhanced** | Supports research workflows | Baseline + digitisation provenance (date, resolution, format, operator), capture context (altitude, camera, squadron, aircraft), full provenance chain, multiple surrogate formats || **Aspirational** | Supports semantic discovery | Enhanced + subject classification, place authority links (GeoNames / Wikidata), cross-collection linked records, event linkage |-Each tier is **incrementally adoptable** — a collection at Baseline does not need to rebuild to reach Enhanced.+Each tier is **incrementally adoptable**: a collection at Baseline does not need to rebuild to reach Enhanced.## The full deliverable set@@ -86,11 +86,11 @@ The [`deliverables/`](deliverables/) directory contains the complete A-to-Z syst| Output | Location ||---|---|-| **1. Standard v1.0** — formal specification | [`deliverables/01-standard/NAPH-STANDARD.md`](deliverables/01-standard/NAPH-STANDARD.md) |+| **1. Standard v1.0**: formal specification | [`deliverables/01-standard/NAPH-STANDARD.md`](deliverables/01-standard/NAPH-STANDARD.md) || 6 module specifications (A: Capture, B: Metadata, C: Rights, D: Packaging, E: Paradata, F: QA) | [`deliverables/01-standard/modules/`](deliverables/01-standard/modules/) || Aerial Photography Profile (the single normative profile in v1.0) | [`deliverables/01-standard/profiles/aerial-photography.md`](deliverables/01-standard/profiles/aerial-photography.md) || 5 sub-profiles (reconnaissance, satellite, UAV, photogrammetric, aerial archaeology) | [`deliverables/01-standard/profiles/aerial-subprofiles/`](deliverables/01-standard/profiles/aerial-subprofiles/) |-| **2. Testing evidence** — partner clinic playbook | [`deliverables/05-governance/partner-clinic-playbook.md`](deliverables/05-governance/partner-clinic-playbook.md) |+| **2. Testing evidence**: partner clinic playbook | [`deliverables/05-governance/partner-clinic-playbook.md`](deliverables/05-governance/partner-clinic-playbook.md) || **3. Cost / capacity / skills analysis** | [`deliverables/03-cost-capacity-skills/`](deliverables/03-cost-capacity-skills/) || Investment case + skills map | [`investment-case.md`](deliverables/03-cost-capacity-skills/investment-case.md), [`skills-map.md`](deliverables/03-cost-capacity-skills/skills-map.md) || **4. Adoption guidance** | [`deliverables/04-adoption-guidance/`](deliverables/04-adoption-guidance/) |@@ -123,14 +123,14 @@ case-studies/heritage-aerial/├── LICENSE (CC BY 4.0 + CC0 + MIT)├── CONTRIBUTING.md├── ontology/-│ ├── naph-core.ttl (the ontology — 30 classes, 29 properties)-│ └── naph-shapes.ttl (SHACL shapes — tiered + DigitalSurrogate + Place)+│ ├── naph-core.ttl (the ontology: 30 classes, 29 properties)+│ └── naph-shapes.ttl (SHACL shapes: tiered + DigitalSurrogate + Place)├── data/│ └── sample-photographs.ttl (10 illustrative records across all 3 tiers)├── pipeline/│ ├── legacy-ncap-style.csv (current-state metadata: messy dates, free-text rights)│ ├── ingest.py (CSV → NAPH TTL transformation pipeline)-│ ├── generated-from-csv.ttl (output of ingest.py — all records lifted to Baseline)+│ ├── generated-from-csv.ttl (output of ingest.py: all records lifted to Baseline)│ ├── self-assessment.py (self-service compliance check CLI)│ ├── generate-report.py (runs full validation + emits HTML report)│ ├── iiif-bridge.py (NAPH → IIIF Presentation 3.0 manifest generator)@@ -164,7 +164,7 @@ python3 -m http.server 8765# http://localhost:8765/demo/index.html```-The demo loads the IIIF collection manifest and renders the 10 records on an interactive map — tier-coloured markers, WGS84 footprint polygons, click-through metadata panel. The user-facing artefact that makes the standard concrete.+The demo loads the IIIF collection manifest and renders the 10 records on an interactive map: tier-coloured markers, WGS84 footprint polygons, click-through metadata panel. The user-facing artefact that makes the standard concrete.## The sample dataset@@ -183,17 +183,17 @@ Ten illustrative photograph records distributed across the three tiers:| 9 | Aspirational | RAF/541/EDI | Edinburgh Castle | 1946-08-04 || 10 | Aspirational | USAAF/3PRS/HIR | Hiroshima post-detonation | 1945-08-11 |-**Note on the dataset:** these records are *modeled on the structure* of NCAP holdings — they use plausible sortie identifier formats, real squadron/aircraft pairings, real geographic coordinates, and rights statements aligned with rightsstatements.org. They are illustrative of what NCAP records *could look like* under the proposed standard, not assertions that these specific frames exist in the NCAP catalogue with these exact identifiers.+**Note on the dataset:** these records are *modeled on the structure* of NCAP holdings: they use plausible sortie identifier formats, real squadron/aircraft pairings, real geographic coordinates, and rights statements aligned with rightsstatements.org. They are illustrative of what NCAP records *could look like* under the proposed standard, not assertions that these specific frames exist in the NCAP catalogue with these exact identifiers.## What this demonstrates-**1. The cost of going from Baseline to Enhanced is small.** Most of the data already exists in NCAP — sortie metadata, squadron, aircraft, capture conditions are routinely recorded. The gap is structuring it (ISO dates, machine-readable fields, explicit provenance chains) rather than acquiring new information.+**1. The cost of going from Baseline to Enhanced is small.** Most of the data already exists in NCAP: sortie metadata, squadron, aircraft, capture conditions are routinely recorded. The gap is structuring it (ISO dates, machine-readable fields, explicit provenance chains) rather than acquiring new information.-**2. The cost of going from Enhanced to Aspirational is significant — but partly automatable.** Subject classification, place authority linking, cross-collection record matching can be partially performed by vision-language models and entity-linking tools. The standard should specify *outcome requirements* (what needs to be linked, to which authorities) rather than prescribing manual workflows.+**2. The cost of going from Enhanced to Aspirational is significant, but partly automatable.** Subject classification, place authority linking, cross-collection record matching can be partially performed by vision-language models and entity-linking tools. The standard should specify *outcome requirements* (what needs to be linked, to which authorities) rather than prescribing manual workflows.**3. The same standard works across collection sub-types.** RAF reconnaissance, US-transferred imagery, post-war urban surveys, and overseas surveys all model cleanly into the same ontology. The differences are in which optional fields apply, not in the core structure.-**4. Computation-ready is achievable with no new research.** The ontology is built from existing standards (PROV-O, GeoSPARQL, SKOS, Dublin Core, DCAT, FOAF) — synthesis, not invention.+**4. Computation-ready is achievable with no new research.** The ontology is built from existing standards (PROV-O, GeoSPARQL, SKOS, Dublin Core, DCAT, FOAF): synthesis, not invention.## How to use it@@ -276,7 +276,7 @@ The pipeline performs the exact transformations the standard requires:| Unit conversion | `30000` (feet) | `9144.0` (metres) || Identifier minting | `RAF/106G/UK/1655` + frame `4023` | `https://w3id.org/naph/photo/RAF-106G-UK-1655-4023` |-This is what an institution actually pays for when adopting the standard — and `ingest.py` is 200 lines.+This is what an institution actually pays for when adopting the standard, and `ingest.py` is 200 lines.## Generating validation reports@@ -284,7 +284,7 @@ This is what an institution actually pays for when adopting the standard — andpython3 pipeline/generate-report.py > reports/validation-report.html```-Runs the full validation suite (load → SHACL → all competency queries) and emits a styled HTML report with live results. Designed as the artefact institutions publish alongside their data to demonstrate compliance — the dashboard view of NAPH adoption.+Runs the full validation suite (load → SHACL → all competency queries) and emits a styled HTML report with live results. Designed as the artefact institutions publish alongside their data to demonstrate compliance: the dashboard view of NAPH adoption.## IIIF interoperability@@ -302,19 +302,19 @@ This is interoperability without lock-in: institutions adopt NAPH and gain the I## Roadmap-This is **v0.3** — working ontology, validated SHACL shapes, end-to-end ingest pipeline, IIIF bridge, validation reports, **and a live real-data harvest** from the NCAP Air Photo Finder API.+This is **v0.3**: working ontology, validated SHACL shapes, end-to-end ingest pipeline, IIIF bridge, validation reports, **and a live real-data harvest** from the NCAP Air Photo Finder API.-- [x] **v0.3** — real Air Photo Finder data (292 frames, live API, reprojected + validated); date-precision shape fix; STAC + GeoJSON exports; RiC-O × STAC crosswalk-- [ ] **v0.4** — automated subject classification pipeline (vision-language models, drafts requiring human validation)-- [ ] **v0.5** — full case study writeup with cost/effort breakdown per tier and partner adoption playbook+- [x] **v0.3**: real Air Photo Finder data (292 frames, live API, reprojected + validated); date-precision shape fix; STAC + GeoJSON exports; RiC-O × STAC crosswalk+- [ ] **v0.4**: automated subject classification pipeline (vision-language models, drafts requiring human validation)+- [ ] **v0.5**: full case study writeup with cost/effort breakdown per tier and partner adoption playbook## Why publish this as open sourceThis case study is published openly because:-- **Heritage collections need this work** — the problem is real and the gap is sector-wide.+- **Heritage collections need this work**: the problem is real and the gap is sector-wide.- **Standards adopt faster when they have working reference implementations alongside specification documents.**-- **Open Ontologies is a general-purpose tool** — heritage / GLAM is one application domain among many, and a real-world case study makes the tool more useful to other domains too.+- **Open Ontologies is a general-purpose tool**: heritage / GLAM is one application domain among many, and a real-world case study makes the tool more useful to other domains too.## Licencediff --git a/case-studies/investment-fund-ontology/README.md b/case-studies/investment-fund-ontology/README.mdindex 1f69c3d2..313bde1c 100644--- a/case-studies/investment-fund-ontology/README.md+++ b/case-studies/investment-fund-ontology/README.md@@ -2,7 +2,7 @@**Ontology under test:** the [Investment Fund Ontology (IFO)](https://github.com/fabio-rovai/investment-fund-ontology), an open OWL 2 ontology + SKOS identifier-scheme registry + SHACL governance layer for registered investment fund data, built against the full public US fund universe: 1,292,541 triples joined from the SEC series/class register, four quarters of Form N-CEN, and GLEIF's 9.1M-pair ISIN-LEI mapping. The five Turtle files here are vendored from IFO at v0.2.0 (same author, MIT/CC BY 4.0).-**The question this case study answers:** IFO ships its layer-3 business rules as standard SHACL-SPARQL (`ifo-rules.ttl`) "for platforms that execute them natively", but its own reference pipeline does not execute them as SPARQL — it re-implements each rule set-based in Python, because rdflib could not be trusted to run them at 1.3M triples. Is that workaround actually necessary, or just an artifact of the store used? Can the rules run *as written* on Open Ontologies' Oxigraph-backed engine?+**The question this case study answers:** IFO ships its layer-3 business rules as standard SHACL-SPARQL (`ifo-rules.ttl`) "for platforms that execute them natively", but its own reference pipeline does not execute them as SPARQL: it re-implements each rule set-based in Python, because rdflib could not be trusted to run them at 1.3M triples. Is that workaround actually necessary, or just an artifact of the store used? Can the rules run *as written* on Open Ontologies' Oxigraph-backed engine?**Answer: the workaround is rdflib-specific.** The plain SPARQL inside the rules' `sh:select` bodies runs unmodified on this repo's engine, at full graph scale, in single-digit seconds, and reproduces the IFO reference pipeline's published counts exactly.@@ -13,15 +13,15 @@ Full 1,292,541-triple `fund_graph.ttl` (IFO build of 14 Aug 2026), Apple silicon| Step | rdflib 7.6.0 | Open Ontologies ||---|---|---|| Load 1.29M triples | 18.0s | 1.8s |-| R1 — ETF share class with no listing (`FILTER NOT EXISTS` anti-join) | 0.1s — 73 findings | 73 findings |-| R2 — conflicting LEI values on one fund (multi-way self-join) | **timeout, >300s** | 0 conflicts |-| R3 — fund reports its registrant's LEI (5-pattern join) | **timeout, >300s** | 214 funds |-| R5 — observed classes exceed N-CEN reported count (nested aggregate) | 0.8s — 2,148 funds | 2,148 funds |+| R1: ETF share class with no listing (`FILTER NOT EXISTS` anti-join) | 0.1s, 73 findings | 73 findings |+| R2: conflicting LEI values on one fund (multi-way self-join) | **timeout, >300s** | 0 conflicts |+| R3: fund reports its registrant's LEI (5-pattern join) | **timeout, >300s** | 214 funds |+| R5: observed classes exceed N-CEN reported count (nested aggregate) | 0.8s, 2,148 funds | 2,148 funds || **Load + all four rules, one process** | **>10 minutes, 2 of 4 rules never complete** | **2.1s** |Two things worth being precise about, because the obvious summary ("rdflib can't do anti-joins at scale") is wrong:-1. **rdflib's failure mode is the multi-way self-join, not the anti-join.** R1's `NOT EXISTS` and R5's nested `GROUP BY` both run fine in rdflib (0.1s, 0.8s). What it cannot finish is R2 and R3 — the rules that join `ifo:identifiedBy` against itself across typed identifier nodes. Those are exactly the cross-source reconciliation rules that motivate IFO's reified-identifier design, so "run the reconciliation rules" is the one thing the reference store cannot do declaratively.+1. **rdflib's failure mode is the multi-way self-join, not the anti-join.** R1's `NOT EXISTS` and R5's nested `GROUP BY` both run fine in rdflib (0.1s, 0.8s). What it cannot finish is R2 and R3, the rules that join `ifo:identifiedBy` against itself across typed identifier nodes. Those are exactly the cross-source reconciliation rules that motivate IFO's reified-identifier design, so "run the reconciliation rules" is the one thing the reference store cannot do declaratively.2. **The counts are the verification, not just the speed.** All four counts match the numbers IFO's set-based Python pipeline published in its governance report (73 / 0 / 214 / 2,148) on the same build of the graph. Same constraints, two independent executors, identical results. (One wording nit surfaced by the replication: IFO's R1 "73" is 73 fund-class findings across **71** distinct funds.) These figures are pinned to the 14 Aug 2026 build; IFO fetches two of its three sources as "latest", so a rebuilt graph will produce different totals.## What the demo runs@@ -30,14 +30,14 @@ Two things worth being precise about, because the obvious summary ("rdflib can't./run-demo.sh```-**Part 1 — self-contained** (vendored files only, no data download): loads `ifo-core.ttl` + `identifier-schemes.ttl` + the 1,883-triple Vanguard example subgraph, then+**Part 1, self-contained** (vendored files only, no data download): loads `ifo-core.ttl` + `identifier-schemes.ttl` + the 1,883-triple Vanguard example subgraph, then-- queries the SKOS registry for identifier schemes grouped by declared scope (entity- / issue- / venue-scoped) — IFO's load-bearing design idea, readable as data;-- reproduces IFO finding #4 in miniature: 49 tickers quoted in public SEC data, 0 ISIN assertions from any open source — including the Vanguard 500 ETF share class (VOO), which has a real ISIN in commercial data that GLEIF's open file simply does not carry;+- queries the SKOS registry for identifier schemes grouped by declared scope (entity- / issue- / venue-scoped), IFO's load-bearing design idea, readable as data;+- reproduces IFO finding #4 in miniature: 49 tickers quoted in public SEC data, 0 ISIN assertions from any open source, including the Vanguard 500 ETF share class (VOO), which has a real ISIN in commercial data that GLEIF's open file simply does not carry;- counts identifier assertions per source system (cross-system disagreement as a query, not an audit project);- validates the subgraph against IFO's layer-1/2 shapes: 37 findings, all the Warning-graded "quotation with no resolvable trading venue" gap, correctly reported as `Warning` per the shape's own `sh:severity`.-**Part 2 — full universe** (runs when `fund_graph.ttl` is present, else prints how to build it): loads the 1.29M-triple graph and executes the four layer-3 rules as plain SPARQL, printing counts next to the pipeline's published figures.+**Part 2, full universe** (runs when `fund_graph.ttl` is present, else prints how to build it): loads the 1.29M-triple graph and executes the four layer-3 rules as plain SPARQL, printing counts next to the pipeline's published figures.To build the full graph: clone IFO, run `scripts/fetch_data.sh` then `pipeline/build_graph.py`, and point `IFO_GRAPH` at `data/build/fund_graph.ttl` (default location is `~/projects/investment-fund-ontology/data/build/fund_graph.ttl`).@@ -46,7 +46,7 @@ To build the full graph: clone IFO, run `scripts/fetch_data.sh` then `pipeline/bRunning a real, externally-authored shapes file through `onto_shacl` is a better test than any synthetic fixture, and IFO's shapes immediately exposed two defects in this repo's SHACL engine, both fixed as part of this case study:1. **`sh:inversePath` support.** IFO's registrant shape uses `sh:path [ sh:inversePath ifo:fundOf ]` ("a registrant must have at least one fund series pointing at it"). The validator previously injected the blank node into a generated SPARQL query and aborted the *entire* validation with a parse error. It now translates `sh:inversePath` to SPARQL's `^` operator; any other complex path (sequence, alternative, zero-or-more) is skipped and reported under `skipped_constraints` instead of poisoning the run.-2. **`sh:severity` honored.** The report hardcoded every finding as `Violation`. IFO grades its venue-gap shape `sh:Warning` with a message that explicitly says "not an error in the record" — reporting it as a Violation would misstate the ontology's own semantics. The validator now reads `sh:severity` off the property shape, defaulting to `Violation` per the SHACL spec.+2. **`sh:severity` honored.** The report hardcoded every finding as `Violation`. IFO grades its venue-gap shape `sh:Warning` with a message that explicitly says "not an error in the record"; reporting it as a Violation would misstate the ontology's own semantics. The validator now reads `sh:severity` off the property shape, defaulting to `Violation` per the SHACL spec.Regression tests for both are in `tests/shacl_test.rs`.diff --git a/case-studies/jc3iedm-ies4-crosswalk/README.md b/case-studies/jc3iedm-ies4-crosswalk/README.mdindex f1c38b95..70e0c3b0 100644--- a/case-studies/jc3iedm-ies4-crosswalk/README.md+++ b/case-studies/jc3iedm-ies4-crosswalk/README.md@@ -32,9 +32,9 @@ For each JC3IEDM entity:1. **Identify the IES4 nearest neighbour.** Walk the IES4 4D taxonomy (Particular vs ClassOfEntity vs Event vs State) and pick the class whose extension covers the JC3IEDM entity's instances. Prefer specificity (a JC3IEDM PERSON maps to IES4 Person, not to the abstract Particular).2. **Choose the SKOS relation:**- - `skos:exactMatch` — when the IES4 class's extension matches the JC3IEDM entity's intended population exactly. Rare in this sketch; the 4D vs snapshot difference usually prevents true exactMatch.- - `skos:closeMatch` — when the IES4 class covers the JC3IEDM entity's population but adds 4D structure (time-extents, role-states) that JC3IEDM treats as attributes. Used for most mappings here.- - `skos:relatedMatch` — when the IES4 class is conceptually adjacent but not a substitution candidate. Used for cases where the semantic gap is too wide for a straight match.+ - `skos:exactMatch`: when the IES4 class's extension matches the JC3IEDM entity's intended population exactly. Rare in this sketch; the 4D vs snapshot difference usually prevents true exactMatch.+ - `skos:closeMatch`: when the IES4 class covers the JC3IEDM entity's population but adds 4D structure (time-extents, role-states) that JC3IEDM treats as attributes. Used for most mappings here.+ - `skos:relatedMatch`: when the IES4 class is conceptually adjacent but not a substitution candidate. Used for cases where the semantic gap is too wide for a straight match.3. **Document the gap.** For every mapping, the crosswalk TTL includes an `rdfs:comment` explaining what the IES4 class adds, removes, or reframes vs the JC3IEDM entity.4. **Use a placeholder JC3IEDM IRI namespace.** STANAG 5525 doesn't issue canonical web IRIs; this sketch uses `http://example.org/jc3iedm/` as a placeholder. A real implementation would use NATO/MIP-issued IRIs.@@ -50,15 +50,15 @@ For each JC3IEDM entity:| FACILITY | `ies:BuiltStructure` | `skos:closeMatch` | IES4 treats location as separate 4D extent || LOCATION | `ies:Location` | `skos:exactMatch` | Both are spatial Particulars; closest match in the set || EVENT | `ies:Event` | `skos:closeMatch` | IES4 requires participants (per the `ies4` enforce rule); JC3IEDM EVENT is looser |-| ACTION | `ies:CommunicationEvent` ⊔ `ies:Process` | `skos:relatedMatch` | JC3IEDM ACTION subsumes both deliberate processes and communication acts — needs splitting |+| ACTION | `ies:CommunicationEvent` ⊔ `ies:Process` | `skos:relatedMatch` | JC3IEDM ACTION subsumes both deliberate processes and communication acts; needs splitting || CAPABILITY | `ies:PowerOfDisposition` | `skos:closeMatch` | Both encode a ZUR (ability) over actions; IES4 attaches it to a state || REPORTING-DATA | `ies:Representation` | `skos:closeMatch` | IES4 frames reports as Representations of underlying particulars || AFFILIATION | `ies:MemberState` | `skos:closeMatch` | JC3IEDM treats as attribute; IES4 models as state-of-being-member |## Files-- [`crosswalk.ttl`](crosswalk.ttl) — the SKOS mappings, runnable through Open Ontologies' tooling-- [`verify.sh`](verify.sh) — checks the IES4 IRIs in the crosswalk resolve against `IES-Org/ont-ies` (live) and `dstl/IES4` v4.3.1 (frozen MIT baseline, via `onto_marketplace install ies-4.3.1`)+- [`crosswalk.ttl`](crosswalk.ttl): the SKOS mappings, runnable through Open Ontologies' tooling+- [`verify.sh`](verify.sh): checks the IES4 IRIs in the crosswalk resolve against `IES-Org/ont-ies` (live) and `dstl/IES4` v4.3.1 (frozen MIT baseline, via `onto_marketplace install ies-4.3.1`)## Usage@@ -79,16 +79,16 @@ bash case-studies/jc3iedm-ies4-crosswalk/verify.shPRs welcome. Useful contributions in priority order:-1. **Correct misalignments** — if you have JC3IEDM expertise and an IES4 class is wrong for a given entity, open a PR with the fix and a rationale.-2. **Extend coverage** — pick a JC3IEDM entity from the remaining 261 and add a mapping.-3. **Add bidirectional transformation logic** — beyond SKOS, the real work is mapping JC3IEDM attributes and relationships to IES4's 4D patterns.+1. **Correct misalignments**: if you have JC3IEDM expertise and an IES4 class is wrong for a given entity, open a PR with the fix and a rationale.+2. **Extend coverage**: pick a JC3IEDM entity from the remaining 261 and add a mapping.+3. **Add bidirectional transformation logic**: beyond SKOS, the real work is mapping JC3IEDM attributes and relationships to IES4's 4D patterns.## References-- STANAG 5525 (JC3IEDM specification — NATO restricted)+- STANAG 5525 (JC3IEDM specification, NATO restricted)- [IES Information Exchange Standard](https://informationexchangestandard.org/) (canonical portal; custodied by UK DBT since March 2025)- [`IES-Org/ont-ies`](https://github.com/IES-Org/ont-ies) (canonical IES repo)-- [`dstl/IES4`](https://github.com/dstl/IES4) (archived; tag `v4.3.1` is the last MIT-licensed snapshot — available in this repo's marketplace as `ies-4.3.1`)+- [`dstl/IES4`](https://github.com/dstl/IES4) (archived; tag `v4.3.1` is the last MIT-licensed snapshot, available in this repo's marketplace as `ies-4.3.1`)- FOUST 7 paper, "Comparing IES and BORO" (CEUR Vol-4176, JOWO 2024)## Licencediff --git a/case-studies/mcp-ies-rag-demo/README.md b/case-studies/mcp-ies-rag-demo/README.mdindex 0e3561e1..ee4b2f30 100644--- a/case-studies/mcp-ies-rag-demo/README.md+++ b/case-studies/mcp-ies-rag-demo/README.md@@ -12,10 +12,10 @@ Per the May 2026 IES4 ecosystem research finding: nobody has publicly grafted LL```case-studies/mcp-ies-rag-demo/-├── README.md this file — the pattern, the why+├── README.md this file: the pattern, the why├── data/│ ├── ies-sample.ttl small IES4-conformant graph (~30 individuals,-│ │ ~80 triples) — people / orgs / locations /+│ │ ~80 triples): people / orgs / locations /│ │ 4D role-states / events with participants│ └── competency-questions.md 6 natural-language questions, each with│ the ontology-grounded answer and the@@ -27,7 +27,7 @@ case-studies/mcp-ies-rag-demo/## The pattern in one paragraph-`onto_embed` over the loaded IES4 graph gives Claude semantic retrieval over particulars (named entities like Alice Patel, Acme Bristol). `onto_query` lets Claude run SPARQL when a question requires structural reasoning (temporal extents, set membership, participant edges). The two combine: Claude retrieves the relevant subgraph by semantic search, then queries it precisely to answer. The 4D modelling means that **states are first-class** — "Alice was the Bristol manager" is a state with a period, not an attribute of Alice — so questions like "who held that role in 2022?" reduce to a SPARQL FILTER over period strings rather than a guess.+`onto_embed` over the loaded IES4 graph gives Claude semantic retrieval over particulars (named entities like Alice Patel, Acme Bristol). `onto_query` lets Claude run SPARQL when a question requires structural reasoning (temporal extents, set membership, participant edges). The two combine: Claude retrieves the relevant subgraph by semantic search, then queries it precisely to answer. The 4D modelling means that **states are first-class** ("Alice was the Bristol manager" is a state with a period, not an attribute of Alice), so questions like "who held that role in 2022?" reduce to a SPARQL FILTER over period strings rather than a guess.## Why this beats flat document RAG@@ -79,23 +79,23 @@ This is a **case study**, not a product. It:- Uses a synthetic 30-individual dataset, not real operational data. Real deployments would load actual IES-conformant graphs (e.g. NDTP-style assets, MOD intelligence corpora).- Uses a placeholder `demo:roleIn` helper property. A production IES4 implementation would use the canonical `ies:MemberState` + `ies:isMemberOf` pattern. The shortcut keeps the demo Turtle readable.-- Doesn't include a quantitative evaluation. A real comparison vs flat document RAG would need a benchmark corpus and human-evaluated accuracy on both temporal and atemporal questions — that's a follow-up paper, not a case study.+- Doesn't include a quantitative evaluation. A real comparison vs flat document RAG would need a benchmark corpus and human-evaluated accuracy on both temporal and atemporal questions; that's a follow-up paper, not a case study.- Doesn't ship runtime code beyond what's already in Open Ontologies (load, query, embed, search). The case study is the dataset + the questions + the documented pattern.## How to extendPRs welcome. Useful directions:-1. **Add more competency questions** to `data/competency-questions.md` — particularly questions that combine multiple temporal extents (e.g. "who held overlapping roles in different orgs simultaneously?").-2. **Add a real dataset** — replace the synthetic data with an IES-conformant transformation of public NDTP data, the Wales valuation report dataset, or similar.-3. **Add a quantitative benchmark** — define a question set, run flat-RAG and onto-grounded-RAG on the same corpus, measure accuracy + latency.+1. **Add more competency questions** to `data/competency-questions.md`, particularly questions that combine multiple temporal extents (e.g. "who held overlapping roles in different orgs simultaneously?").+2. **Add a real dataset**: replace the synthetic data with an IES-conformant transformation of public NDTP data, the Wales valuation report dataset, or similar.+3. **Add a quantitative benchmark**: define a question set, run flat-RAG and onto-grounded-RAG on the same corpus, measure accuracy + latency.4. **Extend the JC3IEDM crosswalk** (the sibling case study at [`../jc3iedm-ies4-crosswalk/`](../jc3iedm-ies4-crosswalk/)) so you can ingest JC3IEDM-shaped data and answer questions via the IES4 4D model.## References- [IES Information Exchange Standard](https://informationexchangestandard.org/)-- [`IES-Org/ont-ies`](https://github.com/IES-Org/ont-ies) — canonical IES repo (custodied by UK DBT since March 2025)-- [Telicent Smart-Cache-Graph](https://github.com/orgs/telicent-oss/repositories) — the RAG-substrate-shaped commercial stack from the IES Working Group's primary implementation partner+- [`IES-Org/ont-ies`](https://github.com/IES-Org/ont-ies): canonical IES repo (custodied by UK DBT since March 2025)+- [Telicent Smart-Cache-Graph](https://github.com/orgs/telicent-oss/repositories): the RAG-substrate-shaped commercial stack from the IES Working Group's primary implementation partner- FOUST 7 paper, "Comparing IES and BORO" (CEUR Vol-4176, JOWO 2024)## Licencediff --git a/case-studies/modip-plastics-kg/BUILD_REPORT.md b/case-studies/modip-plastics-kg/BUILD_REPORT.mdindex 15e5f8cc..87bd8bde 100644--- a/case-studies/modip-plastics-kg/BUILD_REPORT.md+++ b/case-studies/modip-plastics-kg/BUILD_REPORT.md@@ -3,10 +3,10 @@A scrupulous account of what was fetched, what was computed, and what could notbe obtained. Every number here is reproduced by the scripts in `src/`.-## Source data — what was fetched+## Source data: what was fetched-- **Provider:** Museum Data Service (MDS) — a joint service of Art UK, Collections- Trust and the University of Leicester — via its public `extract` API+- **Provider:** Museum Data Service (MDS), a joint service of Art UK, Collections+ Trust and the University of Leicester, via its public `extract` API(`https://mds-data-2.ciim.k-int.com/api/v1/extract`).- **Collection:** Museum of Design in Plastics (MoDiP), Arts University Bournemouth.- **Records fetched:** **11,865** (the complete MoDiP set in MDS at the time of@@ -18,7 +18,7 @@ be obtained. Every number here is reproduced by the scripts in `src/`.- **API access:** the MDS API token is obtained free from the declaration form onany MDS object-search results page. It is supplied to the fetch script via the`MDS_TOKEN` environment variable and is **not** committed to this repository.-- The raw records are stored unmodified at `data/raw/modip_records.json` so every+- The raw records are stored unmodified (gzipped) at `data/raw/modip_records.json.gz` so everydownstream step is reproducible without re-hitting the API.## What was computed@@ -40,7 +40,7 @@ to value+unit; 955 controlled object-name types; 18 colour types.## What could NOT be obtained / limitations-- **49 material assertions (0.1%) are unreconciled** — obscure single-occurrence+- **49 material assertions (0.1%) are unreconciled**: obscure single-occurrencetrade names (D3O, Delaron, Stamisol, Diaplex, Guardian, …). They are linked to`mat:plastic_unidentified` and listed in `build/build_stats.json`(`top_unreconciled_materials`) rather than silently dropped or guessed.diff --git a/case-studies/modip-plastics-kg/README.md b/case-studies/modip-plastics-kg/README.mdindex cf8d7212..8745ef11 100644--- a/case-studies/modip-plastics-kg/README.md+++ b/case-studies/modip-plastics-kg/README.md@@ -1,8 +1,8 @@# MoDiP Plastics Knowledge Graph**A worked example of turning a small museum's raw collection records into a-standards-based knowledge graph — taxonomy, ontology mapping, and a variant-graph — using only open standards and the museum's own open data.**+standards-based knowledge graph (taxonomy, ontology mapping, and a variant+graph) using only open standards and the museum's own open data.**The [Museum of Design in Plastics](https://www.modip.ac.uk/) (MoDiP, ArtsUniversity Bournemouth) publishes **11,865** object records through the@@ -11,7 +11,7 @@ data, they are published as *raw material*: flat, free-text, un-linked. The samepolymer appears as `PP`, `polypropylene`, `polythene` and `Perspex - trade name`as unrelated strings; relationships between objects sit unread inside descriptionprose. This repository shows, end to end, what it takes to make that data-computable — and does it against the real records, not a toy sample.+computable, and does it against the real records, not a toy sample.Nothing here is bespoke where a standard exists. The instance graph is**CIDOC-CRM** (ISO 21127, Linked Art compatible); the vocabularies are **SKOS**,@@ -26,7 +26,7 @@ minted locally are the concept and instance identifiers.| Materials taxonomy | [`ontology/materials.ttl`](ontology/materials.ttl) | 137 SKOS concepts (thermoplastic / thermoset / elastomer / biopolymer), abbreviations + trade names as `altLabel`, 55 Getty AAT `exactMatch` || Process taxonomy | [`ontology/processes.ttl`](ontology/processes.ttl) | 65 concepts (moulding, extrusion, forming, machining, textile processes) || Domain taxonomy | [`ontology/domains.ttl`](ontology/domains.ttl) | 29 concepts (MoDiP's own use-domain facet, made hierarchical) |-| Instance graph | [`build/modip-crm.ttl`](build/modip-crm.ttl) | 485,013 triples, 11,865 `crm:E22_Human-Made_Object`s |+| Instance graph | [`build/modip-crm.ttl.gz`](build/modip-crm.ttl.gz) (gzipped Turtle) | 485,013 triples, 11,865 `crm:E22_Human-Made_Object`s || Variant DAG | [`build/dag_variants.ttl`](build/dag_variants.ttl) · [`.csv`](build/dag_variants.csv) | 289 same-mould / cross-reference edges recovered from description prose || Spectrum→CRM crosswalk | [`docs/spectrum-crm-mapping.md`](docs/spectrum-crm-mapping.md) | the reusable mapping, field by field || Honesty log | [`BUILD_REPORT.md`](BUILD_REPORT.md) | exactly what was fetched, computed, and could not be obtained |@@ -55,7 +55,7 @@ mat:pvc a skos:Concept, crm:E57_Material ;```(`aat:300014513` is the verified Getty AAT concept for polyvinyl chloride; the`pmma` concept carries the abbreviations and trade names too, but is left without-an AAT link because no exact-label AAT match was found — see `BUILD_REPORT.md`.)+an AAT link because no exact-label AAT match was found; see `BUILD_REPORT.md`.)## Reproduce@@ -77,7 +77,7 @@ form on any [MDS object-search page](https://museumdata.uk/object-search/) and r[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Per-record rights areretained in the graph (`dct:license`, `dct:rightsHolder`).- **This transformation** (taxonomies, mappings, code) is released under- [CC BY 4.0](LICENSE) (data/vocabularies) and MIT (code) — see [`LICENSE`](LICENSE).+ [CC BY 4.0](LICENSE) (data/vocabularies) and MIT (code); see [`LICENSE`](LICENSE).- **Getty AAT** alignments © J. Paul Getty Trust, under[ODC-By 1.0](https://opendatacommons.org/licenses/by/1-0/).@@ -88,7 +88,7 @@ form on any [MDS object-search page](https://museumdata.uk/object-search/) and rBuilt by **[The Tesseract Academy](https://tesseract.academy)** as an opendemonstration for the GLAM (galleries, libraries, archives, museums) sector: thisis the pipeline that takes *any* museum's Spectrum/CSV export to a validated,-standards-based knowledge graph. If you run a collection — or fund one — and want+standards-based knowledge graph. If you run a collection, or fund one, and wantyour data made this queryable (or want the method applied to your own catalogue),we'd genuinely like to hear from you: **[email protected]**.diff --git a/case-studies/nature-governance-graph/README.md b/case-studies/nature-governance-graph/README.mdindex 7dc4c709..9cd416fb 100644--- a/case-studies/nature-governance-graph/README.md+++ b/case-studies/nature-governance-graph/README.md@@ -54,13 +54,13 @@ Environment Act 2021 s.104. Each of those is carried in the relationship's## Files-- `data/entities.json` — the sourced source-of-truth (actors + relationships)-- `ontology/ngg.ttl` — the NGG vocabulary (reuses W3C ORG, PROV-O, SKOS, Dublin Core)-- `shapes/ngg-shapes.ttl` — SHACL shapes (labelling, controlled vocab, sourcing, referential integrity)-- `graph.ttl` / `graph.jsonld` — the built graph-- `queries/competency.rq` — the competency questions the graph answers-- `pipeline/build_and_validate.py` — reproducible build + validation-- `metrics.json` — machine-readable build metrics+- `data/entities.json`: the sourced source-of-truth (actors + relationships)+- `ontology/ngg.ttl`: the NGG vocabulary (reuses W3C ORG, PROV-O, SKOS, Dublin Core)+- `shapes/ngg-shapes.ttl`: SHACL shapes (labelling, controlled vocab, sourcing, referential integrity)+- `graph.ttl` / `graph.jsonld`: the built graph+- `queries/competency.rq`: the competency questions the graph answers+- `pipeline/build_and_validate.py`: reproducible build + validation+- `metrics.json`: machine-readable build metrics## Reproducediff --git a/case-studies/skills-england-esco-crosswalk/README.md b/case-studies/skills-england-esco-crosswalk/README.mdindex 610b676b..cfa62c09 100644--- a/case-studies/skills-england-esco-crosswalk/README.md+++ b/case-studies/skills-england-esco-crosswalk/README.md@@ -44,11 +44,11 @@ not quietly assumed away.## Files-- `data/esco_candidates.jsonl` — cached ESCO API candidates per occupation-- `data/crosswalk.json` — full banded crosswalk incl. unmatched-- `crosswalk.ttl` — SKOS mappings (skos:exactMatch / closeMatch / relatedMatch)-- `pipeline/fetch_esco.py`, `pipeline/build_crosswalk.py` — reproducible build-- `metrics.json` — band counts and match rate+- `data/esco_candidates.jsonl`: cached ESCO API candidates per occupation+- `data/crosswalk.json`: full banded crosswalk incl. unmatched+- `crosswalk.ttl`: SKOS mappings (skos:exactMatch / closeMatch / relatedMatch)+- `pipeline/fetch_esco.py`, `pipeline/build_crosswalk.py`: reproducible build+- `metrics.json`: band counts and match rate## Reproducediff --git a/case-studies/wastewater-effluent-quality/README.md b/case-studies/wastewater-effluent-quality/README.mdindex 83cbf5e1..7dfd9c20 100644--- a/case-studies/wastewater-effluent-quality/README.md+++ b/case-studies/wastewater-effluent-quality/README.md@@ -1,4 +1,4 @@-# Case study: wastewater effluent data quality — Open Ontologies+# Case study: wastewater effluent data quality with Open OntologiesA reproducible, open-data demonstration of how Open Ontologies turns a regulatedwastewater monitoring stream into **trustworthy, machine-validated data**. It pairs@@ -14,13 +14,13 @@ validation** (encode the physics so impossible records can never pass).## The data-`Data-Melbourne_F.csv` — a full-scale wastewater treatment plant, daily records+`Data-Melbourne_F.csv`: a full-scale wastewater treatment plant, daily records**2014-01-01 to 2019-06-27 (1,382 days)**, carrying the regulated effluent suite:ammonia, BOD, COD, total nitrogen, plus average inflow/outflow. Source: Kaggle,[Full Scale Waste Water Treatment Plant Data](https://www.kaggle.com/datasets/d4rklucif3r/full-scale-waste-water-treatment-plant-data)(CC BY-SA 4.0). The CSV is fetched by `qa_wwtp.py`.-## Layer 1 — statistical QA (`qa_wwtp.py`)+## Layer 1: statistical QA (`qa_wwtp.py`)A robust, reproducible battery: completeness against the daily cadence, stuck-sensor(flatline) runs, median-absolute-deviation outlier detection (so genuine pollution@@ -40,25 +40,25 @@ Headline findings on this works:| Avg inflow (ML/d) | 100% | 0 | 34 | +1.1 |The series is complete and internally consistent (the COD ≥ BOD invariant holds on-every one of 1,382 rows — a strong curation signal), but the QA pass still surfaces+every one of 1,382 rows, a strong curation signal), but the QA pass still surfacesgenuine structure a trend analyst must handle: dozens of statistical outliers perdeterminand and a multi-year COD baseline drift of +115 mg/L that no single-pointrange check would catch.-## Layer 2 — declarative validation (SHACL)+## Layer 2: declarative validation (SHACL)-- [`effluent-ontology.ttl`](effluent-ontology.ttl) — the observation model (ISO 19156+- [`effluent-ontology.ttl`](effluent-ontology.ttl): the observation model (ISO 19156/ W3C SOSA pattern: one observation, one value per determinand, an assurance state).-- [`effluent-snapshots.ttl`](effluent-snapshots.ttl) — six records: three clean, three+- [`effluent-snapshots.ttl`](effluent-snapshots.ttl): six records: three clean, threewith a planted fault.-- [`data-quality-shapes.ttl`](data-quality-shapes.ttl) — eight SHACL rules: required+- [`data-quality-shapes.ttl`](data-quality-shapes.ttl): eight SHACL rules: requireddate, per-determinand non-negative range bands, non-empty record, and two**domain-aware cross-parameter rules**.The load-bearing rule is **R7: COD ≥ BOD**. Chemical Oxygen Demand measures alloxidisable matter; Biochemical Oxygen Demand only the biodegradable fraction, so bydefinition COD can never be below BOD. A record where it is, is physically-impossible and must be rejected — something no per-column range check can see. R8+impossible and must be rejected, something no per-column range check can see. R8applies the same idea to flow conservation (outflow should not grossly exceed inflow).### Run it@@ -82,7 +82,7 @@ conforms: FalseClassification of "is this data trustworthy?" is **declarative, not learned**. Eachquality rule is a constraint, not a trained model: no labelled fault set, no-retraining when a new failure mode appears — you add a rule. Statistics finds the+retraining when a new failure mode appears: you add a rule. Statistics finds theanomalies; the ontology and its shapes encode the domain physics that decide whichanomalies are merely unusual and which are impossible. That separation is what makesthe verdict auditable, and auditable data quality is exactly what a regulator needsdiff --git a/case-studies/zero-emission-aviation/README.md b/case-studies/zero-emission-aviation/README.mdindex 50b673b9..b2509496 100644--- a/case-studies/zero-emission-aviation/README.md+++ b/case-studies/zero-emission-aviation/README.md@@ -1,4 +1,4 @@-# UK Zero-Emission Flight Ecosystem — an open, computation-ready reference graph+# UK Zero-Emission Flight Ecosystem: an open, computation-ready reference graphAn open, SHACL-validated, **provenance-first** knowledge graph of the UK hydrogen and electricaviation ecosystem: organisations, airports, programmes, projects, funders, bodies, alliances,@@ -44,7 +44,7 @@ Entities by type: 15 organisations, 6 projects, 3 programmes, 3 funders, 3 bodie## Design and methodologyThe ontology is engineered, not hand-waved. It follows the **Linked Open Terms (LOT)** framework-(Poveda-Villalón et al., 2022) — requirements, implementation, publication — with these disciplines:+(Poveda-Villalón et al., 2022) across requirements, implementation and publication, with these disciplines:- **Competency-question driven** (Grüninger & Fox, 1995). The scope is fixed by six competencyquestions (`queries/competency.rq`), and those same questions are re-run as SPARQL **acceptance@@ -91,54 +91,54 @@ The SHACL shapes (`shapes/zef-shapes.ttl`) enforce, and the pipeline proves:CQ3, for example, returns eight provenanced figures including the January 2021 £84.6m green-aviationpackage, GKN H2GEAR (£54.4m total / £27.2m ATI grant), ZeroAvia HyFlyer II (£24.6m / £12.3m ATI),GKN H2FlyGHT (£44m, 2 MW), and the Hydrogen in Aviation alliance's projected £34bn/year UK benefit by-2050 — each traceable to a primary source.+2050, each traceable to a primary source.## Related work (verified, 2020-2026 unless noted as foundational)**Hydrogen and energy ontologies / KGs**- Ascencion Arevalo K M, Neunsinger C. *HOLY: An Ontology Covering the Hydrogen Market.* ISWC 2023,- LNCS 14266. https://doi.org/10.1007/978-3-031-47243-5_1 — the two-axis actors x value-chain design.+ LNCS 14266. https://doi.org/10.1007/978-3-031-47243-5_1; the two-axis actors x value-chain design.- Booshehri M et al. *Introducing the Open Energy Ontology.* Energy and AI 5, 2021.- https://doi.org/10.1016/j.egyai.2021.100074 — BFO-based modular energy ontology; continuant/occurrent.+ https://doi.org/10.1016/j.egyai.2021.100074; BFO-based modular energy ontology; continuant/occurrent.- Santos G et al. *Intelligent Energy Systems Ontology (IESO).* Energy and AI, 2023.- https://doi.org/10.1016/j.ecmx.2023.100495 — integrate-don't-reinvent + SHACL + unit conversion.+ https://doi.org/10.1016/j.ecmx.2023.100495; integrate-don't-reinvent + SHACL + unit conversion.- Haghgoo M et al. *SARGON – Smart energy domain ontology.* IET Smart Cities 2(4), 2020.- https://doi.org/10.1049/iet-smc.2020.0049 — SAREF-extension pattern (lightweight, no upper ontology).+ https://doi.org/10.1049/iet-smc.2020.0049; SAREF-extension pattern (lightweight, no upper ontology).**Emissions provenance and quantities**- Markovic M, Garijo D, Germano S, Naja I. *PECO: The Provenance of Emission Calculations Ontology*, 2023.- https://w3id.org/peco — PROV-O + QUDT + SOSA composition for auditable figures.+ https://w3id.org/peco; PROV-O + QUDT + SOSA composition for auditable figures.**Aviation / aerospace knowledge engineering**- Wittenborg T et al. *Knowledge-Based Aerospace Engineering — A Systematic Literature Review.* arXiv- 2505.10142, 2025. https://arxiv.org/abs/2505.10142 — process/software/data backbone; names the+ 2505.10142, 2025. https://arxiv.org/abs/2505.10142; process/software/data backbone; names thesustainable-aviation gap.- Kabashkin I. *Ontology-Driven Digital Twin Framework for Aviation Maintenance and Operations.*- Mathematics 13(17):2817, 2025. https://doi.org/10.3390/math13172817 — modular multi-ontology design.+ Mathematics 13(17):2817, 2025. https://doi.org/10.3390/math13172817; modular multi-ontology design.- Georgiou J et al. *The ICARUS Ontology: A General Aviation Ontology.* WIMS 2020.- https://doi.org/10.1145/3405962.3405983 — reuse + generic-metadata/domain-layer separation.+ https://doi.org/10.1145/3405962.3405983; reuse + generic-metadata/domain-layer separation.**Funding and technology-maturity KGs**- Chialva D, Mugabushaka A-M. *DINGO: an ontology for projects and grants linked data.* SKG/TPDL 2020.- https://arxiv.org/abs/2006.13438 · https://w3id.org/dingo — the funds/grant/policy schema.+ https://arxiv.org/abs/2006.13438 · https://w3id.org/dingo; the funds/grant/policy schema.- EURIO / CORDIS Knowledge Graph, Publications Office of the EU.- https://op.europa.eu/en/web/eu-vocabularies/eurio — EU-funding interoperability target.+ https://op.europa.eu/en/web/eu-vocabularies/eurio; EU-funding interoperability target.- Trappey A J C, Lin G-B, Hung L-P. *Intelligent Text Mining for Ontological KG Refinement and PatentPortfolio Analysis — Net-Zero Data Center.* Information 15(7):374, 2024.- https://doi.org/10.3390/info15070374 — couples an ontology/KG to technology-maturity analytics.+ https://doi.org/10.3390/info15070374; couples an ontology/KG to technology-maturity analytics.**Reusable W3C / standard building blocks**- Haller A et al. *Semantic Sensor Network Ontology (SOSA/SSN).* W3C Recommendation, 2017.https://www.w3.org/TR/vocab-ssn/- Lebo T et al. *PROV-O: The PROV Ontology.* W3C Recommendation, 2013. https://www.w3.org/TR/prov-o/- Miles A, Bechhofer S. *SKOS Reference.* W3C Recommendation, 2009. https://www.w3.org/TR/skos-reference/-- QUDT — Quantities, Units, Dimensions and Types. https://qudt.org/+- QUDT: Quantities, Units, Dimensions and Types. https://qudt.org/**Ontology-engineering methodology**- Poveda-Villalón M et al. *LOT: An industrial oriented ontology engineering framework.* EAAI 111, 2022.https://doi.org/10.1016/j.engappai.2022.104755- Grüninger M, Fox M S. *Methodology for the Design and Evaluation of Ontologies.* IJCAI-95 workshop- (foundational). — competency questions.+ (foundational); competency questions.- Poveda-Villalón M et al. *OOPS! (OntOlogy Pitfall Scanner!).* IJSWIS 10(2), 2014.https://doi.org/10.4018/ijswis.2014040102- Wilkinson M D et al. *The FAIR Guiding Principles.* Scientific Data 3:160018, 2016.