SHACL Validation¶

IndentiaDB includes a native SHACL (Shapes Constraint Language) validation engine that enforces data quality rules on RDF graphs. The engine implements the W3C SHACL Core specification and extends it with SPARQL-based constraints from the SHACL 1.2 draft, allowing you to define shape graphs that describe the expected structure of your data and validate incoming triples against those shapes before they are committed to the store.

How SHACL Works¶

SHACL validation operates on two graphs:

• Data graph -- the RDF triples you want to validate.
• Shapes graph -- a set of shape definitions that describe valid data structures.

The validation engine selects focus nodes from the data graph based on targets declared in each shape, then checks every applicable constraint. The result is a validation report that either confirms conformance or lists individual violations.

┌──────────────────────┐      ┌──────────────────────┐
│     Shapes Graph     │      │      Data Graph      │
│  ┌────────────────┐  │      │                      │
│  │  NodeShape     │──┼──────┼──▶ Focus Node        │
│  │  PropertyShape │  │      │     ├─ property A     │
│  └────────────────┘  │      │     ├─ property B     │
│                      │      │     └─ property C     │
└──────────────────────┘      └──────────────────────┘
            │                           │
            ▼                           ▼
   ┌────────────────────────────────────────────────┐
   │          SHACL Validation Engine               │
   │   select focus nodes → apply constraints       │
   │   → collect results  → produce report          │
   └────────────────────────────────────────────────┘
                        │
                        ▼
              ValidationReport
              { conforms: true/false,
                results: [...] }

Supported Constraints¶

IndentiaDB supports the full SHACL Core constraint vocabulary plus SPARQL constraints:

Defining Shapes¶

Node Shapes¶

A node shape defines constraints on a focus node itself. Use sh:targetClass to select all instances of a given class:

@prefix sh:     <http://www.w3.org/ns/shacl#> .
@prefix schema: <http://schema.org/> .
@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .
@prefix ex:     <http://example.org/shapes/> .

ex:PersonShape
    a sh:NodeShape ;
    sh:targetClass schema:Person ;
    sh:property ex:PersonNameShape ;
    sh:property ex:PersonEmailShape ;
    sh:property ex:PersonAgeShape .

Property Shapes¶

A property shape defines constraints on the values reached through a property path from the focus node:

ex:PersonNameShape
    a sh:PropertyShape ;
    sh:path schema:name ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:datatype xsd:string ;
    sh:minLength 1 ;
    sh:maxLength 200 ;
    sh:message "Every person must have exactly one name (1-200 characters)" .

ex:PersonEmailShape
    a sh:PropertyShape ;
    sh:path schema:email ;
    sh:minCount 1 ;
    sh:nodeKind sh:Literal ;
    sh:pattern "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" ;
    sh:message "Email must be a valid email address" .

ex:PersonAgeShape
    a sh:PropertyShape ;
    sh:path schema:age ;
    sh:maxCount 1 ;
    sh:datatype xsd:integer ;
    sh:minInclusive 0 ;
    sh:maxInclusive 150 ;
    sh:severity sh:Warning ;
    sh:message "Age must be between 0 and 150" .

Target Declarations¶

IndentiaDB supports all four SHACL target types:

# Target all instances of a class
ex:PersonShape sh:targetClass schema:Person .

# Target a specific node
ex:AliceShape sh:targetNode <http://example.org/alice> .

# Target all subjects that use a predicate
ex:HasNameShape sh:targetSubjectsOf schema:name .

# Target all objects of a predicate
ex:NameValueShape sh:targetObjectsOf schema:name .

Property Path Expressions¶

IndentiaDB evaluates the full range of SHACL property paths, enabling validation of values reached through complex graph traversals:

Example -- validate that every person has a city in their address:

ex:PersonCityShape
    a sh:PropertyShape ;
    sh:path ( schema:address schema:city ) ;
    sh:minCount 1 ;
    sh:datatype xsd:string ;
    sh:message "Person must have a city in their address" .

Logical Constraints¶

Combine shapes using boolean logic for complex validation rules:

