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(shacl): validate reads every graph, not only the default one (#126)

Fabio Rovaidbefd203fe38
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 03f3bde4..15c57a87 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,22 @@ All notable changes to Open Ontologies are documented here.
## [Unreleased]
### Fixed
+- **`onto_shacl` validated the default graph and nothing else, so whether data
+ was checked at all depended on the serialisation it arrived in.** Every
+ data-side query ran through the store's default dataset specification, which
+ is the default graph alone, so an ontology and its instances loaded from
+ Turtle validated while the identical triples loaded from TriG or N-Quads
+ selected no focus nodes: `focus_nodes: 0`, `unmatched_shapes` populated, and
+ the `nothing_matched` null verdict. That is a truthful answer to a question
+ nobody asked, which is why it never arrived as a bug report. The data-side
+ queries now read the union of every graph in the store, added as
+ `GraphStore::sparql_select_union` so the plain `sparql_select` keeps the
+ dataset a hand-written query expects. `GRAPH ?g` still ranges over the named
+ graphs, so nothing written against the old form changes meaning.
+ **This can turn a null or a vacuous pass into a real `conforms: false`**,
+ which is the point: the violations were always there and were not being
+ looked at. Reports now carry `scope`, today always `all_graphs`, so a verdict
+ says what it selected over before temporal scoping makes that vary (#108).
- **A constraint asserted on the node shape itself was never evaluated and
never reported, so `sh:closed true` over data carrying an undeclared
predicate returned `conforms: true`.** The check that routes unimplemented
diff --git a/src/graph.rs b/src/graph.rs
index 34189702..0493c276 100644
--- a/src/graph.rs
+++ b/src/graph.rs
@@ -232,12 +232,37 @@ impl GraphStore {
}
pub fn sparql_select(&self, query: &str) -> anyhow::Result<String> {
+ self.select_with_dataset(query, false)
+ }
+
+ /// Run a SELECT whose default graph is the union of every graph in the
+ /// store, named graphs included.
+ ///
+ /// The plain `sparql_select` leaves the evaluator on its default dataset
+ /// specification, which is the store's default graph alone. That is the
+ /// right dataset for a query someone wrote, since a caller who wants a
+ /// named graph writes `GRAPH`. It is the wrong one for a tool that asks a
+ /// question about the store rather than about a graph, because the answer
+ /// then depends on which serialisation the data arrived in: the same
+ /// triples loaded from Turtle are visible and loaded from TriG are not.
+ ///
+ /// `GRAPH ?g` still ranges over the named graphs here, so a query written
+ /// against the plain form keeps its meaning under this one.
+ pub fn sparql_select_union(&self, query: &str) -> anyhow::Result<String> {
+ self.select_with_dataset(query, true)
+ }
+
+ fn select_with_dataset(
+ &self,
+ query: &str,
+ union_default_graph: bool,
+ ) -> anyhow::Result<String> {
let store = self.store.lock().unwrap();
- match SparqlEvaluator::new()
- .parse_query(query)?
- .on_store(&store)
- .execute()?
- {
+ let mut prepared = SparqlEvaluator::new().parse_query(query)?;
+ if union_default_graph {
+ prepared.dataset_mut().set_default_graph_as_union();
+ }
+ match prepared.on_store(&store).execute()? {
QueryResults::Solutions(solutions) => {
let vars: Vec<String> = solutions
.variables()
diff --git a/src/shacl.rs b/src/shacl.rs
index 588d7212..a70cc917 100644
--- a/src/shacl.rs
+++ b/src/shacl.rs
@@ -686,6 +686,14 @@ impl ShaclValidator {
"violations": violations,
"focus_nodes": focus_nodes_total,
"unmatched_shapes": unmatched,
+ // A verdict that does not say what it selected over cannot be
+ // replayed or compared against the next one, and this value is
+ // about to stop being the only one: temporal scoping arrives as
+ // an argument, and the moment two runs of the same shapes over
+ // the same store can differ, an unlabelled report is a number
+ // without units. Naming it now means the key does not appear for
+ // the first time on the run where it matters.
+ "scope": "all_graphs",
});
if nothing_matched && skipped.is_empty() {
// Every shape targeted a class with no instances in the data, so
@@ -920,11 +928,29 @@ fn query_solutions(
/// Run a SPARQL SELECT against the main `GraphStore` and return results
/// as a vec of maps, using the existing `sparql_select` JSON output.
+///
+/// Every data-side query in this module runs over the union of every graph in
+/// the store. It used to run over the store's default graph alone, which made
+/// the verdict depend on the serialisation the data arrived in: an ontology
+/// and its instances loaded from Turtle validated, and the identical triples
+/// loaded from TriG selected no focus nodes at all and came back as
+/// `nothing_matched` with a null verdict. That is the right answer to a
+/// question nobody asked, and it is why the defect never arrived as a bug
+/// report.
+///
+/// Reading every graph is the only default that cannot silently drop data.
+/// The alternative, selecting instances from the graphs in temporal scope, is
+/// the opposite direction: it can only remove focus nodes, so it can turn a
+/// `conforms: false` into a `true` by dropping the data that failed. That
+/// belongs behind an argument someone passes on purpose, never behind the
+/// no-argument path. See the graph-scope rule on issue #108: a declaration is
+/// read from every graph because a declaration is context-free, and instance
+/// data is scoped because it is not.
fn graph_sparql_select(
graph: &Arc<GraphStore>,
query: &str,
) -> anyhow::Result<Vec<HashMap<String, String>>> {
- let json_str = graph.sparql_select(query)?;
+ let json_str = graph.sparql_select_union(query)?;
let parsed: serde_json::Value = serde_json::from_str(&json_str)?;
let mut rows = Vec::new();
if let Some(results) = parsed["results"].as_array() {
diff --git a/tests/shacl_test.rs b/tests/shacl_test.rs
index e492e023..d0e39872 100644
--- a/tests/shacl_test.rs
+++ b/tests/shacl_test.rs
@@ -1,5 +1,6 @@
use open_ontologies::graph::GraphStore;
use open_ontologies::shacl::ShaclValidator;
+use oxigraph::io::RdfFormat;
use std::sync::Arc;
fn make_store_with_data() -> Arc<GraphStore> {
@@ -737,3 +738,112 @@ fn test_a_true_control_is_still_skipped_beside_a_false_one() {
"sh:deactivated false was honoured and must not be recorded: {v}"
);
}
+
+fn store_from_trig(dataset: &str) -> Arc<GraphStore> {
+ let store = Arc::new(GraphStore::new());
+ store
+ .load_content(dataset, RdfFormat::TriG)
+ .expect("load TriG");
+ store
+}
+
+const ONE_SHAPE: &str = r#"
+ @prefix sh: <http://www.w3.org/ns/shacl#> .
+ @prefix ex: <http://example.org/> .
+ ex:S a sh:NodeShape ; sh:targetClass ex:Thing ;
+ sh:property [ sh:path ex:p ; sh:minCount 1 ] .
+"#;
+
+#[test]
+fn test_instance_data_in_a_named_graph_is_validated() {
+ // Every data-side query ran over the store's default graph alone, so the
+ // verdict depended on the serialisation the data arrived in. The same
+ // triples in Turtle validated and in TriG selected no focus nodes at all,
+ // and the report said `nothing_matched` with a null verdict: the right
+ // answer to a question nobody asked, which is why this never arrived as a
+ // bug report. Reverting `sparql_select_union` to `sparql_select` reddens
+ // this test.
+ let store = store_from_trig(
+ r#"
+ @prefix ex: <http://example.org/> .
+ ex:data { ex:a a ex:Thing . }
+ "#,
+ );
+ let report = ShaclValidator::validate(&store, ONE_SHAPE).unwrap();
+ let v: serde_json::Value = serde_json::from_str(&report).unwrap();
+ assert_eq!(v["focus_nodes"], 1, "the instance must be selected: {v}");
+ assert_eq!(
+ v["conforms"],
+ serde_json::Value::Bool(false),
+ "ex:a has no ex:p, so this is a violation and not an absence: {v}"
+ );
+ assert_eq!(v["violation_count"], 1, "report: {v}");
+ assert!(
+ v["unmatched_shapes"]
+ .as_array()
+ .is_some_and(|a| a.is_empty()),
+ "the shape matched, so it is not unmatched: {v}"
+ );
+}
+
+#[test]
+fn test_data_split_across_graphs_is_one_dataset_and_not_many() {
+ // The union is the RDF merge of every graph read as one default graph, not
+ // the same query run once per graph. A focus node typed in one graph whose
+ // required value sits in another must satisfy sh:minCount: per-graph
+ // evaluation would report a violation here, because neither graph carries
+ // both halves. This is the case that tells the two readings apart, and the
+ // one that would make a fix look like it worked while quietly reporting
+ // violations nobody has.
+ let store = store_from_trig(
+ r#"
+ @prefix ex: <http://example.org/> .
+ ex:types { ex:a a ex:Thing . }
+ ex:values { ex:a ex:p "present" . }
+ "#,
+ );
+ let report = ShaclValidator::validate(&store, ONE_SHAPE).unwrap();
+ let v: serde_json::Value = serde_json::from_str(&report).unwrap();
+ assert_eq!(v["focus_nodes"], 1, "report: {v}");
+ assert_eq!(
+ v["conforms"],
+ serde_json::Value::Bool(true),
+ "the value is in the store, so the shape is satisfied: {v}"
+ );
+}
+
+#[test]
+fn test_the_default_graph_is_still_read() {
+ // Widening to the union must not trade one blindness for the other. A
+ // store loaded from Turtle puts everything in the default graph, which is
+ // the overwhelmingly common case, and it must answer exactly as before.
+ let store = store_from_trig(
+ r#"
+ @prefix ex: <http://example.org/> .
+ ex:a a ex:Thing .
+ ex:named { ex:b a ex:Thing ; ex:p "present" . }
+ "#,
+ );
+ let report = ShaclValidator::validate(&store, ONE_SHAPE).unwrap();
+ let v: serde_json::Value = serde_json::from_str(&report).unwrap();
+ assert_eq!(v["focus_nodes"], 2, "both instances count: {v}");
+ assert_eq!(
+ v["violation_count"], 1,
+ "ex:a violates and ex:b does not: {v}"
+ );
+ assert_eq!(
+ v["violations"][0]["focus_node"], "http://example.org/a",
+ "the default-graph instance is the one that violates: {v}"
+ );
+}
+
+#[test]
+fn test_the_report_names_the_scope_it_selected_over() {
+ // A verdict that does not say what it selected over cannot be replayed or
+ // compared against the next one. The key is added before temporal scoping
+ // arrives rather than on the run where it first matters.
+ let store = store_from_trig("@prefix ex: <http://example.org/> . ex:a a ex:Thing .");
+ let report = ShaclValidator::validate(&store, ONE_SHAPE).unwrap();
+ let v: serde_json::Value = serde_json::from_str(&report).unwrap();
+ assert_eq!(v["scope"], "all_graphs", "report: {v}");
+}