org.eclipse.rdf4j.sail.shacl

Class ShaclSail

java.lang.Object

org.eclipse.rdf4j.sail.helpers.SailWrapper

org.eclipse.rdf4j.sail.helpers.NotifyingSailWrapper

org.eclipse.rdf4j.sail.shacl.ShaclSail

All Implemented Interfaces:

FederatedServiceResolverClient, NotifyingSail, Sail, StackableSail

public class ShaclSail
extends NotifyingSailWrapper

A Sail implementation that adds support for the Shapes Constraint Language (SHACL).

The ShaclSail looks for SHACL shape data in a special named graph RDF4J.SHACL_SHAPE_GRAPH.

Working example

 import ch.qos.logback.classic.Level;
 import ch.qos.logback.classic.Logger;
 import org.eclipse.rdf4j.model.Model;
 import org.eclipse.rdf4j.model.vocabulary.RDF4J;
 import org.eclipse.rdf4j.repository.RepositoryException;
 import org.eclipse.rdf4j.repository.sail.SailRepository;
 import org.eclipse.rdf4j.repository.sail.SailRepositoryConnection;
 import org.eclipse.rdf4j.rio.RDFFormat;
 import org.eclipse.rdf4j.rio.Rio;
 import org.eclipse.rdf4j.sail.memory.MemoryStore;
 import org.eclipse.rdf4j.sail.shacl.ShaclSail;
 import org.eclipse.rdf4j.sail.shacl.ShaclSailValidationException;
 import org.eclipse.rdf4j.sail.shacl.results.ValidationReport;
 import org.slf4j.LoggerFactory;

 import java.io.IOException;
 import java.io.StringReader;

 public class ShaclSampleCode {

        public static void main(String[] args) throws IOException {

                ShaclSail shaclSail = new ShaclSail(new MemoryStore());

                // Logger root = (Logger) LoggerFactory.getLogger(ShaclSail.class.getName());
                // root.setLevel(Level.INFO);

                // shaclSail.setLogValidationPlans(true);
                // shaclSail.setGlobalLogValidationExecution(true);
                // shaclSail.setLogValidationViolations(true);

                SailRepository sailRepository = new SailRepository(shaclSail);
                sailRepository.init();

                try (SailRepositoryConnection connection = sailRepository.getConnection()) {

                        connection.begin();

                        StringReader shaclRules = new StringReader(String.join("\n", "",
                                        "@prefix ex: <http://example.com/ns#> .", "@prefix sh: <http://www.w3.org/ns/shacl#> .",
                                        "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",
                                        "@prefix foaf: <http://xmlns.com/foaf/0.1/>.",

                                        "ex:PersonShape", "      a sh:NodeShape  ;", " sh:targetClass foaf:Person ;",
                                        "  sh:property ex:PersonShapeProperty .",

                                        "ex:PersonShapeProperty ", "     sh:path foaf:age ;", "        sh:datatype xsd:int ;",
                                        "  sh:maxCount 1 ;", "   sh:minCount 1 ."));

                        connection.add(shaclRules, "", RDFFormat.TURTLE, RDF4J.SHACL_SHAPE_GRAPH);
                        connection.commit();

                        connection.begin();

                        StringReader invalidSampleData = new StringReader(String.join("\n", "",
                                        "@prefix ex: <http://example.com/ns#> .", "@prefix foaf: <http://xmlns.com/foaf/0.1/>.",
                                        "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",

                                        "ex:peter a foaf:Person ;", "    foaf:age 20, \"30\"^^xsd:int  ."

                        ));

                        connection.add(invalidSampleData, "", RDFFormat.TURTLE);
                        try {
                                connection.commit();
                        } catch (RepositoryException exception) {
                                Throwable cause = exception.getCause();
                                if (cause instanceof ShaclSailValidationException) {
                                        ValidationReport validationReport = ((ShaclSailValidationException) cause).getValidationReport();
                                        Model validationReportModel = ((ShaclSailValidationException) cause).validationReportAsModel();
                                        // use validationReport or validationReportModel to understand validation violations

                                        Rio.write(validationReportModel, System.out, RDFFormat.TURTLE);
                                }
                                throw exception;
                        }
                }
        }
 }
 

Author:

Heshan Jayasinghe, Håvard Ottestad

See Also:

SHACL W3C Recommendation

Constructor Summary

Constructors

Constructor and Description
ShaclSail()
ShaclSail(NotifyingSail baseSail)

