Part 1: SHACL Core

2.1.1 Constraints, Parameters and Constraint Components

Shapes can declare constraints using the parameters of constraint components.

A constraint component is an IRI. Each constraint component has one or more mandatory parameters, each of which is a property. Each constraint component has zero or more optional parameters, each of which is a property. The parameters of a constraint component are its mandatory parameters plus its optional parameters.

For example, the component sh:MinCountConstraintComponent declares the parameter sh:minCount to represent the restriction that a node has at least a minimum number of values for a particular property.

For a constraint component C with mandatory parameters p1, ... pn, a shape s in a shapes graph SG declares a constraint that has kind C with mandatory parameter values <p1,v1>, ... <pn,vn> in SG when s has vi as a value for pi in SG. For constraint components with optional parameters, the constraint declaration consists of the values that the shape has for all mandatory and optional parameters of that component.

Some constraint components declare only a single parameter. For example sh:ClassConstraintComponent has the single parameter sh:class. These parameters may be used multiple times in the same shape, and each value of such a parameter declares an individual constraint. The interpretation of such declarations is conjunction, i.e. all constraints apply. The following example specifies that the values of ex:customer have to be SHACL instances of both ex:Customer and ex:Person.

ex:InvoiceShape
	a sh:NodeShape ;
	sh:property [
		sh:path ex:customer ;
		sh:class ex:Customer ;
		sh:class ex:Person ;
	] .

Some constraint components such as sh:PatternConstraintComponent declare more than one parameter. Shapes that have more than one value for any of the parameters of such components are ill-formed.

One way to bypass this syntax rule is to spread the constraints across multiple (property) shapes, as illustrated in the following example.

ex:MultiplePatternsShape
	a sh:NodeShape ;
	sh:property [
		sh:path ex:name ;
		sh:pattern "^Start" ;
		sh:flags "i" ;
	] ;
	sh:property [
		sh:path ex:name ;
		sh:pattern "End$" ;
	] .

Constraint components are associated with validators, which provide instructions (for example expressed via SPARQL queries) on how the parameters are used to validate data. Validating an RDF term against a shape involves validating the term against each constraint where the shape has values for all mandatory parameters of the component of the constraint, using the validators associated with the respective component.

The list of constraint components included in SHACL Core is described in section 4. SHACL-SPARQL can be used to declare additional constraint components based on SPARQL.

2.1.2 Focus Nodes

An RDF term that is validated against a shape using the triples from a data graph is called a focus node.

The remainder of this section is informative.

The set of focus nodes for a shape may be identified as follows:

• specified in a shape using target declarations
• specified in any constraint that references a shape in parameters of shape-expecting constraint parameters (e.g. sh:node)
• specified as explicit input to the SHACL processor for validating a specific RDF term against a shape

2.1.3 Targets

Target declarations of a shape in a shapes graph are triples with the shape as the subject and certain properties described in this document (e.g., sh:targetClass) as predicates. Target declarations can be used to produce focus nodes for a shape. The target of a target declaration is the set of RDF terms produced by applying the rules described in the remainder of this section to the data graph. The target of a shape is the union of all RDF terms produced by the individual targets that are declared by the shape in the shapes graph.

SHACL Core includes the following kinds of targets: node targets, class-based targets (including implicit class-based targets), subjects-of targets, and objects-of targets.

The remainder of this introduction is informative.

RDF terms produced by targets are not required to exist as nodes in the data graph. Targets of a shape are ignored whenever a focus node is provided directly as input to the validation process for that shape. This includes the cases where the shape is a value of one of the shape-expecting constraint parameters (such as sh:node) and a focus node is determined during the validation of the corresponding constraint component (such as sh:NodeConstraintComponent). In such cases, the provided focus node does not need to be in the target of the shape.

ex:PersonShape
	a sh:NodeShape ;
	sh:targetNode ex:Alice .

ex:Alice a ex:Person .
ex:Bob a ex:Person .

SELECT DISTINCT ?this    # ?this is the focus node
WHERE {
	BIND ($targetNode AS ?this)    # $targetNode is pre-bound to ex:Alice
}

ex:PersonShape
	a sh:NodeShape ;
	sh:targetClass ex:Person .

ex:Alice a ex:Person .
ex:Bob a ex:Person .
ex:NewYork a ex:Place .

ex:Doctor rdfs:subClassOf ex:Person .
ex:Who a ex:Doctor .
ex:House a ex:Nephrologist .

SELECT DISTINCT ?this    # ?this is the focus node
WHERE {
	?this rdf:type/rdfs:subClassOf* $targetClass .    # $targetClass is pre-bound to ex:Person
}

