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
"""SHACL validation over the loaded graph.
Conformance is the question SHACL answers: is this data shaped the way the
model says it must be. The package owns the validation call and the report
parsing; deciding what to do about a violation is the orchestrator's job, as
everywhere else here.
Requires the optional extra: pip install "open-ontologies-lite[shacl]"
Reference: pySHACL, https://github.com/RDFLib/pySHACL
"""
from __future__ import annotations
SH = "http://www.w3.org/ns/shacl#"
def _require_pyshacl():
try:
import pyshacl # noqa: F401
return pyshacl
except ImportError as exc: # pragma: no cover - exercised by the extra being absent
raise ImportError(
"SHACL validation needs the optional extra: "
'pip install "open-ontologies-lite[shacl]"'
) from exc
def _local(term: str) -> str:
"""Strip a SHACL namespace prefix so severities read as Violation/Warning/Info."""
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] = []
# A declarative target identifies a shape without requiring rdf:type.
# This also includes property shapes (SHACL Core section 2.1).
targets = (sh.targetClass, sh.targetNode, sh.targetSubjectsOf, sh.targetObjectsOf)
shapes = {shape for target in targets for shape in shapes_graph.subjects(target, None)}
for shape in shapes:
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 _term_text(term) -> str:
"""A missing RDF term is empty; falsy literal values are still present."""
return "" if term is None else str(term)
def shacl_validate(
data: str,
shapes: str,
*,
data_format: str = "turtle",
shapes_format: str = "turtle",
inference: str | None = None,
) -> dict:
"""Validate `data` against `shapes` and return a structured report.
`inference` is passed through to pySHACL ("rdfs", "owlrl", "both" or None).
Inference is off by default: materialising entailments changes what counts
as a violation, and that should be an explicit choice rather than a silent
default.
"""
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_graph,
shacl_graph=shapes_graph,
inference=inference,
advanced=True,
# Count coverage on the same inferred graph that the validator checks.
# This graph was parsed here; the caller's store is never modified.
inplace=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):
get = lambda p: results_graph.value(result, p) # noqa: E731
severity = get(sh.resultSeverity)
violations.append(
{
"focus_node": _term_text(get(sh.focusNode)),
"path": _term_text(get(sh.resultPath)),
"value": _term_text(get(sh.value)),
"message": _term_text(get(sh.resultMessage)),
"severity": _local(str(severity)) if severity else "Violation",
"source_shape": _term_text(get(sh.sourceShape)),
"constraint": _local(_term_text(get(sh.sourceConstraintComponent))),
}
)
violations.sort(key=lambda v: (v["focus_node"], v["path"], v["constraint"]))
by_severity: dict[str, int] = {}
for v in violations:
by_severity[v["severity"]] = by_severity.get(v["severity"], 0) + 1
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 report