pySHACL

PySHACL (v0.27.0+) allows highly targeted validation using two features:

1. Focus Node Filtering: Pass a list of specific focus nodes to validate only those nodes. The shapes must still target these nodes, but the validator will filter the shapes' targets to match your list.
2. SHACL Shape Selection: Pass a list of specific SHACL Shapes to use for validation. This is useful for testing specific shapes within a larger graph.
3. Combined Mode: If you provide both a list of Shapes and a list of focus nodes, the validator operates in a highly-targeted mode, feeding the focus nodes directly into the selected shapes. In this mode, the selected shapes do not need to specify their own focus-targeting mechanisms.

Depending on your needs, you can validate multiple graphs in two ways:

1. Combine Mode (Default): Validates all graphs as a single combined dataset.
2. Independent Mode: Validates each graph separately using validate_each.

# Combine mode (default)
from pyshacl import validate

data_graphs = ["data1.ttl", "data2.ttl", "data3.ttl"]
conforms, results_graph, results_text = validate(data_graphs, shacl_graph="shapes.ttl")

# Independent mode
from pyshacl import validate_each

data_graphs = ["data1.ttl", "data2.ttl", "data3.ttl"]
results = validate_each(data_graphs, shacl_graph="shapes.ttl")
for graph_id, (conforms, results_graph, results_text) in results.items():
    print(graph_id, conforms)

SHACL-JS features (Javascript-based constraints, functions, rules, and targets) are implemented as a Python "extras" feature. To use these advanced features, you must install PySHACL using PIP with the js extra included.

pip install pyshacl[js]

pySHACL is a Python 3 library. Ensure your environment meets the following requirements:

• Python Version: Python v3.8 or greater is recommended. Python 3.7 and below are not supported. Python 2.7.x and below are not supported.
• pip Version: If installing from PyPI via pip, use pip v20.0.2 or above for best compatibility. On older systems like Ubuntu 18.04, you may need to upgrade pip manually.

# Upgrade pip if on an older system (e.g., Ubuntu 18.04)
sudo pip3 install --upgrade pip

You can run pySHACL inside a container by pulling the official image from Dockerhub or building it from the repository. When running the container, you must mount the local directory containing your data to a destination inside the container (e.g., /data) to access your RDF files.

To pull the image: docker pull docker.io/ashleysommer/pyshacl:latest

To build the image locally: docker build . -t pyshacl

# Pull the official image
docker pull docker.io/ashleysommer/pyshacl:latest

# Build the image locally
docker build . -t pyshacl

# Run validation by mounting the current directory to /data
docker run --rm -i -t --mount type=bind,src=`pwd`,dst=/data pyshacl -s /data/shacl.ttl /data/graph.ttl

Install pySHACL using pip3. It is recommended to use a Python virtual environment.

To install the base package:

pip3 install pyshacl

To enable Oxigraph compatibility (which allows pySHACL to run validation and SHACL Rules against an Oxigraph store backend), install the oxigraph extra:

pip3 install pyshacl[oxigraph]

In pySHACL, target types (which define how to select nodes for validation) are discovered by scanning the ShapesGraph for subjects that are subclasses of sh:Target.

To use custom or built-in target types, you can use gather_target_types to find all valid SHACLTargetType or SPARQLTargetType instances in your shapes graph, and then apply_target_types to register them.

Note: If sh:JSTargetType is found but JavaScript mode is not enabled in the ShapesGraph, those targets are silently ignored. Currently, SPARQLTargetType is the primary implemented target type.

from pyshacl.target import gather_target_types, apply_target_types

# Assuming shacl_graph is your ShapesGraph instance
target_types = gather_target_types(shacl_graph)
apply_target_types(target_types)

When sparql_mode=True is passed to validate(), pySHACL treats the data_graph string as a SPARQL endpoint URL. It will query the endpoint to retrieve the data for validation.

Authentication can be configured via environment variables:

• PYSHACL_SPARQL_USERNAME: Username for SPARQL endpoint authentication.
• PYSHACL_SPARQL_PASSWORD: Password for SPARQL endpoint authentication.
• PYSHACL_SPARQL_METHOD: HTTP method to use (e.g., GET or POST). Defaults to GET.

Limitations of SPARQL Mode:

• Cannot use shacl-js.
• Cannot use inplace=True.
• Cannot use ont_graph (extra ontology inoculation).
• Does not support multiple data graphs.

PySHACL uses DataGraph to abstract away the differences between rdflib and pyoxigraph.

• RdfLib backend: Used when the provided store is an rdflib_Store. It supports locked_context (allowing operations to be scoped to a specific graph within a dataset) and provides standard RDFLib functionality.
• Oxigraph backend: Used when pyoxigraph is installed and an ox_Store is provided. It is optimized for performance but has specific constraints: it does not support Literals or Blank Nodes in the predicate position, and it is not formula-aware (the quoted argument in add is not supported).

When options['advanced'] is set to True, the Validator activates SHACL-AF features, including SHACL Rules and SHACL Functions.

1. Target Types: The validator gathers target types from the shacl_graph and applies them.
2. Functions & Rules: It gathers functions and rules defined in the shapes graph.
3. Execution: During the .run() process, functions are applied to the graph, and rules are executed (if not in sparql_mode).
4. Cleanup: After validation, any applied functions are unapplied to restore the graph state (if not in inplace mode).