Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

feat: add IES (NDTP core ontology) support — marketplace preset, SPARQL examples, alignment guide

FABIOTESS76cbc2c8d273
diff --git a/README.md b/README.md
index 42d54469..fb416708 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@
<a href="#quick-start-mcp--cli">Quick Start</a> ·
<a href="#studio-desktop-app">Studio</a> ·
<a href="#benchmarks">Benchmarks</a> ·
+ <a href="#ies-support">IES</a> ·
<a href="#tools">Tools</a> ·
<a href="#architecture">Architecture</a> ·
<a href="#documentation">Docs</a>
@@ -30,7 +31,7 @@
---
-Open Ontologies is a **Rust MCP server** and **desktop Studio** for AI-native ontology engineering. It exposes **48 tools** that let Claude build, validate, query, diff, lint, version, reason over, align, and persist RDF/OWL ontologies using an in-memory Oxigraph triple store — with Terraform-style lifecycle management, a marketplace of 29 standard ontologies, clinical crosswalks, semantic embeddings, and a full lineage audit trail.
+Open Ontologies is a **Rust MCP server** and **desktop Studio** for AI-native ontology engineering. It exposes **48 tools** that let Claude build, validate, query, diff, lint, version, reason over, align, and persist RDF/OWL ontologies using an in-memory Oxigraph triple store — with Terraform-style lifecycle management, a marketplace of 30 standard ontologies, clinical crosswalks, semantic embeddings, and a full lineage audit trail.
The **Studio** wraps the engine in a visual desktop environment: 3D force-directed graph, AI chat panel, Protégé-style property inspector, and lineage viewer.
@@ -292,6 +293,47 @@ Full benchmark writeup: [docs/benchmarks.md](docs/benchmarks.md)
---
+## IES Support
+
+[IES (Information Exchange Standard)](https://github.com/IES-Org/ont-ies) is the UK National Digital Twin Programme's core ontology. It uses a 4D extensionalist (BORO) approach for modelling entities, events, states, and relationships. Open Ontologies includes first-class IES support:
+
+### Quick Start
+
+```bash
+# Install IES from the marketplace
+open-ontologies marketplace install ies
+
+# Or pull directly
+open-ontologies pull https://raw.githubusercontent.com/IES-Org/ont-ies/main/docs/specification/ies-common.ttl
+```
+
+### Full Workflow
+
+```text
+onto_marketplace install ies # fetch IES v5 ontology
+onto_stats # verify class/property/triple counts
+onto_lint # check for missing labels, domains, ranges
+onto_reason --profile owl-rl # materialise inferred triples
+onto_stats # verify inferred counts
+onto_query "..." # run IES-specific SPARQL queries
+```
+
+### IES:Building Alignment
+
+The repo includes an [IES Building Extension](benchmark/generated/ies-building-extension.ttl) that models buildings, dwellings, energy performance, and retrofit interventions using IES 4D patterns. Use `onto_align` to map it to other domain ontologies:
+
+```text
+onto_align --source ies-building.ttl --target schema-org.ttl
+```
+
+This mirrors NDTP's active work transforming energy performance data into RDF aligned with IES:Building. See the full walkthrough in [docs/ies-alignment.md](docs/ies-alignment.md).
+
+### SPARQL Examples
+
+5 ready-to-use IES queries covering Person subclasses, EventParticipant relationships, 4D temporal patterns, Location hierarchies, and the ClassOfEntity type-instance pattern. See [docs/ies-examples.md](docs/ies-examples.md).
+
+---
+
## Tools
48 tools organized by function — available as MCP tools (prefixed `onto_`) and CLI subcommands:
@@ -299,7 +341,7 @@ Full benchmark writeup: [docs/benchmarks.md](docs/benchmarks.md)
| Category | Tools | Purpose |
| --- | --- | --- |
| **Core** | `validate` `load` `save` `clear` `stats` `query` `diff` `lint` `convert` `status` | RDF/OWL validation, querying, and management |
-| **Marketplace** | `marketplace` | Browse and install 29 standard W3C/ISO/industry ontologies |
+| **Marketplace** | `marketplace` | Browse and install 30 standard W3C/ISO/industry ontologies |
| **Remote** | `pull` `push` `import-owl` | Fetch/push ontologies, resolve owl:imports |
| **Schema** | `import-schema` | PostgreSQL → OWL conversion |
| **Data** | `map` `ingest` `shacl` `reason` `extend` | Structured data → RDF pipeline |
@@ -466,6 +508,8 @@ flowchart TD
| OWL2-DL Reasoning | [docs/reasoning.md](docs/reasoning.md) |
| Semantic Embeddings | [docs/embeddings.md](docs/embeddings.md) |
| Clinical Crosswalks | [docs/clinical.md](docs/clinical.md) |
+| IES SPARQL Examples | [docs/ies-examples.md](docs/ies-examples.md) |
+| IES:Building Alignment | [docs/ies-alignment.md](docs/ies-alignment.md) |
| Benchmarks | [docs/benchmarks.md](docs/benchmarks.md) |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Changelog | [CHANGELOG.md](CHANGELOG.md) |
diff --git a/docs/ies-alignment.md b/docs/ies-alignment.md
new file mode 100644
index 00000000..0e4d1589
--- /dev/null
+++ b/docs/ies-alignment.md
@@ -0,0 +1,131 @@
+# IES:Building Alignment Example
+
+This guide demonstrates aligning the [IES Building Extension](../benchmark/generated/ies-building-extension.ttl) with another domain ontology using `onto_align`. This directly mirrors NDTP's active work transforming energy performance data into RDF aligned with IES:Building.
+
+## Background
+
+NDTP is building data pipelines that transform energy performance data (EPCs, heating systems, insulation records) into RDF aligned with IES. The IES Building Extension models:
+
+- **Building** → subclass of `ies:Facility` and `ies:Asset`
+- **Dwelling** → subclass of `ies:PartOfFacility` (a self-contained residential unit)
+- **EnergyPerformanceCertificate** → subclass of `ies:Document`
+- **HeatingSystem** / **InsulationElement** → subclasses of `ies:Asset`
+- **RetrofitIntervention** / **EnergyPerformanceReview** → subclasses of `ies:Event`
+
+All following the 4D extensionalist (BORO) pattern with temporal states and bounding states.
+
+## Step 1: Load Both Ontologies
+
+Load the IES Building Extension as the source and Schema.org as the target for alignment:
+
+```text
+# Load IES Building Extension
+onto_validate benchmark/generated/ies-building-extension.ttl
+onto_load benchmark/generated/ies-building-extension.ttl
+
+# Save current state, then load target for alignment
+onto_save /tmp/ies-building.ttl
+onto_clear
+
+# Load Schema.org as alignment target
+onto_marketplace install schema-org
+onto_save /tmp/schema-org.ttl
+onto_clear
+```
+
+## Step 2: Run Alignment
+
+```text
+onto_align --source /tmp/ies-building.ttl --target /tmp/schema-org.ttl
+```
+
+The alignment engine uses 6 structural signals (+ embedding similarity if embeddings are loaded):
+
+1. **Label match** — Jaro-Winkler similarity on rdfs:label
+2. **Local name match** — IRI fragment comparison
+3. **Comment overlap** — Token-level Jaccard on rdfs:comment
+4. **Parent match** — Shared superclass names
+5. **Property overlap** — Common property names in domain/range
+6. **Sibling overlap** — Shared sibling class names
+7. **Embedding similarity** — Cosine + Poincaré distance (if `onto_embed` was run)
+
+### Expected Alignment Candidates
+
+| IES Building Class | Schema.org Class | Signal |
+| --- | --- | --- |
+| `bldg:Building` | `schema:Accommodation` / `schema:House` | Label + comment overlap |
+| `bldg:PostalCode` | `schema:postalCode` | Label match |
+| `bldg:HeatingSystem` | `schema:EngineSpecification` | Property overlap (fuel, type) |
+| `bldg:EnergyPerformanceCertificate` | `schema:EnergyConsumptionDetails` | Comment overlap |
+
+## Step 3: Review and Accept Candidates
+
+```text
+# Accept a good match
+onto_align_feedback --accept "bldg:Building = schema:Accommodation"
+
+# Reject a false positive
+onto_align_feedback --reject "bldg:HeatingSystem = schema:EngineSpecification"
+```
+
+Accepted/rejected feedback trains the self-calibrating confidence weights for future alignments.
+
+## Step 4: Generate Alignment Triples
+
+After reviewing candidates, use SPARQL CONSTRUCT to produce bridging triples:
+
+```sparql
+PREFIX bldg: <http://example.org/ontology/ies-building#>
+PREFIX schema: <https://schema.org/>
+PREFIX owl: <http://www.w3.org/2002/07/owl#>
+PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
+
+CONSTRUCT {
+ bldg:Building skos:closeMatch schema:Accommodation .
+ bldg:Dwelling skos:closeMatch schema:House .
+ bldg:PostalCode skos:relatedMatch schema:postalCode .
+ bldg:EnergyPerformanceCertificate skos:relatedMatch schema:EnergyConsumptionDetails .
+}
+WHERE { }
+```
+
+Use `skos:closeMatch` (not `owl:equivalentClass`) because these are cross-domain approximations, not logical equivalences. The IES 4D model has temporal states that Schema.org lacks.
+
+## NDTP Pipeline Pattern
+
+In a real NDTP pipeline, the alignment flows like this:
+
+```
+EPC CSV data
+ → onto_ingest (CSV → RDF using IES Building mapping)
+ → onto_shacl (validate against IES Building SHACL shapes)
+ → onto_reason (materialise inferred triples via OWL-RL)
+ → onto_align (map to Schema.org / BRICK / other targets)
+ → onto_push (publish to SPARQL endpoint)
+```
+
+This mirrors NDTP's actual architecture: ingest raw energy performance data, validate against IES, reason to fill gaps, then align to downstream consumer schemas.
+
+## Aligning with BRICK Schema
+
+For building management systems, [BRICK](https://brickschema.org/) is a more natural alignment target than Schema.org:
+
+```text
+# Pull BRICK ontology
+onto_pull https://brickschema.org/schema/Brick.ttl
+onto_save /tmp/brick.ttl
+onto_clear
+
+# Run alignment
+onto_align --source /tmp/ies-building.ttl --target /tmp/brick.ttl
+```
+
+Expected high-confidence matches:
+
+| IES Building | BRICK | Confidence |
+| --- | --- | --- |
+| `bldg:Building` | `brick:Building` | Very high (label + structure) |
+| `bldg:HeatingSystem` | `brick:Heating_System` | High (label + parent overlap) |
+| `bldg:WallInsulation` | `brick:Insulation` | Medium (partial label match) |
+
+This demonstrates that Open Ontologies can serve as the alignment layer in NDTP's data integration architecture — mapping between IES (the canonical model) and domain-specific schemas used by different systems.
diff --git a/docs/ies-examples.md b/docs/ies-examples.md
new file mode 100644
index 00000000..d1cd9100
--- /dev/null
+++ b/docs/ies-examples.md
@@ -0,0 +1,172 @@
+# IES SPARQL Examples
+
+The [Information Exchange Standard (IES)](https://github.com/IES-Org/ont-ies) is the UK National Digital Twin Programme's core ontology. It uses a 4D extensionalist (BORO) approach where entities have temporal states, events mark changes, and classification uses the type-instance pattern via `ClassOfEntity`.
+
+These examples assume IES has been loaded into the store:
+
+```bash
+# Via marketplace
+open-ontologies marketplace install ies
+
+# Or via direct pull
+open-ontologies pull https://raw.githubusercontent.com/IES-Org/ont-ies/main/docs/specification/ies-common.ttl
+```
+
+---
+
+## 1. Find All Person Subclasses
+
+IES models people through a hierarchy rooted at `Person`. This query finds all classes that specialise it.
+
+```sparql
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX ies: <http://informationexchangestandard.org/ont/ies/common/>
+
+SELECT ?class ?label WHERE {
+ ?class rdfs:subClassOf* ies:Person .
+ OPTIONAL { ?class rdfs:label ?label }
+ FILTER (?class != ies:Person)
+}
+ORDER BY ?label
+```
+
+**MCP usage:**
+
+```
+onto_load the IES ontology, then onto_query with the SPARQL above
+```
+
+---
+
+## 2. List All EventParticipant Relationships
+
+IES uses `EventParticipant` to link entities to events — a core 4D pattern. This query finds all properties that connect events to their participants.
+
+```sparql
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX owl: <http://www.w3.org/2002/07/owl#>
+PREFIX ies: <http://informationexchangestandard.org/ont/ies/common/>
+
+SELECT ?property ?label ?domain ?range WHERE {
+ ?property rdfs:subPropertyOf* ies:isParticipantIn .
+ OPTIONAL { ?property rdfs:label ?label }
+ OPTIONAL { ?property rdfs:domain ?domain }
+ OPTIONAL { ?property rdfs:range ?range }
+}
+ORDER BY ?label
+```
+
+---
+
+## 3. Show 4D Temporal Patterns (States and BoundingStates)
+
+The 4D extensionalist approach models change over time using `State` (a temporal part of an entity) and `BoundingState` (start/end markers). This query maps the temporal modelling pattern.
+
+```sparql
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX ies: <http://informationexchangestandard.org/ont/ies/common/>
+
+SELECT ?stateClass ?label ?parent WHERE {
+ ?stateClass rdfs:subClassOf* ies:State .
+ ?stateClass rdfs:subClassOf ?parent .
+ OPTIONAL { ?stateClass rdfs:label ?label }
+ FILTER (?stateClass != ies:State)
+}
+ORDER BY ?parent ?label
+```
+
+To find bounding states specifically (the start/end markers of temporal parts):
+
+```sparql
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX ies: <http://informationexchangestandard.org/ont/ies/common/>
+
+SELECT ?boundingState ?label WHERE {
+ ?boundingState rdfs:subClassOf* ies:BoundingState .
+ OPTIONAL { ?boundingState rdfs:label ?label }
+ FILTER (?boundingState != ies:BoundingState)
+}
+ORDER BY ?label
+```
+
+---
+
+## 4. Find All Location Subclasses and Spatial Relationships
+
+IES has a rich spatial model. This query explores the Location hierarchy and its relationships.
+
+```sparql
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX ies: <http://informationexchangestandard.org/ont/ies/common/>
+
+SELECT ?class ?label ?parent WHERE {
+ ?class rdfs:subClassOf* ies:Location .
+ ?class rdfs:subClassOf ?parent .
+ OPTIONAL { ?class rdfs:label ?label }
+ FILTER (?class != ies:Location)
+}
+ORDER BY ?parent ?label
+```
+
+To find spatial properties (inLocation, isPartOf, etc.):
+
+```sparql
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX ies: <http://informationexchangestandard.org/ont/ies/common/>
+
+SELECT ?property ?label ?domain ?range WHERE {
+ ?property rdfs:subPropertyOf* ies:inLocation .
+ OPTIONAL { ?property rdfs:label ?label }
+ OPTIONAL { ?property rdfs:domain ?domain }
+ OPTIONAL { ?property rdfs:range ?range }
+}
+ORDER BY ?label
+```
+
+---
+
+## 5. List All ClassOfEntity Instances (Type-Instance Pattern)
+
+IES uses a distinctive type-instance pattern: instead of creating subclasses for every variation, it uses `ClassOfEntity` individuals to classify entities. For example, `ClassOfBuilding` instances might include "Detached House" or "Flat" — they are data, not schema.
+
+```sparql
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX ies: <http://informationexchangestandard.org/ont/ies/common/>
+
+SELECT ?classOfClass ?label ?parent WHERE {
+ ?classOfClass rdfs:subClassOf* ies:ClassOfEntity .
+ OPTIONAL { ?classOfClass rdfs:label ?label }
+ OPTIONAL {
+ ?classOfClass rdfs:subClassOf ?parent .
+ FILTER (?parent != ies:ClassOfEntity)
+ }
+ FILTER (?classOfClass != ies:ClassOfEntity)
+}
+ORDER BY ?label
+```
+
+---
+
+## Full Workflow Example
+
+Load IES, reason over it, then explore:
+
+```text
+# Step 1: Install from marketplace
+onto_marketplace install ies
+
+# Step 2: Check what loaded
+onto_stats
+
+# Step 3: Run OWL-RL reasoning to materialise inferred triples
+onto_reason --profile owl-rl
+
+# Step 4: Check inferred triple count
+onto_stats
+
+# Step 5: Lint for completeness
+onto_lint
+
+# Step 6: Run any of the SPARQL queries above
+onto_query "SELECT (COUNT(?c) AS ?count) WHERE { ?c a <http://www.w3.org/2002/07/owl#Class> }"
+```
diff --git a/src/marketplace.rs b/src/marketplace.rs
index a5d204bb..7db59e79 100644
--- a/src/marketplace.rs
+++ b/src/marketplace.rs
@@ -10,7 +10,7 @@ pub struct MarketplaceEntry {
pub format: RdfFormat,
}
-/// Curated catalogue of 29 standard W3C/ISO/industry ontologies.
+/// Curated catalogue of 30 standard W3C/ISO/industry ontologies.
pub static CATALOGUE: &[MarketplaceEntry] = &[
// ── Foundational ──────────────────────────────────────────────
MarketplaceEntry {
@@ -38,7 +38,15 @@ pub static CATALOGUE: &[MarketplaceEntry] = &[
format: RdfFormat::Turtle,
},
- // ── Upper ontology ────────────────────────────────────────────
+ // ── Upper ontology / Information Exchange ─────────────────────
+ MarketplaceEntry {
+ id: "ies",
+ name: "IES (Information Exchange Standard)",
+ description: "UK NDTP core ontology for information exchange — 4D extensionalist (BORO) patterns for entities, events, states, and relationships",
+ domain: "upper-ontology",
+ url: "https://raw.githubusercontent.com/IES-Org/ont-ies/main/docs/specification/ies-common.ttl",
+ format: RdfFormat::Turtle,
+ },
MarketplaceEntry {
id: "bfo",
name: "BFO (Basic Formal Ontology)",