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.

fix(drift): canonicalise blank nodes via RDFC 1.0 (succeeds PR #14)

FABIOTESS2e329eea8ea0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b968570..ceb961f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,9 @@ All notable changes to Open Ontologies are documented here.
## [Unreleased]
+### Fixed
+- **`onto_drift` now canonicalises blank nodes via RDFC 1.0 instead of filtering them out.** Replaces the temporary `_:`-prefix filter shipped in PR #14 (Jason Smith / @rustforrecess, who originally diagnosed the bnode-instability bug and shipped the surgical fix that bought time for this proper successor). New method `GraphStore::canonicalize_blank_nodes()` uses W3C RDF Dataset Canonicalization 1.0 (SHA-256) — available built-in via Oxigraph 0.5.8 — to assign deterministic `_:c14n<n>` identifiers derived from the graph structure. `DriftDetector::detect()` canonicalises each snapshot before vocabulary extraction, so reparses of the same ontology produce identical canonical bnode IDs (the reparse-stability property PR #14 achieved by exclusion), but anonymous restriction classes / quoted axioms now PARTICIPATE in the diff with stable IDs rather than being dropped. Caveat: canonical IDs are a function of the whole graph, so a quad change can shift many bnode IDs — for typical edits the existing rename-pairing logic in `detect()` re-matches shifted bnodes via the 4-signal ensemble (label / domain-range / hierarchy / individuals), so the net result is more informative than PR #14's filter. `tests/drift_blank_node_test.rs` updated to assert the new canonical-stability contract; new test `canonical_bnode_ids_are_stable_across_independent_reparses` exercises the contract directly on two restriction shapes.
+
### Changed
- **Oxigraph dependency bumped from 0.4 → 0.5.8** (#15). Oxigraph 0.5 ships RDF 1.2 / SPARQL 1.2 support (behind `rdf-12` / `sparql-12` feature flags), a new `SparqlEvaluator` builder-based query API, JSON-LD 1.1 by default, GeoSPARQL functions, a built-in `/sparql` HTTP server, single-pass ORDER BY, and — most relevant here — **built-in RDFC 1.0 canonicalisation** (W3C Recommendation, 21 May 2024), which gives deterministic blank-node identifiers via SHA-256 over canonical N-Quads. RDFC 1.0 is the proper successor to the bnode-filter hotfix in PR #14: a follow-up release can replace the `_:`-prefix filter in `extract_vocabulary` with canonicalisation, keeping semantic content while solving the reparse-instability problem at its root. The 0.4 → 0.5 migration was back-compatible for this codebase (the auto-migrating on-disk format means existing databases load without intervention). All six `Store::query` call sites in `graph.rs`, `shacl.rs`, and `ontology.rs` have been ported to the non-deprecated `SparqlEvaluator::new().parse_query(...).on_store(&store).execute()` chain; no deprecation warnings remain on the lib build. Full test suite (~290 tests) green on 0.5.8.
diff --git a/src/drift.rs b/src/drift.rs
index ed51f0a3..ee318250 100644
--- a/src/drift.rs
+++ b/src/drift.rs
@@ -14,11 +14,21 @@ impl DriftDetector {
}
/// Detect drift between two Turtle strings.
+ ///
+ /// Each snapshot is canonicalised via RDFC 1.0 (W3C Recommendation, 21 May 2024,
+ /// SHA-256) before vocabulary extraction. The earlier per-callsite "filter `_:`
+ /// IRIs out of SPARQL results" (PR #14, @rustforrecess) protected the rename
+ /// detector from spurious bnode noise on reparse — canonicalisation preserves the
+ /// same protection (identical graphs reparse to identical canonical IDs) while
+ /// keeping anonymous restriction classes / quoted axioms visible in the diff
+ /// instead of dropping them entirely.
pub fn detect(&self, v1_turtle: &str, v2_turtle: &str) -> anyhow::Result<String> {
- let store1 = Arc::new(GraphStore::new());
- let store2 = Arc::new(GraphStore::new());
- store1.load_turtle(v1_turtle, None)?;
- store2.load_turtle(v2_turtle, None)?;
+ let raw1 = GraphStore::new();
+ let raw2 = GraphStore::new();
+ raw1.load_turtle(v1_turtle, None)?;
+ raw2.load_turtle(v2_turtle, None)?;
+ let store1 = Arc::new(raw1.canonicalize_blank_nodes()?);
+ let store2 = Arc::new(raw2.canonicalize_blank_nodes()?);
let v1_vocab = self.extract_vocabulary(&store1);
let v2_vocab = self.extract_vocabulary(&store2);
@@ -184,15 +194,15 @@ impl DriftDetector {
fn extract_vocabulary(&self, store: &GraphStore) -> HashMap<String, VocabEntry> {
let mut vocab = HashMap::new();
- // Drop blank nodes — they're anonymous restriction classes etc.
- // and get fresh IDs on every reparse, so they generate spurious
- // add/remove/rename noise between two snapshots of the same file.
- let is_named = |iri: &str| !iri.starts_with("_:");
+ // Blank nodes are canonicalised upstream in `detect()` via RDFC 1.0, so
+ // they carry deterministic `_:c14n<n>` identifiers stable across reparses.
+ // They participate in the vocab diff like any other node — the previous
+ // `_:`-prefix filter (PR #14) is no longer needed.
// Classes
let class_query = "SELECT DISTINCT ?c WHERE { ?c a <http://www.w3.org/2002/07/owl#Class> }";
if let Ok(json) = store.sparql_select(class_query) {
- for iri in parse_iris(&json, "c").into_iter().filter(|i| is_named(i)) {
+ for iri in parse_iris(&json, "c") {
vocab.entry(iri.clone()).or_insert_with(|| VocabEntry {
iri,
kind: "class".to_string(),
@@ -209,7 +219,7 @@ impl DriftDetector {
{ ?p a <http://www.w3.org/2002/07/owl#DatatypeProperty> } \
}";
if let Ok(json) = store.sparql_select(prop_query) {
- for iri in parse_iris(&json, "p").into_iter().filter(|i| is_named(i)) {
+ for iri in parse_iris(&json, "p") {
vocab.entry(iri.clone()).or_insert_with(|| VocabEntry {
iri,
kind: "property".to_string(),
diff --git a/src/graph.rs b/src/graph.rs
index 2a6342bc..76309745 100644
--- a/src/graph.rs
+++ b/src/graph.rs
@@ -163,6 +163,51 @@ impl GraphStore {
Ok(after.saturating_sub(before))
}
+ /// Canonicalise the store's blank nodes via RDFC 1.0 (W3C Recommendation,
+ /// 21 May 2024) using SHA-256, returning a NEW `GraphStore` whose blank
+ /// nodes have deterministic `_:c14n<n>` identifiers derived from the graph
+ /// structure.
+ ///
+ /// This is the principled successor to per-callsite "filter `_:` IRIs out
+ /// of the SPARQL result set" — for any operation that depends on stable
+ /// identity across reparses (drift detection, hashing, signature
+ /// comparison), canonicalisation preserves the semantic content of
+ /// anonymous restriction classes / quoted axioms instead of dropping them.
+ ///
+ /// **Warning:** per the W3C spec, canonical IDs are a function of the
+ /// whole graph. Mutating one quad can shift many bnode IDs, so this
+ /// is poorly suited to producing minimal-diff outputs over arbitrary
+ /// edits. For drift detection specifically, the existing rename-pairing
+ /// logic in `drift.rs::detect()` will re-match shifted IDs via the
+ /// label/domain/range/hierarchy/individual signal ensemble, so the
+ /// net result is more informative than the previous "filter and forget"
+ /// approach (PR #14, @rustforrecess) that dropped bnode content entirely.
+ pub fn canonicalize_blank_nodes(&self) -> anyhow::Result<GraphStore> {
+ use oxigraph::model::dataset::{CanonicalizationAlgorithm, CanonicalizationHashAlgorithm};
+ use oxigraph::model::Dataset;
+
+ let store = self.store.lock().unwrap();
+ let mut dataset = Dataset::new();
+ for quad in store.iter() {
+ let q = quad?;
+ dataset.insert(&q);
+ }
+ drop(store);
+
+ dataset.canonicalize(CanonicalizationAlgorithm::Rdfc10 {
+ hash_algorithm: CanonicalizationHashAlgorithm::Sha256,
+ });
+
+ let new_gs = GraphStore::new();
+ {
+ let new_store = new_gs.store.lock().unwrap();
+ for quad in dataset.iter() {
+ new_store.insert(quad)?;
+ }
+ }
+ Ok(new_gs)
+ }
+
pub fn serialize(&self, format: &str) -> anyhow::Result<String> {
let store = self.store.lock().unwrap();
let rdf_format = Self::parse_format(format)?;
diff --git a/tests/drift_blank_node_test.rs b/tests/drift_blank_node_test.rs
index 78ba3bf1..cb614a7f 100644
--- a/tests/drift_blank_node_test.rs
+++ b/tests/drift_blank_node_test.rs
@@ -52,7 +52,16 @@ fn drift_of_same_ontology_with_restrictions_returns_no_changes() {
}
#[test]
-fn drift_vocabulary_excludes_blank_node_iris() {
+fn real_named_change_detected_alongside_canonicalised_bnodes() {
+ // Original spirit of this test (PR #14 era): assert that bnode IRIs don't
+ // pollute the named-vocabulary diff. Under RDFC 1.0 canonicalisation we
+ // ALLOW bnodes in the diff — they carry deterministic `_:c14n<n>` IDs and
+ // represent real semantic content (anonymous restriction classes). The
+ // assertion is now twofold:
+ //
+ // 1. Any bnode IRIs that DO appear use the canonical `_:c14n` prefix
+ // (proving canonicalisation ran), NOT raw parser-generated IDs.
+ // 2. The named class rename is still detected.
let db = setup();
let detector = DriftDetector::new(db);
@@ -83,10 +92,14 @@ fn drift_vocabulary_excludes_blank_node_iris() {
.chain(parsed["removed"].as_array().unwrap().iter())
{
let s = iri.as_str().unwrap();
- assert!(
- !s.starts_with("_:"),
- "drift report leaked a blank-node IRI into named-vocabulary diff: {}", s
- );
+ if s.starts_with("_:") {
+ assert!(
+ s.starts_with("_:c14n"),
+ "blank-node IRI in diff lacks the canonical `_:c14n` prefix — \
+ canonicalisation may not have run on this snapshot: {}",
+ s
+ );
+ }
}
assert!(
@@ -100,3 +113,40 @@ fn drift_vocabulary_excludes_blank_node_iris() {
"real addition (VeggiePizza) should still be detected"
);
}
+
+#[test]
+fn canonical_bnode_ids_are_stable_across_independent_reparses() {
+ // The reparse-stability guarantee that PR #14's filter approximated by
+ // exclusion. Under canonicalisation we get the same property AND keep
+ // bnode content: two independent loads of the same Turtle string canonicalise
+ // to the same `_:c14n<n>` identifiers, so `detect(x, x)` produces zero noise.
+ let db = setup();
+ let detector = DriftDetector::new(db);
+
+ // Two structurally distinct ontologies (a wider variety of restriction
+ // shapes), each reparsed twice and diffed against itself.
+ for ttl in &[PIZZA_WITH_RESTRICTION, r#"
+ @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ @prefix ex: <http://example.org/> .
+ ex:Vehicle a owl:Class .
+ ex:Engine a owl:Class .
+ ex:hasEngine a owl:ObjectProperty .
+ ex:MotorisedVehicle a owl:Class ;
+ owl:equivalentClass [
+ a owl:Class ;
+ owl:intersectionOf (
+ ex:Vehicle
+ [ a owl:Restriction ;
+ owl:onProperty ex:hasEngine ;
+ owl:minCardinality 1 ]
+ )
+ ] .
+ "#] {
+ let report = detector.detect(ttl, ttl).expect("detect");
+ let parsed: serde_json::Value = serde_json::from_str(&report).unwrap();
+ assert!(parsed["added"].as_array().unwrap().is_empty());
+ assert!(parsed["removed"].as_array().unwrap().is_empty());
+ assert!(parsed["likely_renames"].as_array().unwrap().is_empty());
+ assert!(parsed["drift_velocity"].as_f64().unwrap() < 0.01);
+ }
+}