Method Summary

Modifier and Type	Method and Description
void	disableValidation() Disable the SHACL validation on commit()
void	enableValidation() Enabled the SHACL validation on commit()
NotifyingSailConnection	getConnection() Opens a connection on the Sail which can be used to query and update data.
static List<IRI>	getSupportedShaclPredicates() Lists the predicates that have been implemented in the ShaclSail.
void	initialize() Initializes the Sail.
boolean	isCacheSelectNodes() Check if selected nodes caches is enabled.
boolean	isGlobalLogValidationExecution() Check if logging of every execution steps is enabled.
boolean	isIgnoreNoShapesLoadedException()
boolean	isLogValidationPlans() Check if logging of validation plans is enabled.
boolean	isLogValidationViolations() Check if logging a list of violations and the triples that caused the violations is enabled.
boolean	isParallelValidation() Check if SHACL validation is run in parellel.
boolean	isRdfsSubClassReasoning()
boolean	isUndefinedTargetValidatesAllSubjects() Check if NodeShapes without a defined target are considered wildcards.
boolean	isValidationEnabled() Check if SHACL validation on commit() is enabled.
void	setCacheSelectNodes(boolean cacheSelectNodes) The ShaclSail retries a lot of its relevant data through running SPARQL Select queries against the underlying sail and against the changes in the transaction.
void	setGlobalLogValidationExecution(boolean loggingEnabled) Log (INFO) every execution step of the SHACL validation.
void	setIgnoreNoShapesLoadedException(boolean ignoreNoShapesLoadedException) Check if shapes have been loaded into the shapes graph before other data is added
void	setLogValidationPlans(boolean logValidationPlans) Log (INFO) the executed validation plans as GraphViz DOT Recommended to disable parallel validation with setParallelValidation(false)
void	setLogValidationViolations(boolean logValidationViolations) Log (INFO) a list of violations and the triples that caused the violations (BETA).
void	setParallelValidation(boolean parallelValidation) EXPERIMENTAL! Run SHACL validation in parallel.
void	setRdfsSubClassReasoning(boolean rdfsSubClassReasoning)
void	setUndefinedTargetValidatesAllSubjects(boolean undefinedTargetValidatesAllSubjects) If no target is defined for a NodeShape, that NodeShape will be ignored.
void	shutDown() Shuts down the Sail, giving it the opportunity to synchronize any stale data.

Methods inherited from class org.eclipse.rdf4j.sail.helpers.NotifyingSailWrapper

addSailChangedListener, getBaseSail, removeSailChangedListener, setBaseSail

Methods inherited from class org.eclipse.rdf4j.sail.helpers.SailWrapper

getDataDir, getDefaultIsolationLevel, getSupportedIsolationLevels, getValueFactory, isWritable, setDataDir, setFederatedServiceResolver, verifyBaseSailSet

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.eclipse.rdf4j.sail.Sail

getDataDir, getDefaultIsolationLevel, getSupportedIsolationLevels, getValueFactory, init, isWritable, setDataDir

Constructor Detail

ShaclSail

public ShaclSail(NotifyingSail baseSail)

ShaclSail

public ShaclSail()

Method Detail

getSupportedShaclPredicates

public static List<IRI> getSupportedShaclPredicates()

Lists the predicates that have been implemented in the ShaclSail. All of these, and all combinations, should work, please report any bugs. For sh:path, only single predicate paths are supported.

Returns:

List of IRIs (SHACL predicates)

initialize

public void initialize()
                throws SailException

Description copied from interface: Sail

Initializes the Sail. Care should be taken that required initialization parameters have been set before this method is called. Please consult the specific Sail implementation for information about the relevant parameters.

Specified by:

initialize in interface Sail

Overrides:

initialize in class SailWrapper

Throws:

SailException - If the Sail could not be initialized.

shutDown

public void shutDown()
              throws SailException

Description copied from interface: Sail

Shuts down the Sail, giving it the opportunity to synchronize any stale data. Care should be taken that all initialized Sails are being shut down before an application exits to avoid potential loss of data. Once shut down, a Sail can no longer be used until it is re-initialized.

Specified by:

shutDown in interface Sail

Overrides:

shutDown in class SailWrapper

Throws:

SailException - If the Sail object encountered an error or unexpected situation internally.

getConnection

public NotifyingSailConnection getConnection()
                                      throws SailException

