---
title: 'xpSHACL: Explainable SHACL Validation'
url: https://www.emergentmind.com/topics/xpshacl
type: topic
---

# xpSHACL: Explainable SHACL Validation

Searching arXiv for the cited xpSHACL paper and closely related SHACL semantics work.
{"query":"arXiv:2507.08432 xpSHACL Explainable SHACL Validation using Retrieval-Augmented Generation and Large Language Models", "max_results": 5}
{"query":"xpSHACL Explainable SHACL Validation using Retrieval-Augmented Generation and Large Language Models", "max_results": 10}
{"query":"Fixpoint Semantics for Recursive SHACL 2109.08285", "max_results": 5}
xpSHACL is an explainable SHACL validation system that combines rule-based justification trees with retrieval-augmented generation (RAG) and large language models (LLMs) to produce detailed, multilanguage, human-readable explanations for constraint violations. It is modeled as a validation pipeline over an RDF data graph and a SHACL shapes graph, with a persistent Violation Knowledge Graph that caches explanations and suggestions by violation signature. In the formulation associated with xpSHACL, the system is intended to make RDF validation more transparent while preserving the underlying SHACL validation workflow [2507.08432].

## 1. Formal definition and core objects

The formal model of xpSHACL is the tuple
$$
\mathrm{xpSHACL} = (D, S, EV, JB, CR, EG, KG)
$$
where $D$ is the RDF data graph to be validated; $S$ is the SHACL shapes graph containing node- and property-shape constraints; $EV:(D,S)\to V$ is the Extended Validator that builds the set $V$ of detailed violations; $JB:V\to T$ is the Justification Tree Builder mapping each violation $v\in V$ to a tree $T(v)$; $CR:V\to C$ is the Context Retriever that collects auxiliary domain context $C(v)$ for each $v$; $EG:(V,T,C,\ell)\to E$ is the Explanation Generator producing an explanation $E$ in language $\ell$; and $KG$ is the Violation Knowledge Graph, a persistent store mapping a violation signature $\sigma(v)$ to cached explanations and suggestions in various languages [2507.08432].

A violation $v\in V$ is a record
$$
v=\langle focusNode, sourceShape, constraintComponent, path, value\rangle
$$
extracted from the SHACL report, specifically `sh:ValidationResult`. This representation preserves the focus node, the violated shape, the constraint component, the relevant path, and the offending value. In xpSHACL, the violation object is therefore richer than a minimal pass/fail outcome.

The justification tree $T(v)$ is a rooted, directed tree whose nodes are premise nodes, observation nodes, and inference nodes. Edges connect observations and premises to inferences, culminating in the root “violation occurred.” The canonical example is a premise such as “Shape X requires minCount = 1” combined with an observation such as “Node n has 0 values for property P,” yielding the inference “0 < 1 ⇒ violation.” This makes the explanatory layer explicitly symbolic rather than purely generative.

The violation signature is defined as a canonical abstraction of $v$ ignoring instance-specific identifiers:
$$
\sigma(v)=\mathrm{hash}\bigl(\text{sourceShape},\;\text{constraintComponent},\;\text{path}\bigr).
$$
The explanation itself is a structured object
$$
E=\langle text_\ell, suggestions_\ell\rangle
$$
where $text_\ell$ is the natural-language rationale in language $\ell$ and $suggestions_\ell$ is a set of corrective actions. This suggests that xpSHACL treats explanation not as free-form prose alone, but as a paired rationale-and-remediation artifact.

## 2. Architectural organization and validation flow

The architecture consists of five major components and their interactions: the Extended Validator, the Justification Tree Builder, the Context Retriever connected to RAG sources, the Explanation Generator, and the Violation Knowledge Graph cache [2507.08432]. The RAG sources are explicitly listed as ontology fragments, shape docs, similar cases, and domain rules.

The process begins when `EV` runs a SHACL engine, specifically pySHACL, on $(D,S)$ and extracts for each violation $v$ the full context: focus node, shape, constraint component, path, and offending value. `JB` then uses rdflib/Sparql to traverse the shapes and data graphs and constructs $T(v)$, described as a symbolic proof tree. `CR` executes SPARQL queries to retrieve four classes of context: ontology fragments, shape documentation, similar cases, and domain rules. The retrieved shape documentation is identified as `rdfs:comment` or `sh:description` attached to the violated shape, while domain rules are business logic axioms linked via a custom `xsh:appliesToProperty` predicate.

