Skip to main content

oxilite_validate/
lib.rs

1//! SHACL and ShEx validation of oxilite data with [rudof](https://rudof-project.github.io/).
2//!
3//! rudof's engines run unchanged: [`StoreGraph`] implements rudof's `Rdf`, `NeighsRDF` and
4//! `QueryRDF` traits over a blocking [`Store`], so neighbourhood lookups become SQL pattern
5//! scans and rudof's SPARQL runs through the oxilite compiler. For stores that cannot block
6//! (Cloudflare D1), [`prefetch`] loads the relevant subgraph into rudof's in-memory graph with
7//! a bounded number of requests, then validates it natively. rudof's validators do not build
8//! for wasm32, so D1 validation runs in native code (a CLI, a server, CI) over the D1 HTTP API.
9//!
10// @lat: [[architecture#Validation]]
11
12mod graph;
13pub mod prefetch;
14
15pub use graph::StoreGraph;
16pub use shacl::validator::report::ValidationReport;
17pub use shacl::validator::ShaclValidationMode;
18pub use shex_ast::shapemap::result_shape_map::ResultShapeMap;
19
20use oxilite::model::{GraphName, GraphNameRef};
21use oxilite::schema::SchemaRole;
22use oxilite::store::Store;
23use oxilite_core::SyncBackend;
24use rudof_iri::IriS;
25use rudof_rdf::rdf_core::RDFFormat;
26use rudof_rdf::rdf_impl::{OxigraphInMemory, ReaderMode};
27use shacl::ir::IRSchema;
28use shacl::rdf::ShaclParser;
29use shacl::validator::engine::{Engine, NativeEngine, SparqlEngine};
30use shacl::validator::processor::ShaclProcessor;
31use shacl::validator::ShaclConfig;
32use shex_ast::compact::ShapeMapParser;
33use shex_ast::ir::map_state::MapState;
34use shex_ast::ir::schema_ir::SchemaIR;
35use shex_ast::ir::semantic_actions_registry::SemanticActionsRegistry;
36use shex_ast::{ResolveMethod, ShExParser};
37use shex_validation::{Validator, ValidatorConfig};
38use std::fmt::Debug;
39
40/// Validation errors (shapes that do not parse, rudof failures, store errors, limits).
41#[derive(Debug, thiserror::Error)]
42pub enum Error {
43    #[error("invalid shapes: {0}")]
44    Shapes(String),
45    #[error("validation failed: {0}")]
46    Validation(String),
47    #[error(transparent)]
48    Store(#[from] oxilite_core::Error),
49    #[error(
50        "the subgraph needed for validation has more than {limit} triples ({found} found so far); raise the limit or validate natively"
51    )]
52    TooLarge { limit: usize, found: usize },
53    #[error("no SHACL shapes graph is registered; name one explicitly or register it")]
54    NoShapesGraph,
55    #[error("{0} SHACL shapes graphs are registered ({1}); name the one to use")]
56    AmbiguousShapesGraph(usize, String),
57}
58
59pub type Result<T> = std::result::Result<T, Error>;
60
61/// Parses a SHACL shapes graph (Turtle, N-Triples, RDF/XML…) and compiles it.
62pub fn shacl_schema(shapes: &str, format: &RDFFormat, base: Option<&str>) -> Result<IRSchema> {
63    let graph = OxigraphInMemory::from_str(shapes, format, base, &ReaderMode::Strict)
64        .map_err(|e| Error::Shapes(e.to_string()))?;
65    let ast = ShaclParser::new(graph)
66        .parse()
67        .map_err(|e| Error::Shapes(e.to_string()))?;
68    IRSchema::try_from(ast).map_err(|e| Error::Shapes(e.to_string()))
69}
70
71/// Compiles the SHACL shapes held in the store itself.
72///
73/// With `graph`, that graph's triples are the shapes graph. Without one, the registry decides:
74/// exactly one graph registered as SHACL shapes is used, and anything else is an error rather
75/// than a guess. The shapes are serialized and handed to rudof's own parser, so a stored
76/// shapes graph and a shapes file compile identically.
77pub fn shacl_schema_from_store<B: SyncBackend + Send + Sync + 'static>(
78    store: &Store<B>,
79    graph: Option<GraphNameRef<'_>>,
80) -> Result<IRSchema> {
81    let graph = match graph {
82        Some(g) => g.into_owned(),
83        None => {
84            let registered: Vec<GraphName> = store
85                .schema_graphs()?
86                .into_iter()
87                .filter(|g| g.role == SchemaRole::Shacl)
88                .map(|g| g.graph)
89                .collect();
90            match registered.len() {
91                0 => return Err(Error::NoShapesGraph),
92                1 => registered.into_iter().next().expect("one graph"),
93                n => {
94                    let names: Vec<String> = registered.iter().map(ToString::to_string).collect();
95                    return Err(Error::AmbiguousShapesGraph(n, names.join(", ")));
96                }
97            }
98        }
99    };
100    let turtle =
101        store.dump_graph_to_writer(graph.as_ref(), oxilite::io::RdfFormat::NTriples, Vec::new())?;
102    let turtle = String::from_utf8(turtle)
103        .map_err(|e| Error::Shapes(format!("shapes graph is not valid UTF-8: {e}")))?;
104    shacl_schema(&turtle, &RDFFormat::NTriples, None)
105}
106
107/// Validates a store against the shapes it holds (see [`shacl_schema_from_store`]).
108pub fn validate_shacl_stored<B: SyncBackend + Send + Sync + 'static>(
109    store: &Store<B>,
110    shapes_graph: Option<GraphNameRef<'_>>,
111    mode: &ShaclValidationMode,
112) -> Result<ValidationReport> {
113    let schema = shacl_schema_from_store(store, shapes_graph)?;
114    validate_shacl_graph(StoreGraph::new(store.clone()), &schema, mode)
115}
116
117/// A SHACL processor over any rudof graph (a store, or a prefetched in-memory graph).
118struct Processor<S> {
119    data: S,
120}
121
122impl<
123        S: rudof_rdf::rdf_core::NeighsRDF
124            + rudof_rdf::rdf_core::query::QueryRDF
125            + Debug
126            + Send
127            + Sync
128            + 'static,
129    > ShaclProcessor<S> for Processor<S>
130{
131    fn store(&self) -> &S {
132        &self.data
133    }
134
135    fn runner(mode: &ShaclValidationMode, config: &ShaclConfig) -> Box<dyn Engine<S>> {
136        match mode {
137            ShaclValidationMode::Native => {
138                Box::new(NativeEngine::new(config.recursion_semantics()))
139            }
140            ShaclValidationMode::Sparql => {
141                Box::new(SparqlEngine::new(config.recursion_semantics()))
142            }
143        }
144    }
145}
146
147/// Validates any rudof graph against compiled SHACL shapes.
148pub fn validate_shacl_graph<S>(
149    data: S,
150    schema: &IRSchema,
151    mode: &ShaclValidationMode,
152) -> Result<ValidationReport>
153where
154    S: rudof_rdf::rdf_core::NeighsRDF
155        + rudof_rdf::rdf_core::query::QueryRDF
156        + Debug
157        + Send
158        + Sync
159        + 'static,
160{
161    Processor { data }
162        .validate(schema, mode, &ShaclConfig::default())
163        .map_err(|e| Error::Validation(e.to_string()))
164}
165
166/// Validates the default graph of a store (or, with `union`, all graphs merged) against a
167/// SHACL shapes graph given as Turtle.
168pub fn validate_shacl<B: SyncBackend + Send + Sync + 'static>(
169    store: &Store<B>,
170    shapes_turtle: &str,
171    mode: &ShaclValidationMode,
172) -> Result<ValidationReport> {
173    let schema = shacl_schema(shapes_turtle, &RDFFormat::Turtle, None)?;
174    validate_shacl_graph(StoreGraph::new(store.clone()), &schema, mode)
175}
176
177/// Parses and compiles a ShEx schema (ShExC).
178pub fn shex_schema(schema: &str, base: &str) -> Result<SchemaIR> {
179    let base = IriS::new(base).map_err(|e| Error::Shapes(e.to_string()))?;
180    let ast = ShExParser::parse(schema, Some(base.clone()), &base)
181        .map_err(|e| Error::Shapes(e.to_string()))?;
182    let config = ValidatorConfig::default();
183    let mut map_state = MapState::default();
184    let registry = SemanticActionsRegistry::default();
185    registry.set_map_state(&mut map_state);
186    let mut compiler = shex_ast::ir::ast2ir::AST2IR::new(&ResolveMethod::default(), map_state);
187    let mut compiled = SchemaIR::new(registry);
188    compiler
189        .compile(
190            &ast,
191            &base,
192            &Some(base.clone()),
193            &mut compiled,
194            config.external_resolvers(),
195        )
196        .map_err(|e| Error::Shapes(e.to_string()))?;
197    Ok(compiled)
198}
199
200/// Validates the nodes of a ShEx shape map (compact syntax, e.g. `<http://ex/a>@<http://ex/S>`)
201/// on any rudof graph.
202pub fn validate_shex_graph<S>(
203    data: &S,
204    schema: &SchemaIR,
205    shape_map: &str,
206) -> Result<ResultShapeMap>
207where
208    S: rudof_rdf::rdf_core::NeighsRDF + rudof_rdf::rdf_core::query::QueryRDF,
209{
210    let nodes_pm = data.prefixmap();
211    let shapes_pm = Some(schema.prefixmap());
212    let map = ShapeMapParser::parse(shape_map, &nodes_pm, &None, &shapes_pm, &None)
213        .map_err(|e| Error::Shapes(e.to_string()))?;
214    let validator = Validator::new(schema, &ValidatorConfig::default())
215        .map_err(|e| Error::Validation(e.to_string()))?;
216    validator
217        .validate_shapemap(&map, data, schema, &nodes_pm)
218        .map_err(|e| Error::Validation(e.to_string()))
219}
220
221/// Validates the default graph of a store against a ShEx schema and a shape map.
222pub fn validate_shex<B: SyncBackend + Send + Sync + 'static>(
223    store: &Store<B>,
224    shexc: &str,
225    base: &str,
226    shape_map: &str,
227) -> Result<ResultShapeMap> {
228    let schema = shex_schema(shexc, base)?;
229    validate_shex_graph(&StoreGraph::new(store.clone()), &schema, shape_map)
230}