# How to Validate Knowledge Graphs against SHACL Shapes using Semantica's OntologyValidator

> Learn to validate knowledge graphs against SHACL shapes using Semantica's OntologyValidator. Easily check RDF data and get detailed violation reports with pySHACL.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-17

---

**The OntologyValidator in semantica-agi/semantica uses pySHACL to check RDF data against SHACL constraints, returning a structured report of violations via the `validate_shacl` function in [`semantica/ontology/ontology_validator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_validator.py).**

The semantica-agi/semantica repository provides a robust framework for ontology management and validation. When you need to validate knowledge graphs against SHACL shapes using OntologyValidator, the library leverages the pySHACL engine to parse constraints, execute validation, and return detailed violation reports. This integration allows developers to programmatically enforce data quality rules on RDF graphs within Python applications.

## Understanding the Validation Architecture

The validation system consists of two primary modules: the generator that creates SHACL shapes from OWL ontologies, and the validator that executes constraint checking.

### Core Components

**SHACLGenerator** ([`semantica/ontology/ontology_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_generator.py)): Emits SHACL shapes in Turtle, JSON-LD, or N-Triples format from a Semantica OWL ontology dictionary. Supports quality tiers ("basic", "standard", "strict") to control constraint strictness.

**OntologyValidator** ([`semantica/ontology/ontology_validator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_validator.py)): Contains the `validate_shacl` function that orchestrates the validation process. This module integrates directly with pySHACL and rdflib to parse shape graphs and data graphs.

**SHACLValidationReport**: A Pydantic-style container returned by the validator that includes:
- `conforms` (bool): Whether the graph passes all constraints
- `violations` (list): Detailed `SHACLViolation` objects
- `warnings` and `infos`: Optional non-fatal issues

**SHACLViolation**: Represents individual constraint breaches with fields for `focus_node`, `path`, `message`, and severity level.

## The validate_shacl Function

The `validate_shacl` function in [`semantica/ontology/ontology_validator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_validator.py) serves as the primary entry point for validation.

### Function Signature and Parameters

The function accepts the data graph as an rdflib Graph object and the SHACL shapes as a string. It supports resource limits to prevent runaway validation jobs:

```python
report = validate_shacl(
    data_graph=data_graph,
    shacl_str=shacl_turtle,
    max_shacl_triples=5000,
    max_shacl_bytes=2_000_000,
    timeout_seconds=30
)

```

### Validation Execution Flow

Under the hood, `validate_shacl` performs these operations:

1. Parses the SHACL string into an `rdflib.Graph`
2. Parses the target knowledge graph (RDF)
3. Invokes `pyshacl.validate()` with configured timeouts and limits (defined in [`semantica/explorer/routes/ontology.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/explorer/routes/ontology.py))
4. Translates raw pySHACL results into structured `SHACLViolation` objects

## Practical Implementation Examples

### Generating SHACL Shapes from an Ontology

Before validation, you may need to generate shapes from your ontology definition:

```python
import json
from semantica.ontology.ontology_generator import SHACLGenerator

# Load ontology dictionary

with open("my_ontology.json") as f:
    ontology_dict = json.load(f)

# Initialize generator with quality tier

gen = SHACLGenerator(quality_tier="standard")
shacl_graph = gen.generate(ontology_dict)

# Serialize for validation

shacl_turtle = gen.serialize(shacl_graph, format="turtle")

```

### Validating a Knowledge Graph

Once you have your shapes, validate the target graph:

```python
from rdflib import Graph
from semantica.ontology.ontology_validator import validate_shacl

# Load knowledge graph

data_graph = Graph()
data_graph.parse("my_knowledge_graph.ttl", format="turtle")

# Execute validation

report = validate_shacl(
    data_graph=data_graph,
    shacl_str=shacl_turtle,
    max_shacl_triples=10000,
    max_shacl_bytes=5_000_000,
    timeout_seconds=60
)

# Check conformance

if not report.conforms:
    for violation in report.violations:
        print(f"Node: {violation.focus_node}")
        print(f"Path: {violation.path}")
        print(f"Message: {violation.message}")

```

### Using Custom SHACL Shapes

If you have existing shape definitions, bypass the generator:

```python
with open("custom_shapes.ttl") as f:
    custom_shacl = f.read()

report = validate_shacl(
    data_graph=data_graph, 
    shacl_str=custom_shacl
)

```

### Handling Resource Limits and Timeouts

For production workloads, configure protective limits to prevent excessive resource consumption:

```python
report = validate_shacl(
    data_graph=data_graph,
    shacl_str=shacl_turtle,
    max_shacl_triples=10000,   # Abort if shapes exceed triple count

    max_shacl_bytes=5_000_000,  # Abort if shape file exceeds 5MB

    timeout_seconds=60          # Abort after 1 minute

)

```

The function raises `ProcessingError` when dependencies are missing or limits are exceeded.

### Complete End-to-End Workflow

This example demonstrates the full pipeline from ontology to validation report:

```python
import json
from rdflib import Graph
from semantica.ontology.ontology_generator import SHACLGenerator
from semantica.ontology.ontology_validator import validate_shacl

# Step 1: Generate SHACL from ontology

with open("ontology.json") as f:
    ontology = json.load(f)

generator = SHACLGenerator(quality_tier="strict")
shacl_graph = generator.generate(ontology)
shacl_turtle = generator.serialize(shacl_graph, format="turtle")

# Step 2: Load target knowledge graph

kg = Graph()
kg.parse("knowledge_graph.ttl", format="turtle")

# Step 3: Validate

report = validate_shacl(
    data_graph=kg,
    shacl_str=shacl_turtle,
    max_shacl_triples=5000,
    timeout_seconds=20
)

# Step 4: Process results

print("Conforms:", report.conforms)
for violation in report.violations:
    print(f"{violation.focus_node} - {violation.path}: {violation.message}")

```

## Interpreting Validation Results

The `SHACLValidationReport` object provides structured access to validation outcomes. The `conforms` boolean indicates overall success, while the `violations` list contains detailed `SHACLViolation` instances. Each violation specifies the `focus_node` (the violating resource), the `path` (the property or constraint), and a human-readable `message`. The report also includes `warnings` and `infos` collections for non-fatal issues that do not prevent conformance.

## Summary

- The **OntologyValidator** in [`semantica/ontology/ontology_validator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_validator.py) provides the `validate_shacl` function for checking RDF graphs against SHACL constraints.
- **SHACLGenerator** in [`semantica/ontology/ontology_generator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ontology/ontology_generator.py) creates shapes from OWL ontologies with configurable quality tiers (basic, standard, strict).
- Validation returns a **SHACLValidationReport** containing conformance status and detailed **SHACLViolation** objects with focus nodes, paths, and messages.
- Resource limits (`max_shacl_triples`, `max_shacl_bytes`, `timeout_seconds`) protect against runaway validation jobs.
- The implementation relies on **pySHACL** and **rdflib** for parsing and constraint checking.

## Frequently Asked Questions

### What Python dependencies does OntologyValidator require?

The validator requires **pySHACL** and **rdflib** to parse RDF graphs and execute SHACL validation. If these dependencies are missing, `validate_shacl` raises a `ProcessingError` indicating that the required libraries are not installed.

### Can I validate large knowledge graphs with OntologyValidator?

Yes, but you should configure the resource limit parameters. Set `max_shacl_triples`, `max_shacl_bytes`, and `timeout_seconds` when calling `validate_shacl` to prevent memory exhaustion or hanging processes. For extremely large graphs, consider splitting validation into smaller batches.

### How do I interpret the quality tiers in SHACLGenerator?

The **quality tiers** control constraint strictness: "basic" generates minimal constraints, "standard" follows typical OWL-to-SHACL mappings, and "strict" produces comprehensive constraints that enforce full ontological compliance. Choose "strict" for data quality enforcement and "basic" for lightweight validation.

### Where can I find test examples for validation workflows?

The file [`tests/ontology/test_ontology_advanced.py`](https://github.com/semantica-agi/semantica/blob/main/tests/ontology/test_ontology_advanced.py) contains unit tests demonstrating both SHACL generation and validation patterns. These tests illustrate expected usage patterns for the `validate_shacl` function and `SHACLGenerator` class, serving as a reference for implementation.