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(shacl): onto_shacl_check — structural dry-run for proposed SHACL (#21)
Fabio Rovai9867133e2bba
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 785c1b24..ab7f0578 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,7 @@ All notable changes to Open Ontologies are documented here.### Added- **KGCL output format for `onto_drift`** (#17). The drift detector can now emit results in the [Knowledge Graph Change Language](https://github.com/INCATools/kgcl) (Mungall et al., Database 2025, doi:10.1093/database/baae133) alongside the existing JSON. Two new format options on the MCP tool: `format = "kgcl"` produces line-oriented CNL (`create node <iri>`, `obsolete node <iri>`, `obsolete node <iri> with replacement <iri>`) consumed by ROBOT and BioPortal; `format = "kgcl_json"` produces structured JSON-LD. High-confidence likely_renames (above `rename_threshold`, default 0.7) collapse into a `NodeObsoletion` with `has_direct_replacement` instead of plain add+remove pairs. New module `src/kgcl.rs` with 8 unit tests plus `tests/kgcl_drift_test.rs` integration suite.- **LLM-orchestrated borderline-candidate review for `onto_align`** (#16). The alignment engine now splits its output into three buckets driven by two thresholds rather than a single `min_confidence` cliff: candidates with confidence above `high_threshold` (default 0.85) auto-apply as today, those in `[low_threshold, high_threshold)` (default low 0.4) surface in a new `borderline` array enriched with `context` (source/target labels and parent IRIs), and those below `low_threshold` are dropped. The MCP tool returns a `summary_for_review` instructing the connected LLM to inspect each borderline pair and call `onto_align_feedback` to record verdicts — those verdicts flow into the existing self-calibrating-weights loop. This is the MCP-native form of the LogMap-LLM "LLM-as-oracle" pattern (Jiménez-Ruiz et al., EACL 2026 main, top-2 in OAEI 2025 Bio-ML): no extra LLM client, no API key, no provider abstraction — the connected orchestrator does the judging via the conversation that already exists. New public method `AlignmentEngine::align_with_thresholds(source, target, high, low, dry_run)`; the legacy `align(source, target, min_confidence, dry_run)` remains and delegates with a degenerate range (empty borderline bucket) for back-compat. New `OntoAlignInput` fields `high_threshold` + `low_threshold` (both optional); `min_confidence` retained as the back-compat alias for `high_threshold`. New `tests/align_borderline_test.rs` (5 tests) covering bucket boundaries, context enrichment, summary text, and back-compat.+- **`onto_shacl_check` MCP tool — structural dry-run for proposed SHACL shapes** (#18). New `ShaclValidator::check_shapes(graph, shapes_ttl)` function and matching MCP tool that verifies (a) the shapes parse as Turtle and (b) every IRI they reference exists in the loaded ontology: `sh:targetClass` and `sh:class` must be declared as `owl:Class`/`rdfs:Class`; `sh:path` must be declared as `owl:ObjectProperty`, `owl:DatatypeProperty`, or `rdf:Property`; `sh:datatype` is prefix-checked against `xsd:`. Does NOT validate data — that's the existing `onto_shacl`. The intended workflow: the connected LLM generates candidate SHACL from a prose specification (the text2shacl paper, CiTIUS 2025, reports F1 0.904 / 0.934 / 0.699 on the EU ERA railway ontology with general-purpose LLMs), calls `onto_shacl_check` to catch missing IRIs, iterates, then runs `onto_shacl` to validate data. This is the MCP-native form of NL-to-SHACL: no LLM inside the server, no API key, the server provides the validation primitive and Claude does the authoring. Output includes per-shape diagnostic detail and an `issues` array categorised by `missing_target_class` / `missing_path` / `missing_class_constraint` / `unrecognised_datatype`. New `tests/shacl_check_test.rs` (7 tests covering well-formed shapes, each issue category, and Turtle parse failure).- **DuckDB SQL data backbone**. New optional `duckdb` Cargo feature (and `sql` umbrella combining `postgres` + `duckdb`) wires DuckDB in alongside PostgreSQL as a *data integration* backbone — not as a SPARQL parser. DuckDB's extensions (`httpfs`, `parquet`, `csv`, `json`, `postgres_scanner`, `iceberg`, `delta`, …) let one SQL query federate over remote files, object stores, and other databases; rows then flow into the existing mapping/SHACL/reason pipeline.- **New MCP tool `onto_sql_ingest`** — runs a SQL `SELECT` against PostgreSQL or DuckDB and ingests result rows into the triple store using the same `MappingConfig` shape as `onto_ingest`. Connection-string scheme is auto-detected (`postgres://`, `postgresql://`, `duckdb://`, `:memory:`, or a `*.duckdb` / `*.ddb` file path).- **New CLI command `sql-ingest`** mirroring the MCP tool, with `--mapping`, `--inline-mapping`, `--base-iri`, and `-` (stdin) for the SQL.diff --git a/src/inputs.rs b/src/inputs.rsindex e63e5946..7c75ac73 100644--- a/src/inputs.rs+++ b/src/inputs.rs@@ -207,6 +207,18 @@ pub struct OntoShaclInput {pub inline: Option<bool>,}+#[derive(Deserialize, JsonSchema)]+pub struct OntoShaclCheckInput {+ /// Path to SHACL shapes file OR inline SHACL Turtle content to dry-run-validate+ /// against the currently loaded ontology. Checks that the shapes parse and that+ /// every IRI they reference (`sh:targetClass`, `sh:path`, `sh:class`) actually+ /// exists in the ontology, plus a lightweight XSD-prefix check on `sh:datatype`.+ /// Does NOT apply or run the shapes — that's `onto_shacl`.+ pub shapes: String,+ /// If true, treat shapes as inline Turtle content (default false = file path).+ pub inline: Option<bool>,+}+#[derive(Deserialize, JsonSchema)]pub struct OntoReasonInput {/// Reasoning profile: rdfs (default), owl-rldiff --git a/src/server.rs b/src/server.rsindex 906c3092..89e9a747 100644--- a/src/server.rs+++ b/src/server.rs@@ -914,6 +914,21 @@ impl OpenOntologiesServer {.unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e))}+ #[tool(name = "onto_shacl_check", description = "Dry-run structural check on proposed SHACL shapes against the loaded ontology. Verifies that shapes parse as Turtle and that every IRI they reference (sh:targetClass, sh:path, sh:class) exists in the ontology, plus a lightweight XSD-prefix check on sh:datatype. Does NOT validate data — use onto_shacl for that. Use this to iterate on LLM-generated SHACL before applying.")]+ async fn onto_shacl_check(&self, Parameters(input): Parameters<OntoShaclCheckInput>) -> String {+ use crate::shacl::ShaclValidator;+ let shapes = if input.inline.unwrap_or(false) {+ input.shapes.clone()+ } else {+ match std::fs::read_to_string(&input.shapes) {+ Ok(c) => c,+ Err(e) => return format!(r#"{{"error":"Cannot read shapes file: {}"}}"#, e),+ }+ };+ ShaclValidator::check_shapes(&self.graph, &shapes)+ .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e))+ }+#[tool(name = "onto_reason", description = "Run inference over the loaded ontology. Profiles: 'rdfs' (subclass, domain/range), 'owl-rl' (+ transitive/symmetric/inverse, sameAs, equivalentClass), 'owl-rl-ext' (+ someValuesFrom, allValuesFrom, hasValue, intersectionOf, unionOf), 'owl-dl' (Full OWL2-DL SHOIQ tableaux: satisfiability, classification, qualified number restrictions with node merging, inverse/symmetric roles, functional properties, parallel agent-based classification, explanation traces, ABox reasoning). Materializes inferred triples.")]async fn onto_reason(&self, Parameters(input): Parameters<OntoReasonInput>) -> String {use crate::reason::Reasoner;diff --git a/src/shacl.rs b/src/shacl.rsindex 2c5b6423..382f1078 100644--- a/src/shacl.rs+++ b/src/shacl.rs@@ -192,6 +192,177 @@ impl ShaclValidator {Ok(report.to_string())}++ /// Structural dry-run check on proposed SHACL shapes.+ ///+ /// Verifies that the shapes parse as Turtle and that every IRI they reference+ /// (`sh:targetClass`, `sh:path`, `sh:class`) actually exists in the loaded+ /// ontology, plus a lightweight XSD-prefix check on `sh:datatype`. Does NOT+ /// validate data against the shapes — that's `validate`. This is the primitive+ /// the orchestrating LLM needs to iterate on proposed SHACL before applying.+ ///+ /// Output is a JSON report with `ok` (true if no structural issues), `parses`,+ /// `shape_count`, and an `issues` array describing each missing reference.+ pub fn check_shapes(graph: &Arc<GraphStore>, shapes_ttl: &str) -> anyhow::Result<String> {+ // 1. Parse the proposed shapes into a temporary Oxigraph store.+ let shapes_store = Store::new()?;+ let reader = Cursor::new(shapes_ttl.as_bytes());+ let parser = RdfParser::from_format(RdfFormat::Turtle).for_reader(reader);+ for quad in parser {+ match quad {+ Ok(q) => shapes_store.insert(&q)?,+ Err(e) => {+ return Ok(serde_json::json!({+ "ok": false,+ "parses": false,+ "parse_error": format!("{}", e),+ "issues": [],+ "issue_count": 0,+ "shape_count": 0,+ })+ .to_string());+ }+ };+ }++ // 2. Walk every NodeShape and collect its referenced IRIs (target_class ++ // per-property path + optional class constraint + datatype).+ let shapes = query_solutions(+ &shapes_store,+ r#"+ PREFIX sh: <http://www.w3.org/ns/shacl#>+ SELECT ?shape ?targetClass WHERE {+ ?shape a sh:NodeShape ;+ sh:targetClass ?targetClass .+ }+ "#,+ )?;++ let mut issues: Vec<serde_json::Value> = Vec::new();+ let mut shape_reports: Vec<serde_json::Value> = Vec::new();++ for shape in &shapes {+ let shape_iri = match shape.get("shape") {+ Some(s) => s.clone(),+ None => continue,+ };+ let target_class = match shape.get("targetClass") {+ Some(tc) => strip_angle_brackets(tc),+ None => continue,+ };++ let target_class_exists = class_exists(graph, &target_class)?;+ if !target_class_exists {+ issues.push(serde_json::json!({+ "shape": strip_angle_brackets(&shape_iri),+ "kind": "missing_target_class",+ "value": target_class,+ "message": format!(+ "sh:targetClass <{}> is not declared as owl:Class or rdfs:Class in the loaded ontology",+ target_class+ ),+ }));+ }++ let props = query_solutions(+ &shapes_store,+ &format!(+ r#"+ PREFIX sh: <http://www.w3.org/ns/shacl#>+ SELECT ?prop ?path ?class ?datatype WHERE {{+ {} sh:property ?prop .+ ?prop sh:path ?path .+ OPTIONAL {{ ?prop sh:class ?class }}+ OPTIONAL {{ ?prop sh:datatype ?datatype }}+ }}+ "#,+ shape_iri+ ),+ )?;++ let mut prop_reports: Vec<serde_json::Value> = Vec::new();+ for prop in &props {+ let path = match prop.get("path") {+ Some(p) => strip_angle_brackets(p),+ None => continue,+ };+ let path_exists = property_exists(graph, &path)?;+ if !path_exists {+ issues.push(serde_json::json!({+ "shape": strip_angle_brackets(&shape_iri),+ "kind": "missing_path",+ "value": path.clone(),+ "message": format!(+ "sh:path <{}> is not declared as a property (owl:ObjectProperty, owl:DatatypeProperty, or rdf:Property) in the loaded ontology",+ path+ ),+ }));+ }++ let class_constraint = prop.get("class").map(|c| strip_angle_brackets(c));+ let class_exists_value = match &class_constraint {+ Some(iri) => {+ let exists = class_exists(graph, iri)?;+ if !exists {+ issues.push(serde_json::json!({+ "shape": strip_angle_brackets(&shape_iri),+ "kind": "missing_class_constraint",+ "value": iri.clone(),+ "message": format!(+ "sh:class <{}> is not declared as owl:Class or rdfs:Class in the loaded ontology",+ iri+ ),+ }));+ }+ Some(exists)+ }+ None => None,+ };++ let datatype = prop.get("datatype").map(|d| strip_angle_brackets(d));+ let datatype_ok = datatype.as_deref().map(is_recognised_xsd_datatype);+ if let (Some(dt), Some(false)) = (datatype.as_deref(), datatype_ok) {+ let dt_owned: String = dt.to_owned();+ issues.push(serde_json::json!({+ "shape": strip_angle_brackets(&shape_iri),+ "kind": "unrecognised_datatype",+ "value": dt_owned,+ "message": format!(+ "sh:datatype <{}> does not look like an XSD datatype IRI (expected something starting with http://www.w3.org/2001/XMLSchema#)",+ dt+ ),+ }));+ }++ prop_reports.push(serde_json::json!({+ "path": path,+ "path_exists": path_exists,+ "class_constraint": class_constraint,+ "class_constraint_exists": class_exists_value,+ "datatype": datatype,+ "datatype_recognised": datatype_ok,+ }));+ }++ shape_reports.push(serde_json::json!({+ "shape_iri": strip_angle_brackets(&shape_iri),+ "target_class": target_class,+ "target_class_exists": target_class_exists,+ "property_constraints": prop_reports,+ }));+ }++ let ok = issues.is_empty();+ Ok(serde_json::json!({+ "ok": ok,+ "parses": true,+ "shape_count": shape_reports.len(),+ "issue_count": issues.len(),+ "issues": issues,+ "shapes": shape_reports,+ })+ .to_string())+ }}/// Run a SPARQL SELECT against a temporary shapes `Store` and return results@@ -249,6 +420,40 @@ fn graph_sparql_select(Ok(rows)}+/// Check whether `iri` is declared as `owl:Class` or `rdfs:Class` in the graph.+fn class_exists(graph: &Arc<GraphStore>, iri: &str) -> anyhow::Result<bool> {+ let query = format!(+ r#"SELECT ?x WHERE {{+ <{iri}> a ?type .+ FILTER(?type = <http://www.w3.org/2002/07/owl#Class>+ || ?type = <http://www.w3.org/2000/01/rdf-schema#Class>)+ }} LIMIT 1"#+ );+ let results = graph_sparql_select(graph, &query)?;+ Ok(!results.is_empty())+}++/// Check whether `iri` is declared as an `owl:ObjectProperty`,+/// `owl:DatatypeProperty`, or `rdf:Property` in the graph.+fn property_exists(graph: &Arc<GraphStore>, iri: &str) -> anyhow::Result<bool> {+ let query = format!(+ r#"SELECT ?x WHERE {{+ <{iri}> a ?type .+ FILTER(?type = <http://www.w3.org/2002/07/owl#ObjectProperty>+ || ?type = <http://www.w3.org/2002/07/owl#DatatypeProperty>+ || ?type = <http://www.w3.org/1999/02/22-rdf-syntax-ns#Property>)+ }} LIMIT 1"#+ );+ let results = graph_sparql_select(graph, &query)?;+ Ok(!results.is_empty())+}++/// Quick prefix check for XSD datatypes (the SHACL spec allows others,+/// but the overwhelming majority of real-world `sh:datatype` constraints are XSD).+fn is_recognised_xsd_datatype(iri: &str) -> bool {+ iri.starts_with("http://www.w3.org/2001/XMLSchema#")+}+/// Trim angle brackets from IRI strings like `<http://example.org/foo>`.fn strip_angle_brackets(s: &str) -> String {let s = s.trim();diff --git a/tests/shacl_check_test.rs b/tests/shacl_check_test.rsnew file mode 100644index 00000000..02b4f490--- /dev/null+++ b/tests/shacl_check_test.rs@@ -0,0 +1,229 @@+//! Integration tests for `ShaclValidator::check_shapes` (#18).+//!+//! Verifies the structural dry-run primitive: the function must catch missing+//! `sh:targetClass`, `sh:path`, `sh:class`, and unrecognised `sh:datatype` IRIs+//! against the loaded ontology, but accept well-formed shapes referencing+//! existing terms.++use open_ontologies::graph::GraphStore;+use open_ontologies::shacl::ShaclValidator;+use std::sync::Arc;++const ONTOLOGY: &str = r#"+ @prefix owl: <http://www.w3.org/2002/07/owl#> .+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .+ @prefix ex: <http://example.org/> .++ ex:Person a owl:Class .+ ex:Address a owl:Class .+ ex:hasName a owl:DatatypeProperty ;+ rdfs:domain ex:Person ;+ rdfs:range <http://www.w3.org/2001/XMLSchema#string> .+ ex:livesAt a owl:ObjectProperty ;+ rdfs:domain ex:Person ;+ rdfs:range ex:Address .+"#;++fn loaded() -> Arc<GraphStore> {+ let g = Arc::new(GraphStore::new());+ g.load_turtle(ONTOLOGY, None).expect("load ontology");+ g+}++#[test]+fn well_formed_shapes_pass() {+ let graph = loaded();++ let shapes = r#"+ @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:hasName ;+ sh:datatype <http://www.w3.org/2001/XMLSchema#string> ;+ ] ;+ sh:property [+ sh:path ex:livesAt ;+ sh:class ex:Address ;+ ] .+ "#;++ let report_str = ShaclValidator::check_shapes(&graph, shapes).expect("check_shapes");+ let report: serde_json::Value = serde_json::from_str(&report_str).expect("json");++ assert!(+ report["ok"].as_bool().unwrap(),+ "well-formed shapes should produce ok=true; got:\n{}",+ report_str+ );+ assert!(report["parses"].as_bool().unwrap());+ assert_eq!(report["issue_count"].as_u64().unwrap(), 0);+ assert_eq!(report["shape_count"].as_u64().unwrap(), 1);+}++#[test]+fn missing_target_class_is_flagged() {+ let graph = loaded();++ let shapes = r#"+ @prefix sh: <http://www.w3.org/ns/shacl#> .+ @prefix ex: <http://example.org/> .++ ex:GhostShape a sh:NodeShape ;+ sh:targetClass ex:DoesNotExist ;+ sh:property [+ sh:path ex:hasName ;+ ] .+ "#;++ let report_str = ShaclValidator::check_shapes(&graph, shapes).expect("check_shapes");+ let report: serde_json::Value = serde_json::from_str(&report_str).expect("json");++ assert!(!report["ok"].as_bool().unwrap());+ assert!(report["issue_count"].as_u64().unwrap() >= 1);++ let issues = report["issues"].as_array().unwrap();+ assert!(+ issues.iter().any(|i| {+ i["kind"].as_str() == Some("missing_target_class")+ && i["value"].as_str().unwrap_or("").contains("DoesNotExist")+ }),+ "expected a missing_target_class issue for ex:DoesNotExist; got: {:?}",+ issues+ );+}++#[test]+fn missing_path_property_is_flagged() {+ let graph = loaded();++ let shapes = r#"+ @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:undeclaredProperty ;+ ] .+ "#;++ let report_str = ShaclValidator::check_shapes(&graph, shapes).expect("check_shapes");+ let report: serde_json::Value = serde_json::from_str(&report_str).expect("json");++ assert!(!report["ok"].as_bool().unwrap());+ let issues = report["issues"].as_array().unwrap();+ assert!(+ issues.iter().any(|i| {+ i["kind"].as_str() == Some("missing_path")+ && i["value"].as_str().unwrap_or("").contains("undeclaredProperty")+ }),+ "expected a missing_path issue; got: {:?}",+ issues+ );+}++#[test]+fn missing_class_constraint_is_flagged() {+ let graph = loaded();++ let shapes = r#"+ @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:livesAt ;+ sh:class ex:NoSuchClass ;+ ] .+ "#;++ let report_str = ShaclValidator::check_shapes(&graph, shapes).expect("check_shapes");+ let report: serde_json::Value = serde_json::from_str(&report_str).expect("json");++ assert!(!report["ok"].as_bool().unwrap());+ let issues = report["issues"].as_array().unwrap();+ assert!(+ issues.iter().any(|i| {+ i["kind"].as_str() == Some("missing_class_constraint")+ && i["value"].as_str().unwrap_or("").contains("NoSuchClass")+ }),+ "expected a missing_class_constraint issue; got: {:?}",+ issues+ );+}++#[test]+fn unrecognised_datatype_is_flagged() {+ let graph = loaded();++ let shapes = r#"+ @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:hasName ;+ sh:datatype ex:CustomNotXsd ;+ ] .+ "#;++ let report_str = ShaclValidator::check_shapes(&graph, shapes).expect("check_shapes");+ let report: serde_json::Value = serde_json::from_str(&report_str).expect("json");++ let issues = report["issues"].as_array().unwrap();+ assert!(+ issues.iter().any(|i| i["kind"].as_str() == Some("unrecognised_datatype")),+ "expected an unrecognised_datatype issue; got: {:?}",+ issues+ );+}++#[test]+fn invalid_turtle_returns_parse_error_not_panic() {+ let graph = loaded();++ let bad_shapes = "this is not turtle: << >> /// invalid";+ let report_str = ShaclValidator::check_shapes(&graph, bad_shapes).expect("check_shapes");+ let report: serde_json::Value = serde_json::from_str(&report_str).expect("json");++ assert!(!report["parses"].as_bool().unwrap());+ assert!(!report["ok"].as_bool().unwrap());+ assert!(report["parse_error"].is_string());+}++#[test]+fn well_formed_shapes_carry_per_shape_diagnostic_detail() {+ // Beyond the top-level `ok` flag, callers (LLMs) need per-shape detail+ // to write targeted fixes. Verify that.+ let graph = loaded();++ let shapes = r#"+ @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:hasName ;+ sh:datatype <http://www.w3.org/2001/XMLSchema#string> ;+ ] .+ "#;++ let report_str = ShaclValidator::check_shapes(&graph, shapes).expect("check_shapes");+ let report: serde_json::Value = serde_json::from_str(&report_str).expect("json");++ let shapes_arr = report["shapes"].as_array().unwrap();+ assert_eq!(shapes_arr.len(), 1);+ let s = &shapes_arr[0];+ assert!(s["target_class"].as_str().unwrap().contains("Person"));+ assert!(s["target_class_exists"].as_bool().unwrap());+ let pc = s["property_constraints"].as_array().unwrap();+ assert_eq!(pc.len(), 1);+ assert!(pc[0]["path_exists"].as_bool().unwrap());+ assert!(pc[0]["datatype_recognised"].as_bool().unwrap());+}