# AND: value must satisfy all listed shapes
ex:FullNameShape
    a sh:PropertyShape ;
    sh:path schema:name ;
    sh:and (
        [ sh:minLength 2 ]
        [ sh:maxLength 100 ]
        [ sh:pattern "^[A-Z]" ]
    ) ;
    sh:message "Name must be 2-100 chars and start with uppercase" .

# OR: value must satisfy at least one shape
ex:ContactInfoShape
    a sh:PropertyShape ;
    sh:path schema:contactPoint ;
    sh:or (
        [ sh:datatype xsd:string ; sh:pattern "^\\+?[0-9\\-\\s]+$" ]
        [ sh:datatype xsd:string ; sh:pattern "^[^@]+@[^@]+$" ]
    ) ;
    sh:message "Contact must be a phone number or email" .

# NOT: value must not satisfy the shape
ex:NotRetiredShape
    a sh:PropertyShape ;
    sh:path schema:status ;
    sh:not [ sh:hasValue "retired" ] .

# XONE: value must satisfy exactly one shape
ex:IdentifierShape
    a sh:PropertyShape ;
    sh:path schema:identifier ;
    sh:xone (
        [ sh:pattern "^[0-9]{9}$" ]
        [ sh:pattern "^[A-Z]{2}[0-9]{6}$" ]
    ) ;
    sh:message "Identifier must be either a 9-digit number or a 2-letter + 6-digit code" .

Closed Shapes¶

Restrict which properties a node may have:

ex:StrictPersonShape
    a sh:NodeShape ;
    sh:targetClass schema:Person ;
    sh:closed true ;
    sh:ignoredProperties ( rdf:type ) ;
    sh:property [
        sh:path schema:name ;
        sh:minCount 1 ;
    ] ;
    sh:property [
        sh:path schema:email ;
    ] .

With sh:closed true, any property on a schema:Person node that is not declared as a sh:property path (and not in sh:ignoredProperties) triggers a violation.

Severity Levels¶

Each shape or property shape can declare a severity level that controls how violations are reported:

ex:DeprecatedFieldShape
    a sh:PropertyShape ;
    sh:path ex:legacyField ;
    sh:maxCount 0 ;
    sh:severity sh:Warning ;
    sh:message "legacyField is deprecated; migrate to ex:newField" .

Validation Endpoint¶

IndentiaDB exposes a REST endpoint for SHACL validation:

Load Shapes¶

curl -X POST http://localhost:7001/shacl/shapes \
  -H "Content-Type: text/turtle" \
  -H "Authorization: Bearer $TOKEN" \
  -d '@shapes.ttl'

Response:

{
  "loaded": 3,
  "shape_ids": [
    "http://example.org/shapes/PersonShape",
    "http://example.org/shapes/PersonNameShape",
    "http://example.org/shapes/PersonEmailShape"
  ]
}

Validate Data¶

curl -X POST http://localhost:7001/shacl/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "graph": "http://example.org/data",
    "shapes": ["http://example.org/shapes/PersonShape"]
  }'

Response (conforming):

{
  "conforms": true,
  "results": [],
  "stats": {
    "shapes_evaluated": 1,
    "focus_nodes_validated": 42,
    "constraints_checked": 126,
    "duration_ms": 12
  }
}

Response (non-conforming):

{
  "conforms": false,
  "results": [
    {
      "focusNode": "http://example.org/person/99",
      "resultPath": "http://schema.org/name",
      "sourceShape": "http://example.org/shapes/PersonNameShape",
      "sourceConstraintComponent": "http://www.w3.org/ns/shacl#MinCountConstraintComponent",
      "resultSeverity": "http://www.w3.org/ns/shacl#Violation",
      "resultMessage": "Every person must have exactly one name (1-200 characters)",
      "value": null
    },
    {
      "focusNode": "http://example.org/person/42",
      "resultPath": "http://schema.org/email",
      "sourceShape": "http://example.org/shapes/PersonEmailShape",
      "sourceConstraintComponent": "http://www.w3.org/ns/shacl#PatternConstraintComponent",
      "resultSeverity": "http://www.w3.org/ns/shacl#Violation",
      "resultMessage": "Email must be a valid email address",
      "value": {
        "type": "literal",
        "value": "not-an-email"
      }
    }
  ],
  "stats": {
    "shapes_evaluated": 1,
    "focus_nodes_validated": 42,
    "constraints_checked": 126,
    "duration_ms": 18
  }
}

