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

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.

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): 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): 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 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:

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)
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:

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:

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:

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:

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:

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 provides the validate_shacl function for checking RDF graphs against SHACL constraints.
• SHACLGenerator in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}