ex:Person
	a rdfs:Class, sh:NodeShape .

ex:Alice a ex:Person .
ex:NewYork a ex:Place .

ex:TargetSubjectsOfExampleShape
	a sh:NodeShape ;
	sh:targetSubjectsOf ex:knows .

ex:Alice ex:knows ex:Bob .
ex:Bob ex:livesIn ex:NewYork .

SELECT DISTINCT ?this    # ?this is the focus node
WHERE {
	?this $targetSubjectsOf ?any .    # $targetSubjectsOf is pre-bound to ex:knows
}

ex:TargetObjectsOfExampleShape
	a sh:NodeShape ;
	sh:targetObjectsOf ex:knows .

ex:Alice ex:knows ex:Bob .
ex:Bob ex:livesIn ex:NewYork .

SELECT DISTINCT ?this    # ?this is the focus node
WHERE {
	?any $targetObjectsOf ?this .    # $targetObjectsOf is pre-bound to ex:knows
}

2.1.4 Declaring the Severity of a Shape

Shapes can specify one value for the property sh:severity in the shapes graph. Each value of sh:severity in a shape is an IRI.

The values of sh:severity are called severities. SHACL includes the three IRIs listed in the table below to represent severities. These are declared in the SHACL vocabulary as SHACL instances of sh:Severity.

The remainder of this section is informative.

The specific values of sh:severity have no impact on the validation, but MAY be used by user interface tools to categorize validation results. The values of sh:severity are used by SHACL processors to populate the sh:resultSeverity field of validation results, see section on severity in validation results. Any IRI can be used as a severity.

For every shape, sh:Violation is the default if sh:severity is unspecified. The following example illustrates this.

ex:MyShape
	a sh:NodeShape ;
	sh:targetNode ex:MyInstance ;
	sh:property [    # _:b1
		# Violations of sh:minCount and sh:datatype are produced as warnings
		sh:path ex:myProperty ;
		sh:minCount 1 ;
		sh:datatype xsd:string ;
		sh:severity sh:Warning ;
	] ;
	sh:property [    # _:b2
		# The default severity here is sh:Violation
		sh:path ex:myProperty ;
		sh:maxLength 10 ;
		sh:message "Too many characters"@en ;
		sh:message "Zu viele Zeichen"@de ;
	] .

ex:MyInstance
	ex:myProperty "http://toomanycharacters"^^xsd:anyURI .

[	a sh:ValidationReport ;
	sh:conforms false ;
	sh:result
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Warning ;
		sh:focusNode ex:MyInstance ;
		sh:resultPath ex:myProperty ;
		sh:value "http://toomanycharacters"^^xsd:anyURI ;
		sh:sourceConstraintComponent sh:DatatypeConstraintComponent ;
		sh:sourceShape _:b1 ;
	] ,
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:MyInstance ;
		sh:resultPath ex:myProperty ;
		sh:value "http://toomanycharacters"^^xsd:anyURI ;
		sh:resultMessage "Too many characters"@en ;
		sh:resultMessage "Zu viele Zeichen"@de ;
		sh:sourceConstraintComponent sh:MaxLengthConstraintComponent ;
		sh:sourceShape _:b2 ;
	]
] .

2.1.5 Declaring Messages for a Shape

Shapes can have values for the property sh:message. The values of sh:message in a shape are either xsd:string literals or literals with a language tag. A shape should not have more than one value for sh:message with the same language tag.

If a shape has at least one value for sh:message in the shapes graph, then all validation results produced as a result of the shape will have exactly these messages as their value of sh:resultMessage, i.e. the values will be copied from the shapes graph into the results graph. (Note that in SHACL-SPARQL, SPARQL-based constraints and SPARQL-based constraint components provide additional means to declare such messages.)

The remainder of this section is informative.

The example from the previous section uses this mechanism to supply the second validation result with two messages. See the section on sh:resultMessage in the validation results on further details on how the values of sh:resultMessage are populated.

2.1.6 Deactivating a Shape

Shapes can have at most one value for the property sh:deactivated. The value of sh:deactivated in a shape must be either true or false.

A shape that has the value true for the property sh:deactivated is called deactivated. All RDF terms conform to a deactivated shape.

The remainder of this section is informative.