Before the LLM is called, the system computes $\sigma(v)$ and queries `KG` for an existing explanation in the requested language $\ell`. On a cache hit, xpSHACL retrieves $text_\ell$ and $suggestions_\ell$. On a cache miss, it feeds $v$, $T(v)$, $C(v)$, and $\ell$ into `EG` to synthesize
$$
E = EG(v,T,C,\ell),
$$
then stores $\langle \sigma(v),\ell,E\rangle$ in `KG`.

The end-to-end validation flow is specified in four stages. Step 1 takes input $D$ and $S$. Step 2 executes `EV.validate(D,S)` to obtain the set of violations $V$. Step 3 iterates over each $v\in V$: compute $\sigma(v)$; if cached, retrieve $E$; otherwise build the justification tree, retrieve context, generate the explanation, and store it in the knowledge graph. Step 4 aggregates all $\langle v,E\rangle$ pairs into the final output, either JSON or UI. The intended consequence is that every violation is accompanied by a human-readable explanation and suggestions.

## 3. Violation Knowledge Graph and explanation reuse

The Violation Knowledge Graph is an RDF graph using a small ontology, `xpshacl_ontology.ttl`, with classes `xsh:ViolationSignature`, `xsh:Explanation`, and `xsh:providedByModel` [2507.08432]. The graph stores signature hashes, language-tagged explanations, correction suggestions, and the model that provided the explanation. The example serialization includes triples such as a signature resource with `xsh:signatureHash "abcd1234"` and an explanation resource with `xsh:forSignature`, `xsh:language`, `xsh:naturalLanguageText`, `xsh:correctionSuggestions`, and `xsh:providedByModel "gemini-2.0-flash-lite"`.

The lookup/store behavior is given by the following pseudocode:

```text
function getExplanation(v, ℓ):
  σ ← computeSignature(v)
  if KG.hasExplanation(σ, ℓ):
    return KG.lookup(σ, ℓ)
  else:
    T ← JB.buildTree(v)
    C ← CR.retrieveContext(v)
    E ← EG.generate(v, T, C, ℓ)
    KG.store(σ, ℓ, E)
    return E