Description copied from interface: Sail

Opens a connection on the Sail which can be used to query and update data. Depending on how the implementation handles concurrent access, a call to this method might block when there is another open connection on this Sail.

Specified by:

getConnection in interface NotifyingSail

Specified by:

getConnection in interface Sail

Overrides:

getConnection in class NotifyingSailWrapper

Throws:

SailException - If no transaction could be started, for example because the Sail is not writable.

disableValidation

public void disableValidation()

Disable the SHACL validation on commit()

enableValidation

public void enableValidation()

Enabled the SHACL validation on commit()

isValidationEnabled

public boolean isValidationEnabled()

Check if SHACL validation on commit() is enabled.

Returns:

true if validation is enabled, false otherwise.

isLogValidationPlans

public boolean isLogValidationPlans()

Check if logging of validation plans is enabled.

Returns:

true if validation plan logging is enabled, false otherwise.

isIgnoreNoShapesLoadedException

public boolean isIgnoreNoShapesLoadedException()

setIgnoreNoShapesLoadedException

public void setIgnoreNoShapesLoadedException(boolean ignoreNoShapesLoadedException)

Check if shapes have been loaded into the shapes graph before other data is added

Parameters:

ignoreNoShapesLoadedException -

setLogValidationPlans

public void setLogValidationPlans(boolean logValidationPlans)

Log (INFO) the executed validation plans as GraphViz DOT Recommended to disable parallel validation with setParallelValidation(false)

Parameters:

logValidationPlans -

setGlobalLogValidationExecution

public void setGlobalLogValidationExecution(boolean loggingEnabled)

Log (INFO) every execution step of the SHACL validation. This is fairly costly and should not be used in production. Recommended to disable parallel validation with setParallelValidation(false)

Parameters:

loggingEnabled -

isGlobalLogValidationExecution

public boolean isGlobalLogValidationExecution()

Check if logging of every execution steps is enabled.

Returns:

true if enabled, false otherwise.

See Also:

setGlobalLogValidationExecution(boolean)

isLogValidationViolations

public boolean isLogValidationViolations()

Check if logging a list of violations and the triples that caused the violations is enabled. It is recommended to disable parallel validation with setParallelValidation(boolean)

See Also:

setLogValidationViolations(boolean)

setLogValidationViolations

public void setLogValidationViolations(boolean logValidationViolations)

Log (INFO) a list of violations and the triples that caused the violations (BETA). Recommended to disable parallel validation with setParallelValidation(false)

Parameters:

logValidationViolations -

setUndefinedTargetValidatesAllSubjects

public void setUndefinedTargetValidatesAllSubjects(boolean undefinedTargetValidatesAllSubjects)

If no target is defined for a NodeShape, that NodeShape will be ignored. Calling this method with "true" will make such NodeShapes wildcard shapes and validate all subjects. Equivalent to setting sh:targetClass to owl:Thing or rdfs:Resource in an environment with a reasoner.

Parameters:

undefinedTargetValidatesAllSubjects - default false

isUndefinedTargetValidatesAllSubjects

public boolean isUndefinedTargetValidatesAllSubjects()

Check if NodeShapes without a defined target are considered wildcards.

Returns:

true if enabled, false otherwise

See Also:

setUndefinedTargetValidatesAllSubjects(boolean)

isParallelValidation

public boolean isParallelValidation()

Check if SHACL validation is run in parellel.

Returns:

true if enabled, false otherwise.

setParallelValidation

public void setParallelValidation(boolean parallelValidation)

EXPERIMENTAL! Run SHACL validation in parallel. Default: false

May cause deadlock, especially when using NativeStore.

Parameters:

parallelValidation - default false

isCacheSelectNodes

public boolean isCacheSelectNodes()

Check if selected nodes caches is enabled.

Returns:

true if enabled, false otherwise.

See Also:

setCacheSelectNodes(boolean)

setCacheSelectNodes

public void setCacheSelectNodes(boolean cacheSelectNodes)

The ShaclSail retries a lot of its relevant data through running SPARQL Select queries against the underlying sail and against the changes in the transaction. This is usually good for performance, but while validating large amounts of data disabling this cache will use less memory. Default: true

Parameters:

cacheSelectNodes - default true

isRdfsSubClassReasoning

public boolean isRdfsSubClassReasoning()

setRdfsSubClassReasoning

public void setRdfsSubClassReasoning(boolean rdfsSubClassReasoning)