Use cases of this feature include shape reuse and debugging. In scenarios where shapes from other graphs or files are imported into a given shapes graph, sh:deactivated can be set to true in the local shapes graph for imported shapes to exclude shapes that do not apply in the current application context. This makes it possible to reuse SHACL graphs developed by others even if you disagree with certain assumptions made by the original authors. If a shape author anticipates that a shape may need to be disabled or modified by others, it is a good practice to use IRIs instead of blank nodes for the actual shapes. For example, a property shape for the property ex:name at the shape ex:PersonShape may have the IRI ex:PersonShape-name. Another typical use case of sh:deactivated is during the development and testing of shapes, to (temporarily) disable certain shapes.

The following example illustrates the use of sh:deactivated to deactivate a shape. In cases where shapes are imported from other graphs, the sh:deactivated true triple would be in the importing graph.

ex:PersonShape
	a sh:NodeShape ;
	sh:targetClass ex:Person ;
	sh:property ex:PersonShape-name .

ex:PersonShape-name
	a sh:PropertyShape ;
	sh:path ex:name ;
	sh:minCount 1 ;
	sh:deactivated true .

With the following data, no constraint violation will be reported even though the instance does not have any value for ex:name.

ex:JohnDoe a ex:Person .

2.3.1 SHACL Property Paths

SHACL includes RDF terms to represent the following subset of SPARQL property paths: PredicatePath, InversePath, SequencePath, AlternativePath, ZeroOrMorePath, OneOrMorePath and ZeroOrOnePath.

The following sub-sections provide syntax rules of well-formed SHACL property paths together with mapping rules to SPARQL 1.1 property paths. These rules define the path mapping path(p,G) in an RDF graph G of an RDF term p that is a SHACL property path in G. Two SHACL property paths are considered equivalent paths when they map to the exact same SPARQL property paths.

A node in an RDF graph is a well-formed SHACL property path p if it satisfies exactly one of the syntax rules in the following sub-sections. A node p is not a well-formed SHACL property path if p is a blank node and any path mappings of p directly or transitively reference p.

The following example illustrates some valid SHACL property paths, together with their SPARQL 1.1 equivalents.

SPARQL Property path: ex:parent
SHACL Property path: ex:parent

SPARQL Property path: ^ex:parent
SHACL Property path: [ sh:inversePath ex:parent ]

SPARQL Property path: ex:parent/ex:firstName
SHACL Property path: ( ex:parent ex:firstName )

SPARQL Property path: rdf:type/rdfs:subClassOf*
SHACL Property path: ( rdf:type [ sh:zeroOrMorePath rdfs:subClassOf ] )

SPARQL Property path: ex:father|ex:mother
SHACL Property path: [ sh:alternativePath ( ex:father ex:mother  ) ]

3.4.1 Failures

Validation and conformance checking can result in a failure. For example, a particular SHACL processor might allow recursive shapes but report a failure if it detects a loop within the data. Failures can also be reported due to resource exhaustion. Failures are signalled through implementation-specific channels.

3.4.2 Handling of Ill-formed Shapes Graphs

If the shapes graph contains ill-formed nodes, then the result of the validation process is undefined. A SHACL processor SHOULD produce a failure in this case. See also 3.6.1.3 Syntax Checking of Shapes Graph (sh:shapesGraphWellFormed).

3.4.3 Handling of Recursive Shapes

The following properties are the so-called shape-expecting constraint parameters in SHACL Core:

• sh:and
• sh:not
• sh:or
• sh:property
• sh:qualifiedValueShape
• sh:node
• sh:xone

The following properties are the so-called list-taking constraint parameters in SHACL Core:

• sh:and
• sh:in
• sh:languageIn
• sh:or
• sh:xone

A shape s1 in an RDF graph G refers to shape s2 in G if it has s2 as value for some non-list-taking, shape-expecting parameter of some constraint component or s2 as a member of the value for some list-taking, shape-expecting parameter of some constraint component. A shape in an RDF graph G is a recursive shape in G if it is related to itself by the transitive closure of the refers relationship in G.

The validation with recursive shapes is not defined in SHACL and is left to SHACL processor implementations. For example, SHACL processors may support recursion scenarios or produce a failure when they detect recursion.

The remainder of this section is informative.

The recursion policy above has been selected to support a large variety of implementation strategies. By leaving recursion undefined, implementations may chose to not support recursion so that they can issue a static set of SPARQL queries (against SPARQL end points) without having to support cycles. The Working Group is aware that other implementations may support recursion and that some shapes graphs may rely on these specific characteristics. The expectation is that future work, for example in W3C Community Groups, will lead to the definition of specific dialects of SHACL where recursion is well-defined.

3.6.1 Validation Report (sh:ValidationReport)

The result of a validation process is an RDF graph with exactly one SHACL instance of sh:ValidationReport. The RDF graph MAY contain additional information such as provenance metadata.