```

Because explanations are expensive, specifically LLM calls, caching by $\sigma$ yields dramatic speedups and consistent wording across runs. The cache key deliberately ignores instance-specific identifiers, so repeated manifestations of the same violated `sourceShape`, `constraintComponent`, and `path` can share an explanation template across focus nodes. A plausible implication is that the Violation KG functions as both a performance mechanism and a normalization layer for explanatory output.

## 4. Multilanguage explanation generation

xpSHACL includes multilanguage generation by combining the same violation signature and justification tree with a prompt that targets a different language [2507.08432]. The illustrative example uses a SHACL shape requiring every `ex:Person` to have at least one `ex:name` with `sh:minCount = 1`, and a resource `ex:Alice` that has no name. The signature is
`hash( PersonShape, sh:MinCountConstraintComponent, ex:name )`.

The English explanation states that `ex:Alice` is typed as `Person` but does not have any `ex:name` values, that the shape requires at least one `ex:name` property, and that the corrective action is to add a name value such as ``ex:Alice ex:name "Alice"@en`` and include an appropriate language tag. The Spanish and German versions express the same violation and repair guidance in the target language, including examples with `"Alicia"@es` and `"Alice"@de`. The system therefore preserves the violation structure while varying only the generated language.

Traditional SHACL validation engines are described as often providing terse reports in English that are difficult for non-technical users to interpret and act upon. xpSHACL addresses this by coupling symbolic justification with domain-aware retrieval and multilingual NLG. This suggests a shift from bare conformance reporting toward explanation-centric validation, while still retaining SHACL as the underlying constraint formalism.

## 5. Evaluation setup, metrics, and reported results

The reported evaluation includes a public-data experiment over LOV ontologies and ontology-quality shapes, and a synthetic baseline experiment using `complex_data.ttl` and `complex_shapes.ttl` [2507.08432]. In the public-data experiment, 868 LOV vocabs were attempted, 431 parsed successfully, and 416 of those had violations. The average end-to-end xpSHACL time per graph was 13.03 s, with core validation at 11.38 s and explanation retrieval/generation at 0.12 s. Total violations were 145 910, with an average of 350 per graph. The violation types were Cardinality (78 022), SPARQL checks (54 096), and Value-type (13 792).

The cache behavior is central to the reported performance profile. The cache hit rate was 99.48 %, corresponding to 2 289 hits of 2 301 lookups. Only 12 unique signatures needed fresh LLM calls, characterized as 12×LLM overhead instead of 2 301×. In the synthetic baseline experiment, pySHACL was approximately 4 s per run and stable. xpSHACL first run was approximately 65 s due to tree-building, context retrieval, hundreds of first-time LLM calls, and KG population. xpSHACL subsequent runs were approximately 20 s, attributed to KG cache retrieval of explanations and the avoidance of LLM calls.

The evaluation metrics are grouped into efficiency, robustness, and quality. Efficiency includes overall runtime and cache hit rate. Robustness is the percentage of graphs successfully processed. Quality, in its initial form, is described through manual inspection of sample explanations that found them clear, correct, actionable. Planned future human studies are specified more formally: RQ1 and RQ4 via Likert scales and task-completion rates, RQ3 via text-similarity metrics such as cosine on embeddings and ROUGE/BLEU, and RQ2 via larger graphs.

## 6. Recursive semantics and fixpoint-theoretic foundation

A separate formal account describes how the fixpoint-based, three-valued semantics for recursive SHACL can be adopted as the formal foundation of xpSHACL as an extension of SHACL with full recursive definitions [2109.08285]. The starting point is a SHACL schema $(Def,T)$ over a fixed RDF graph-interpretation $I$, with shape interpretations $J:S\to \wp(\mathcal{D})$ and a complete lattice $L$ ordered pointwise by subset inclusion. Three-valued interpretations are pairs $\mathbb{I}=(J^{-},J^{+})$ with $J^{-}\leq_t J^{+}$, representing what is certainly true and what is possibly true. The induced bilattice $L^2$ carries the precision order
$$
(J_1^{-},J_1^{+}) \leq_p (J_2^{-},J_2^{+}) \iff J_1^{-}\subseteq J_2^{-} \text{ and } J_2^{+}\subseteq J_1^{+}.
$$

For each rule $s(x)\leftarrow \phi(x)$, the three-valued evaluation of $\phi$ extends Kleene’s truth tables. Conjunction is `min` under the truth order $f<u<t$, disjunction is `max`, and negation swaps $t$ and $f$ and leaves $u$ unchanged. The resulting approximator is
$$
Y_{(Def)}(\mathbb{I})=(K^{-},K^{+}),
$$
where, for each shape $s$ and node $a$,
$$
K^{-}(s)=\{a \mid [[\phi_s]]^{(J^{-},J^{+})}(a)=t\},
\qquad
K^{+}(s)=\{a \mid [[\phi_s]]^{(J^{-},J^{+})}(a)\neq f\}.
$$
The theorem cited in the formalization states that $Y_{(Def)}$ is monotone with respect to $\leq_p$ and that its diagonal agrees with the two-valued operator $T_{(Def)}$.

On this basis, Approximation Fixpoint Theory yields supported, stable, Kripke–Kleene, and well-founded semantics. Supported models are exactly the fixpoints of $T_{(Def)}$; the Kripke–Kleene model is the $\leq_p$-least fixpoint of $Y_{(Def)}$; partial stable models satisfy alternating fixpoint equations; the well-founded model is the $\leq_p$-least partial stable model; and stable two-valued models are those $J$ for which $(J,J)$ is a partial stable model. In the xpSHACL-oriented instantiation, recursive rules may be written using `sh:xpRule`, with an optional schema-level annotation such as `xpSHACL:WellFounded`, and the engine may compute the well-founded model, all stable models, or the Kripke–Kleene model.

The worked examples illustrate the consequences of this choice of semantics. A pure positive recursion for `:Reachable` without a base case yields the unique model $\emptyset$; adding `{Alice} V (≥1 foaf:knows . :Reachable)` yields the transitive closure from Alice. The negation-bearing `:AtRisk` example has two supported models, while the well-founded and Kripke–Kleene models are three-valued with $WF^{-}=\{d,e,f\}$ and $WF^{+}=\{a,b,c,d,e,f\}$. For the non-stratified `:Safe` shape, well-founded and supported semantics admit the unique grounded solution `{a,b,c}`, whereas ACORSS-style level-mapping stable semantics also admit the spurious full model; xpSHACL by default uses AFT-stable, ruling out that extra model. This places xpSHACL within a broader debate on recursive SHACL semantics rather than treating recursion as semantically unproblematic.

## 7. Limitations, extensions, and implementation trajectory

The stated limitations concern latency, residual overhead, dependence on the chosen LLM and prompt design, and privacy [2507.08432]. Initial-run latency is high due to many fresh LLM calls. There remains an approximately 20 s overhead per run even with cache, attributed to justification tree building and SPARQL context queries. Quality depends on the chosen LLM and prompt design, and non-determinism may introduce minor wording differences. Privacy requires careful context retrieval to avoid leaking sensitive data to cloud LLM APIs.

The future directions are framed as concrete engineering extensions. Hybrid Query Engines would integrate high-performance RDF backends such as QLever to speed up SPARQL context retrieval. Extended Caching would store intermediate artifacts, including justification trees and raw context, in the KG to avoid repeated computation. A Collaborative Violation KG would host the KG in a version-controlled repository so community runs enrich the shared cache and eventually make LLM calls rare. Editor Integration would embed xpSHACL into SHARK, RDFUnit, and pySHACL for live feedback. A User Feedback Loop would allow users to correct or refine explanations in the UI, improving KG accuracy and reducing hallucinations. KG Scalability would cluster similar signatures, deduplicate explanations, and partition the KG to maintain fast lookups at scale. Advanced Retrieval would use knowledge-graph embeddings to find semantically related shapes or ontology fragments.

Taken together, these limitations and extensions position xpSHACL as a system in which symbolic SHACL validation, explicit justification structures, retrieval over RDF context, and cached LLM-generated multilingual explanations are tightly coupled. A plausible implication is that its longer-term significance depends not only on explanation quality, but also on how effectively the Violation KG amortizes repeated validation workloads and how cleanly recursive semantics are integrated where full recursive definitions are required.

Source: https://www.emergentmind.com/topics/xpshacl