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
feat(python): closed-world vocabulary checking, focus-node reporting, 0.4.0
FABIOTESS8beb9cd6c228
diff --git a/python/README.md b/python/README.mdindex 7d5c9683..dcdaa89d 100644--- a/python/README.md+++ b/python/README.md@@ -116,7 +116,41 @@ Register it with any MCP client (e.g. Claude):| `onto_diff` | Triple-level diff between two ontologies || `onto_kgcl_diff` | KGCL change records between two versions (governance / change logs) || `onto_lint` | Missing labels, domains, ranges |-| `onto_shacl` | SHACL conformance: violations with focus node, path, value, severity and constraint (needs the `[shacl]` extra) |+| `onto_shacl` | SHACL conformance: violations with focus node, path, value, severity and constraint, plus `focus_nodes` and `unmatched_shapes` (needs the `[shacl]` extra) |+| `onto_vocab_check` | Closed-world check: which terms in the data are not declared in the loaded ontology |++### Closed-world checking++RDF is open-world, so a predicate nobody declared is unknown rather than wrong.+An extractor that invents `ex:hasProteinName` because it sounded plausible+produces RDF that parses, loads and satisfies SHACL without a murmur. Closing+that world is the only way to tell an invented term from a real one:++```python+from open_ontologies_lite import vocab_check++report = vocab_check(ontology_ttl, generated_data_ttl)+report["undeclared_terms"] # ['http://example.org/onto#hasProteinName']+```++Instance IRIs are never policed, because individuals belong to the data rather+than the vocabulary, and the standard vocabularies are never policed either.+With no ontology loaded the check reports that nothing was checked and returns+`conforms: False`, never `True`: a green light from an empty vocabulary is the+failure this exists to prevent.++### Validation that never passes vacuously++A shapes graph whose targets match nothing validates every constraint against+the empty set and reports `conforms: True`, byte-identical to a run where every+constraint was checked and passed. `shacl_validate` reports how many focus nodes+were actually selected and names the shapes that selected none:++```python+report["focus_nodes"] # 0+report["unmatched_shapes"] # [{'shape': '...PersonShape', 'target_class': '...Person'}]+report["conforms"] # None, because nothing was examined+```## Relationship to the Rust enginediff --git a/python/pyproject.toml b/python/pyproject.tomlindex c6daad93..a6c16e6d 100644--- a/python/pyproject.toml+++ b/python/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "open-ontologies-lite"-version = "0.3.0"+version = "0.4.0"description = "Lightweight Python bridge to the Oxigraph RDF/OWL engine, MCP server included. No Rust toolchain, no compilation."readme = "README.md"requires-python = ">=3.10"@@ -18,7 +18,7 @@ classifiers = []dependencies = ["pyoxigraph>=0.5,<0.6",- "mcp>=1.2",+ "mcp>=1.2,<2",][project.optional-dependencies]diff --git a/python/src/open_ontologies_lite/__init__.py b/python/src/open_ontologies_lite/__init__.pyindex c0fcb0ac..24977f48 100644--- a/python/src/open_ontologies_lite/__init__.py+++ b/python/src/open_ontologies_lite/__init__.py@@ -5,14 +5,16 @@ Oxigraph RDF/OWL engine. No Rust toolchain, no compilation, prebuilt wheels onlyfrom .dataframe import rows_from_dataframe, rows_to_turtlefrom .engine import OntologyEngine, ValidationResult, resolve_formatfrom .kgcl import ChangeSet, kgcl_diff+from .vocab_check import vocab_check-__version__ = "0.3.0"+__version__ = "0.4.0"__all__ = ["OntologyEngine","ValidationResult","resolve_format","ChangeSet","kgcl_diff",+ "vocab_check","rows_from_dataframe","rows_to_turtle","__version__",diff --git a/python/src/open_ontologies_lite/server.py b/python/src/open_ontologies_lite/server.pyindex 6aabf5cf..e15016a2 100644--- a/python/src/open_ontologies_lite/server.py+++ b/python/src/open_ontologies_lite/server.py@@ -120,6 +120,29 @@ def onto_shacl()+def onto_vocab_check(+ data: str, data_format: str = "turtle", extra_namespaces: list[str] | None = None+) -> dict:+ """Closed-world check: which terms in `data` are not declared in the loaded ontology.++ RDF is open-world, so an invented predicate is merely unknown and passes both+ parsing and SHACL untouched. This closes that world against the loaded+ ontology and names every undeclared term in the namespaces that ontology owns.+ Instance IRIs and the standard vocabularies are never policed.++ Returns False for `conforms`, never True, when no vocabulary is loaded.+ """+ from .vocab_check import vocab_check++ return vocab_check(+ _engine.dump(),+ data,+ data_format=data_format,+ extra_namespaces=extra_namespaces,+ )++def main() -> None:import argparsediff --git a/python/src/open_ontologies_lite/shacl.py b/python/src/open_ontologies_lite/shacl.pyindex 17cb9450..10a564d2 100644--- a/python/src/open_ontologies_lite/shacl.py+++ b/python/src/open_ontologies_lite/shacl.py@@ -32,6 +32,68 @@ def _local(term: str) -> str:return term[len(SH) :] if term.startswith(SH) else term+def _focus_nodes(data_graph, shapes_graph) -> tuple[int, list[dict]]:+ """Count the nodes each shape actually selected.++ A shapes graph whose targets match nothing validates every constraint against+ the empty set and reports conformance, which is indistinguishable from a run+ that examined the data and found it sound. Counting the selected nodes is+ what separates "checked and clean" from "checked nothing".++ Only the four declarative target predicates are counted. A shape with no+ declared target, or one using SPARQL-based `sh:target`, is not judged here:+ reporting it as unmatched would be a guess.+ """+ import rdflib++ sh = rdflib.Namespace(SH)+ rdfs = rdflib.RDFS++ total = 0+ unmatched: list[dict] = []++ for shape in set(shapes_graph.subjects(rdflib.RDF.type, sh.NodeShape)):+ selected: set = set()+ declared = False++ for target_class in shapes_graph.objects(shape, sh.targetClass):+ declared = True+ # SHACL selects SHACL-instances, so instances of subclasses count.+ selected.update(data_graph.subjects(rdflib.RDF.type, target_class))+ for sub in data_graph.transitive_subjects(rdfs.subClassOf, target_class):+ selected.update(data_graph.subjects(rdflib.RDF.type, sub))++ for node in shapes_graph.objects(shape, sh.targetNode):+ declared = True+ selected.add(node)++ for prop in shapes_graph.objects(shape, sh.targetSubjectsOf):+ declared = True+ selected.update(data_graph.subjects(prop, None))++ for prop in shapes_graph.objects(shape, sh.targetObjectsOf):+ declared = True+ selected.update(data_graph.objects(None, prop))++ if not declared:+ continue++ total += len(selected)+ if not selected:+ unmatched.append(+ {+ "shape": str(shape),+ "target_class": next(+ (str(t) for t in shapes_graph.objects(shape, sh.targetClass)),+ "",+ ),+ }+ )++ unmatched.sort(key=lambda u: (u["target_class"], u["shape"]))+ return total, unmatched++def shacl_validate(data: str,shapes: str,@@ -50,15 +112,18 @@ def shacl_validate(pyshacl = _require_pyshacl()import rdflib+ data_graph = rdflib.Graph().parse(data=data, format=data_format)+ shapes_graph = rdflib.Graph().parse(data=shapes, format=shapes_format)+conforms, results_graph, results_text = pyshacl.validate(- data,- shacl_graph=shapes,- data_graph_format=data_format,- shacl_graph_format=shapes_format,+ data_graph,+ shacl_graph=shapes_graph,inference=inference,advanced=True,)+ focus_nodes, unmatched_shapes = _focus_nodes(data_graph, shapes_graph)+sh = rdflib.Namespace(SH)violations: list[dict] = []for result in results_graph.subjects(rdflib.RDF.type, sh.ValidationResult):@@ -81,10 +146,25 @@ def shacl_validate(for v in violations:by_severity[v["severity"]] = by_severity.get(v["severity"], 0) + 1- return {+ report = {"conforms": bool(conforms),"count": len(violations),"by_severity": by_severity,"violations": violations,+ "focus_nodes": focus_nodes,+ "unmatched_shapes": unmatched_shapes,"text": results_text,}++ # Every shape that declared a target selected nothing, so no constraint was+ # applied to anything. Reporting conformance here would be the same lie as+ # reporting it for a constraint that never ran.+ if focus_nodes == 0 and unmatched_shapes:+ report["conforms"] = None+ report["warning"] = (+ f"no focus node was selected: all {len(unmatched_shapes)} targeted shape(s) "+ "match nothing in the data, so conformance is undetermined. "+ "See unmatched_shapes."+ )++ return reportdiff --git a/python/src/open_ontologies_lite/vocab_check.py b/python/src/open_ontologies_lite/vocab_check.pynew file mode 100644index 00000000..d6f74c70--- /dev/null+++ b/python/src/open_ontologies_lite/vocab_check.py@@ -0,0 +1,148 @@+"""Closed-world vocabulary checking against a declared ontology.++RDF is open-world: an IRI nobody declared is unknown, not wrong. That is the+right default for the web and the wrong one for checking a generated graph,+because an extractor that invents `ex:hasProteinName` because it sounded+plausible produces RDF that parses, loads and satisfies SHACL without complaint.+Nothing in the standard toolchain objects.++This module closes that world deliberately. It reads the vocabulary an ontology+declares, works out which namespaces that ontology owns, and reports every term+used in the data that sits in one of those namespaces without being declared.++Two rules keep it honest. Instance IRIs are never policed, because individuals+belong to the data rather than the vocabulary. And a check with no vocabulary+loaded never returns a pass, because a green light from an empty ontology is the+exact failure this exists to prevent.++Runs on pyoxigraph, the same engine as everything else here, so it needs no+dependency beyond the base install and answers as the Rust engine's+`vocab_check` does.+"""++from __future__ import annotations++import pyoxigraph as ox++from .engine import resolve_format++OWL = "http://www.w3.org/2002/07/owl#"+RDF = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"+RDFS = "http://www.w3.org/2000/01/rdf-schema#"++#: Vocabularies every graph is entitled to use without declaring them.+STD_NS = (+ RDF,+ RDFS,+ OWL,+ "http://www.w3.org/2001/XMLSchema#",+ "http://www.w3.org/ns/shacl#",+ "http://www.w3.org/2004/02/skos/core#",+)++_CLASS_OR_PROPERTY = f"""FILTER(+ ?k = <{OWL}Class>+ || ?k = <{RDFS}Class>+ || ?k = <{OWL}ObjectProperty>+ || ?k = <{OWL}DatatypeProperty>+ || ?k = <{OWL}AnnotationProperty>+ || ?k = <{OWL}FunctionalProperty>+ || ?k = <{OWL}InverseFunctionalProperty>+ || ?k = <{RDF}Property>)"""++# An ontology that gives an IRI a domain or a range has declared it in substance,+# even without typing it, so those axioms count as declarations too.+_DEFINING_AXIOM = f"""FILTER(+ ?p = <{RDFS}domain>+ || ?p = <{RDFS}range>+ || ?p = <{RDFS}subClassOf>+ || ?p = <{RDFS}subPropertyOf>)"""+++def _namespace_of(iri: str) -> str:+ """Everything up to and including the last `#` or `/`."""+ cut = max(iri.rfind("#"), iri.rfind("/"))+ return iri[: cut + 1] if cut >= 0 else iri+++def _store_from(text: str, fmt: str) -> ox.Store:+ store = ox.Store()+ if text.strip():+ store.load(text.encode("utf-8"), format=resolve_format(fmt))+ return store+++def _iris(store: ox.Store, sparql: str, var: str) -> set[str]:+ """Collect the IRI bindings of one variable; literals and blanks are skipped."""+ out: set[str] = set()+ for solution in store.query(sparql):+ term = solution[var]+ if isinstance(term, ox.NamedNode):+ out.add(term.value)+ return out+++def vocab_check(+ ontology: str,+ data: str,+ *,+ ontology_format: str = "turtle",+ data_format: str = "turtle",+ extra_namespaces: list[str] | None = None,+) -> dict:+ """Check `data` against the vocabulary `ontology` declares.++ `extra_namespaces` polices namespaces the ontology does not own, which is how+ you check data against a vocabulary you have not loaded.++ Returns a report with `conforms`, `undeclared_terms`, the namespaces policed,+ and the counts behind the verdict. `conforms` is False, never True, when+ there was no vocabulary to check against.+ """+ onto_store = _store_from(ontology, ontology_format)+ data_store = _store_from(data, data_format)++ declared = _iris(+ onto_store, f"SELECT DISTINCT ?t WHERE {{ ?t a ?k . {_CLASS_OR_PROPERTY} }}", "t"+ ) | _iris(+ onto_store, f"SELECT DISTINCT ?t WHERE {{ ?t ?p ?o . {_DEFINING_AXIOM} }}", "t"+ )++ extra = list(extra_namespaces or [])++ # A closed-world check with nothing to close over must never silently pass.+ if not declared and not extra:+ return {+ "conforms": False,+ "undeclared_terms": [],+ "checked_namespaces": [],+ "predicates_checked": 0,+ "types_checked": 0,+ "ontology_terms": 0,+ "warning": (+ "no ontology vocabulary found (0 declared terms): load an ontology, "+ "or pass extra_namespaces to police; nothing was checked"+ ),+ }++ policed = {_namespace_of(term) for term in declared}+ policed.update(extra)+ policed.difference_update(STD_NS)++ predicates = _iris(data_store, "SELECT DISTINCT ?p WHERE { ?s ?p ?o }", "p")+ types = _iris(data_store, "SELECT DISTINCT ?c WHERE { ?s a ?c }", "c")++ undeclared = sorted(+ iri+ for iri in predicates | types+ if _namespace_of(iri) in policed and iri not in declared+ )++ return {+ "conforms": not undeclared,+ "undeclared_terms": undeclared,+ "checked_namespaces": sorted(policed),+ "predicates_checked": len(predicates),+ "types_checked": len(types),+ "ontology_terms": len(declared),+ }diff --git a/python/tests/test_shacl_vacuous.py b/python/tests/test_shacl_vacuous.pynew file mode 100644index 00000000..3414b3cc--- /dev/null+++ b/python/tests/test_shacl_vacuous.py@@ -0,0 +1,127 @@+"""Vacuous conformance: shapes that selected no focus nodes.++pySHACL answers `conforms: True` for a shapes graph whose targets match nothing,+with no indication that nothing was examined. That report is byte-identical to+one where every constraint ran and passed, so a pipeline gating on `conforms`+publishes unvalidated data on a green light.++The Rust engine reports `focus_nodes` and `unmatched_shapes` and withholds the+verdict when nothing matched. These tests hold the Python package to the same+contract, so the two surfaces cannot disagree about what a validation run means.+"""++import pytest++pytest.importorskip("pyshacl", reason="needs the [shacl] extra")++from open_ontologies_lite.shacl import shacl_validate # noqa: E402++# Shapes in one namespace, data in another: the mismatch that makes generated+# shapes target nothing while every report still reads clean.+SHAPES_OTHER_NAMESPACE = """+@prefix sh: <http://www.w3.org/ns/shacl#> .+@prefix ex: <http://example.org/shapes/> .+ex:PersonShape a sh:NodeShape ;+ sh:targetClass ex:Person ;+ sh:property [ sh:path ex:name ; sh:minCount 1 ] .+"""++SHAPES_SAME_NAMESPACE = """+@prefix sh: <http://www.w3.org/ns/shacl#> .+@prefix ex: <http://example.org/> .+ex:PersonShape a sh:NodeShape ;+ sh:targetClass ex:Person ;+ sh:property [ sh:path ex:name ; sh:minCount 1 ] .+"""++DATA = """+@prefix ex: <http://example.org/> .+ex:ada a ex:Person ; ex:name "Ada" .+"""++DATA_MISSING_NAME = """+@prefix ex: <http://example.org/> .+ex:ada a ex:Person .+"""+++def test_shapes_that_select_nothing_are_named():+ report = shacl_validate(DATA, SHAPES_OTHER_NAMESPACE)++ assert report["focus_nodes"] == 0+ assert [u["target_class"] for u in report["unmatched_shapes"]] == [+ "http://example.org/shapes/Person"+ ]+++def test_a_run_that_selected_nothing_withholds_the_verdict():+ report = shacl_validate(DATA_MISSING_NAME, SHAPES_OTHER_NAMESPACE)++ assert report["conforms"] is None, "nothing was checked, so there is no verdict"+ assert "focus node" in report["warning"]+++def test_an_ordinary_passing_run_still_conforms():+ report = shacl_validate(DATA, SHAPES_SAME_NAMESPACE)++ assert report["conforms"] is True+ assert report["focus_nodes"] == 1+ assert report["unmatched_shapes"] == []+++def test_a_failing_run_is_unaffected():+ report = shacl_validate(DATA_MISSING_NAME, SHAPES_SAME_NAMESPACE)++ assert report["conforms"] is False+ assert report["focus_nodes"] == 1+ assert report["count"] == 1+++def test_subclass_instances_count_as_focus_nodes():+ """SHACL selects SHACL-instances, so a subclass instance is a focus node."""+ data = """+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .+ @prefix ex: <http://example.org/> .+ ex:Employee rdfs:subClassOf ex:Person .+ ex:ada a ex:Employee ; ex:name "Ada" .+ """+ report = shacl_validate(data, SHAPES_SAME_NAMESPACE)++ assert report["focus_nodes"] == 1+ assert report["unmatched_shapes"] == []+++def test_target_predicates_other_than_class_are_counted():+ shapes = """+ @prefix sh: <http://www.w3.org/ns/shacl#> .+ @prefix ex: <http://example.org/> .+ ex:AuthoredShape a sh:NodeShape ;+ sh:targetSubjectsOf ex:wrote ;+ sh:property [ sh:path ex:name ; sh:minCount 1 ] .+ """+ data = """+ @prefix ex: <http://example.org/> .+ ex:ada ex:wrote ex:notes ; ex:name "Ada" .+ """+ report = shacl_validate(data, shapes)++ assert report["focus_nodes"] == 1+ assert report["unmatched_shapes"] == []+ assert report["conforms"] is True+++def test_a_shape_with_no_declared_target_is_not_called_unmatched():+ """Property shapes and advanced targets are not judged, only reported honestly."""+ shapes = """+ @prefix sh: <http://www.w3.org/ns/shacl#> .+ @prefix ex: <http://example.org/> .+ ex:Floating a sh:NodeShape ;+ sh:property [ sh:path ex:name ; sh:minCount 1 ] .+ ex:PersonShape a sh:NodeShape ;+ sh:targetClass ex:Person ;+ sh:property [ sh:path ex:name ; sh:minCount 1 ] .+ """+ report = shacl_validate(DATA, shapes)++ assert report["unmatched_shapes"] == []+ assert report["focus_nodes"] == 1diff --git a/python/tests/test_vocab_check.py b/python/tests/test_vocab_check.pynew file mode 100644index 00000000..635d7a58--- /dev/null+++ b/python/tests/test_vocab_check.py@@ -0,0 +1,121 @@+"""Closed-world vocabulary checking.++In the open world an undeclared IRI is unknown, not wrong, so an extractor that+invents `ex:hasProteinName` produces RDF that parses, loads and passes SHACL+without complaint. Closed-world checking is the only thing that separates a real+term from a plausible-looking one, and it is the check that has no equivalent+elsewhere in the Python RDF stack.++Mirrors the semantics of the Rust engine's `vocab_check`: police the namespaces+the ontology itself declares terms in, never instance IRIs, never the standard+vocabularies, and refuse to return a pass when there is no vocabulary to check+against.+"""++import pytest++pytest.importorskip("pyoxigraph")++from open_ontologies_lite.vocab_check import vocab_check # noqa: E402++ONTOLOGY = """+@prefix owl: <http://www.w3.org/2002/07/owl#> .+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .+@prefix ex: <http://example.org/onto#> .++ex:Person a owl:Class .+ex:Protein a owl:Class .+ex:hasName a owl:DatatypeProperty ; rdfs:domain ex:Person .+"""++CLEAN_DATA = """+@prefix ex: <http://example.org/onto#> .+<http://example.org/instances/ada> a ex:Person ; ex:hasName "Ada" .+"""++INVENTED_TERM = """+@prefix ex: <http://example.org/onto#> .+<http://example.org/instances/ada> a ex:Person ; ex:hasProteinName "Ada" .+"""+++def test_clean_data_conforms():+ report = vocab_check(ONTOLOGY, CLEAN_DATA)++ assert report["conforms"] is True+ assert report["undeclared_terms"] == []+ assert report["ontology_terms"] == 3+++def test_an_invented_predicate_is_flagged():+ report = vocab_check(ONTOLOGY, INVENTED_TERM)++ assert report["conforms"] is False+ assert report["undeclared_terms"] == ["http://example.org/onto#hasProteinName"]+++def test_instance_iris_are_not_policed():+ """Individuals live in the data, not the vocabulary; flagging them is noise."""+ data = """+ @prefix ex: <http://example.org/onto#> .+ <http://example.org/onto#ada> a ex:Person ; ex:hasName "Ada" .+ """+ report = vocab_check(ONTOLOGY, data)++ assert report["conforms"] is True, report["undeclared_terms"]+++def test_terms_outside_the_policed_namespaces_are_left_alone():+ data = """+ @prefix ex: <http://example.org/onto#> .+ @prefix dct: <http://purl.org/dc/terms/> .+ <http://example.org/instances/ada> a ex:Person ; dct:title "Ada" .+ """+ report = vocab_check(ONTOLOGY, data)++ assert report["conforms"] is True+ assert "http://purl.org/dc/terms/" not in report["checked_namespaces"]+++def test_standard_vocabularies_are_never_policed():+ data = """+ @prefix ex: <http://example.org/onto#> .+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .+ <http://example.org/instances/ada> a ex:Person ; rdfs:label "Ada" .+ """+ report = vocab_check(ONTOLOGY, data)++ assert report["conforms"] is True+++def test_no_vocabulary_never_returns_a_pass():+ """The footgun this check exists to kill: a green light from an empty ontology."""+ report = vocab_check("", CLEAN_DATA)++ assert report["conforms"] is False+ assert "nothing was checked" in report["warning"]+ assert report["ontology_terms"] == 0+++def test_extra_namespaces_can_be_policed_explicitly():+ report = vocab_check(+ "", INVENTED_TERM, extra_namespaces=["http://example.org/onto#"]+ )++ assert report["conforms"] is False+ assert "http://example.org/onto#hasProteinName" in report["undeclared_terms"]+++def test_a_term_carrying_only_a_domain_axiom_counts_as_declared():+ ontology = """+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .+ @prefix ex: <http://example.org/onto#> .+ ex:hasName rdfs:domain ex:Person .+ """+ data = """+ @prefix ex: <http://example.org/onto#> .+ <http://example.org/instances/ada> ex:hasName "Ada" .+ """+ report = vocab_check(ontology, data)++ assert report["conforms"] is True