Validate Inline Data¶

Send both shapes and data in one request:

curl -X POST http://localhost:7001/shacl/validate-inline \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "shapes_format": "turtle",
    "shapes": "@prefix sh: <http://www.w3.org/ns/shacl#> ...",
    "data_format": "turtle",
    "data": "@prefix schema: <http://schema.org/> ..."
  }'

Validate-Before-Write¶

IndentiaDB can enforce SHACL validation on every SPARQL INSERT operation. When enabled, the engine validates the incoming triples against all loaded shapes before committing them to the store. If any violation with severity sh:Violation is found, the INSERT is rejected and the full validation report is returned as an error.

Enable via Configuration¶

[shacl]
enabled             = true
validate_on_insert  = true      # reject INSERTs that violate loaded shapes
strict_mode         = true      # also reject on sh:Warning (optional)

Enable via REST¶

curl -X PUT http://localhost:7001/shacl/config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "validate_on_insert": true,
    "strict_mode": false
  }'

When validate_on_insert is active, a SPARQL INSERT that would create invalid data returns HTTP 422:

curl -X POST http://localhost:7001/sparql \
  -H "Content-Type: application/sparql-update" \
  -H "Authorization: Bearer $TOKEN" \
  -d 'INSERT DATA {
    <http://example.org/person/new> a <http://schema.org/Person> .
  }'

{
  "error": "SHACL validation failed",
  "conforms": false,
  "results": [
    {
      "focusNode": "http://example.org/person/new",
      "resultPath": "http://schema.org/name",
      "sourceConstraintComponent": "http://www.w3.org/ns/shacl#MinCountConstraintComponent",
      "resultMessage": "Every person must have exactly one name (1-200 characters)"
    }
  ]
}

SPARQL Constraints (SHACL 1.2)¶

IndentiaDB supports SPARQL-based constraints from the SHACL 1.2 draft. These let you write arbitrary SPARQL SELECT queries as validation rules:

ex:UniqueEmailShape
    a sh:NodeShape ;
    sh:targetClass schema:Person ;
    sh:sparql [
        sh:message "Email address must be unique across all persons" ;
        sh:select """
            SELECT $this (schema:email AS ?path) ?value
            WHERE {
                $this schema:email ?value .
                ?other schema:email ?value .
                FILTER(?other != $this)
            }
        """ ;
    ] .

Each solution returned by the SELECT query is treated as one constraint violation. The query receives $this bound to the current focus node.

Validation Reports as RDF¶

Validation reports can be serialized to RDF quads using the standard SHACL vocabulary, making them queryable with SPARQL:

curl -X POST http://localhost:7001/shacl/validate \
  -H "Accept: text/turtle" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "graph": "http://example.org/data" }'

_:report0 a sh:ValidationReport ;
    sh:conforms "false"^^xsd:boolean ;
    sh:result _:result0 .

_:result0 a sh:ValidationResult ;
    sh:focusNode <http://example.org/person/99> ;
    sh:resultPath schema:name ;
    sh:sourceShape <http://example.org/shapes/PersonNameShape> ;
    sh:sourceConstraintComponent sh:MinCountConstraintComponent ;
    sh:resultSeverity sh:Violation ;
    sh:resultMessage "Every person must have exactly one name (1-200 characters)" .

You can also persist reports to the store for audit purposes:

curl -X POST http://localhost:7001/shacl/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "graph": "http://example.org/data",
    "persist_report": true,
    "report_graph": "http://example.org/validation-reports"
  }'

SurrealDB Schema for SHACL Storage¶

The SHACL engine persists shape definitions and validation history in three SurrealDB tables:

Indexes:

Query validation history with SurrealQL:

-- List recent validation runs
SELECT validation_id, conforms, results_count, created_at
FROM shacl_validation
ORDER BY created_at DESC
LIMIT 10;

-- Get all violations for a specific node
SELECT *
FROM shacl_result
WHERE focus_node = "http://example.org/person/99"
  AND severity = "http://www.w3.org/ns/shacl#Violation"
ORDER BY created_at DESC;

Configuration¶

Server Configuration (TOML)¶

[shacl]
# Enable the SHACL validation engine
enabled = true

# Reject SPARQL INSERTs that violate loaded shapes
validate_on_insert = false

# Also reject on sh:Warning (not just sh:Violation)
strict_mode = false

# Validation timeout per run (seconds)
timeout = 10

# Maximum recursion depth for nested shapes (sh:node, logical constraints)
max_shape_depth = 16

# Maximum focus nodes validated per shape
max_focus_nodes = 100000

# Maximum value nodes returned by a property path evaluation
max_value_nodes = 10000

# Maximum graph expansion steps for repetition paths (*, +)
max_path_steps = 50000

# Maximum validation results per report
max_results = 10000

# Include warnings and infos in the report
include_warnings = true
include_infos = true

# Optional named graph filter (validate only this graph)
# graph_iri = "http://example.org/data"

Configuration Reference¶

Python Client Example¶

import requests

BASE_URL = "http://localhost:7001"
HEADERS = {"Authorization": "Bearer <token>"}

# 1. Load shapes
shapes_ttl = """
@prefix sh:     <http://www.w3.org/ns/shacl#> .
@prefix schema: <http://schema.org/> .
@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .
@prefix ex:     <http://example.org/shapes/> .

ex:PersonShape
    a sh:NodeShape ;
    sh:targetClass schema:Person ;
    sh:property [
        sh:path schema:name ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
        sh:datatype xsd:string ;
    ] ;
    sh:property [
        sh:path schema:email ;
        sh:minCount 1 ;
        sh:pattern "^[^@]+@[^@]+$" ;
    ] .
"""

resp = requests.post(
    f"{BASE_URL}/shacl/shapes",
    headers={**HEADERS, "Content-Type": "text/turtle"},
    data=shapes_ttl,
)
print(f"Loaded shapes: {resp.json()}")

# 2. Insert some data
insert_sparql = """
INSERT DATA {
    <http://example.org/person/1> a <http://schema.org/Person> ;
        <http://schema.org/name> "Alice" ;
        <http://schema.org/email> "alice@example.org" .
    <http://example.org/person/2> a <http://schema.org/Person> ;
        <http://schema.org/email> "not-an-email" .
}
"""

requests.post(
    f"{BASE_URL}/sparql",
    headers={**HEADERS, "Content-Type": "application/sparql-update"},
    data=insert_sparql,
)

# 3. Validate
resp = requests.post(
    f"{BASE_URL}/shacl/validate",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"shapes": ["http://example.org/shapes/PersonShape"]},
)

report = resp.json()
if report["conforms"]:
    print("All data conforms to shapes")
else:
    print(f"Found {len(report['results'])} violation(s):")
    for r in report["results"]:
        print(f"  - {r['focusNode']}: {r.get('resultMessage', 'constraint violated')}")

Shape Format Support¶

The SHACL parser accepts shapes in multiple RDF serialization formats:

Interpreting Validation Reports¶

Each ValidationResult in a report contains the following fields:

Common constraint component IRIs:

Performance Considerations¶

• Shape complexity: Shapes with deep nesting (sh:node referencing shapes with their own sh:node) multiply the validation cost. Keep nesting depth below 4-5 levels for interactive workloads.
• Broad targets: sh:targetClass on a class with millions of instances validates every instance. Use max_focus_nodes to cap this, or prefer sh:targetNode for spot-checks.
• Repetition paths: sh:zeroOrMorePath and sh:oneOrMorePath perform BFS traversal and can visit the entire graph. The max_path_steps limit prevents runaway expansion.
• SPARQL constraints: Custom SPARQL queries run against the full data graph. Index the predicates used in your constraint queries for best performance.
• Batch validation: When loading large datasets, disable validate_on_insert, load all data, then run a single validation pass. This is orders of magnitude faster than per-triple validation.