SHACL Example

The following example data graph contains three SHACL instances of the class ex:Person.

ex:Alice
	a ex:Person ;
	ex:ssn "987-65-432A" .
  
ex:Bob
	a ex:Person ;
	ex:ssn "123-45-6789" ;
	ex:ssn "124-35-6789" .
  
ex:Calvin
	a ex:Person ;
	ex:birthDate "1971-07-07"^^xsd:date ;
	ex:worksFor ex:UntypedCompany .

The following conditions are shown in the example:

• A SHACL instance of ex:Person can have at most one value for the property ex:ssn, and this value is a literal with the datatype xsd:string that matches a specified regular expression.
• A SHACL instance of ex:Person can have unlimited values for the property ex:worksFor, and these values are IRIs and SHACL instances of ex:Company.
• A SHACL instance of ex:Person cannot have values for any other property apart from ex:ssn, ex:worksFor and rdf:type.

The aforementioned conditions can be represented as shapes and constraints in the following shapes graph:

ex:PersonShape
	a sh:NodeShape ;
	sh:targetClass ex:Person ;    # Applies to all persons
	sh:property [                 # _:b1
		sh:path ex:ssn ;           # constrains the values of ex:ssn
		sh:maxCount 1 ;
		sh:datatype xsd:string ;
		sh:pattern "^\\d{3}-\\d{2}-\\d{4}$" ;
	] ;
	sh:property [                 # _:b2
		sh:path ex:worksFor ;
		sh:class ex:Company ;
		sh:nodeKind sh:IRI ;
	] ;
	sh:closed true ;
	sh:ignoredProperties ( rdf:type ) .

The example below shows the same shape definition as a possible JSON-LD [[json-ld]] fragment. Note that we have left out a @context declaration, and depending on the @context the rendering may look quite different. Therefore this example should be understood as an illustration only.

{
	"@id" : "ex:PersonShape",
	"@type" : "NodeShape",
	"targetClass" : "ex:Person",
	"property" : [
		{
			"path" : "ex:ssn",
			"maxCount" : 1,
			"datatype" : "xsd:string" ,
			"pattern" : "^\\d{3}-\\d{2}-\\d{4}$"
		},
		{
			"path" : "ex:worksFor",
			"class" : "ex:Company",
			"nodeKind" : "sh:IRI"
		}
	],
	"closed" : true,
	"ignoredProperties" : [ "rdf:type" ]
}

We can use the shape declaration above to illustrate some of the key terminology used by SHACL. The target for the shape ex:PersonShape is the set of all SHACL instances of the class ex:Person. This is specified using the property sh:targetClass. During the validation, these target nodes become focus nodes for the shape. The shape ex:PersonShape is a node shape, which means that it applies to the focus nodes. It declares constraints on the focus nodes, for example using the parameters sh:closed and sh:ignoredProperties. The node shape also declares two other constraints with the property sh:property, and each of these is backed by a property shape. These property shapes declare additional constraints using parameters such as sh:datatype and sh:maxCount.

Some of the property shapes specify parameters from multiple constraint components in order to restrict multiple aspects of the property values. For example, in the property shape for ex:ssn, parameters from three constraint components are used. The parameters of these constraint components are sh:datatype, sh:pattern and sh:maxCount. For each focus node the property values of ex:ssn will be validated against all three components.

SHACL validation based on the provided data graph and shapes graph would produce the following validation report. See the section Validation Report for details on the format.

[	a sh:ValidationReport ;
	sh:conforms false ;
	sh:result
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:Alice ;
		sh:resultPath ex:ssn ;
		sh:value "987-65-432A" ;
		sh:sourceConstraintComponent sh:RegexConstraintComponent ;
		sh:sourceShape ... blank node _:b1 on ex:ssn above ... ;
	] ,
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:Bob ;
		sh:resultPath ex:ssn ;
		sh:sourceConstraintComponent sh:MaxCountConstraintComponent ;
		sh:sourceShape ... blank node _:b1 on ex:ssn above ... ;
	] ,
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:Calvin ;
		sh:resultPath ex:worksFor ;
		sh:value ex:UntypedCompany ;
		sh:sourceConstraintComponent sh:ClassConstraintComponent ;
		sh:sourceShape ... blank node _:b2 on ex:worksFor above ... ;
	] ,
	[	a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:Calvin ;
		sh:resultPath ex:birthDate ;
		sh:value "1971-07-07"^^xsd:date ;
		sh:sourceConstraintComponent sh:ClosedConstraintComponent ;
		sh:sourceShape sh:PersonShape ;
	] 
] .

The validation results are enclosed in a validation report. The first validation result is produced because ex:Alice has a value for ex:ssn that does not match the regular expression specified by the property sh:regex. The second validation result is produced because ex:Bob has more than the permitted number of values for the property ex:ssn as specified by the sh:maxCount of 1. The third validation result is produced because ex:Calvin has a value for ex:worksFor that does not have an rdf:type triple that makes it a SHACL instance of ex:Company. The forth validation result is produced because the shape ex:PersonShape has the property sh:closed set to true but ex:Calvin uses the property ex:birthDate which is neither one of the predicates from any of the property shapes of the shape, nor one of the properties listed using sh:ignoredProperties.

Relationship between SHACL and SPARQL

For SHACL Core this specification uses parts of SPARQL 1.1 in non-normative alternative definitions of the semantics of constraint components and targets. While these may help some implementers, SPARQL is not required for the implementation of the SHACL Core language.

SHACL-SPARQL is based on SPARQL 1.1 and uses it as a mechanism to declare constraints and constraint components. Implementations that cover only the SHACL Core features are not required to implement these mechanisms.

SPARQL variables using the $ marker represent external bindings that are pre-bound or, in the case of $PATH, substituted in the SPARQL query before execution (as explained in ).

The definition of some constraints requires or is simplified through access to the shapes graph during query execution. SHACL-SPARQL processors MAY pre-bind the variable shapesGraph to provide access to the shapes graph. Access to the shapes graph is not a requirement for supporting the SHACL Core language. The variable shapesGraph can also be used in SPARQL-based constraints and SPARQL-based constraint components. However, such constraints may not be interoperable across different SHACL-SPARQL processors or not applicable to remote RDF datasets.

Note that at the time of writing, SPARQL EXISTS has been imperfectly defined and implementations vary. While a W3C Community Group is working on improving this situation, users of SPARQL are advised that the use of EXISTS may have inconsistent results and should be approached with care.

An Example SPARQL-based Constraint

The following example illustrates the syntax of a SPARQL-based constraint.

ex:ValidCountry a ex:Country ;
	ex:germanLabel "Spanien"@de .
  
ex:InvalidCountry a ex:Country ;
	ex:germanLabel "Spain"@en .

ex:LanguageExampleShape
	a sh:NodeShape ;
	sh:targetClass ex:Country ;
	sh:sparql [
		a sh:SPARQLConstraint ;   # This triple is optional
		sh:message "Values are literals with German language tag." ;
		sh:prefixes ex: ;
		sh:select """
			SELECT $this (ex:germanLabel AS ?path) ?value
			WHERE {
				$this ex:germanLabel ?value .
				FILTER (!isLiteral(?value) || !langMatches(lang(?value), "de"))
			}
			""" ;
	] .

The target of the shape above includes all SHACL instances of ex:Country. For those nodes (represented by the variable this), the SPARQL query walks through the values of ex:germanLabel and verifies that they are literals with a German language code. The validation results for the aforementioned data graph is shown below:

[	a sh:ValidationReport ;
	sh:conforms false ;
	sh:result [
		a sh:ValidationResult ;
		sh:resultSeverity sh:Violation ;
		sh:focusNode ex:InvalidCountry ;
		sh:resultPath ex:germanLabel ;
		sh:value "Spain"@en ;
		sh:sourceConstraintComponent sh:SPARQLConstraintComponent ;
		sh:sourceShape ex:LanguageExampleShape ;
		# ...
	]
] .

The SPARQL query returns result set solutions for all bindings of the variable value that violate the constraint. There is a validation result for each solution in that result set, applying the mapping rules explained later. In this example, each validation result will have the binding for the variable this as the sh:focusNode, ex:germanLabel as sh:resultPath and the violating value as sh:value.

The following example illustrates a similar scenario as above, but with a property shape.

ex:LanguageExamplePropertyShape
	a sh:PropertyShape ;
	sh:targetClass ex:Country ;
	sh:path ex:germanLabel ;
	sh:sparql [
		a sh:SPARQLConstraint ;   # This triple is optional
		sh:message "Values are literals with German language tag." ;
		sh:prefixes ex: ;
		sh:select """
			SELECT $this ?value
			WHERE {
				$this $PATH ?value .
				FILTER (!isLiteral(?value) || !langMatches(lang(?value), "de"))
			}
			""" ;
	] .

An Example SPARQL-based Constraint Component

The following example demonstrates how SPARQL can be used to specify new constraint components using the SHACL-SPARQL language. The example implements sh:pattern and sh:flags using a SPARQL ASK query to validate that each value node matches a given regular expression. Note that this is only an example implementation and should not be considered normative.

sh:PatternConstraintComponent
	a sh:ConstraintComponent ;
	sh:parameter [
		sh:path sh:pattern ;
	] ;
	sh:parameter [
		sh:path sh:flags ;
		sh:optional true ;
	] ;
	sh:validator shimpl:hasPattern .

shimpl:hasPattern
	a sh:SPARQLAskValidator ;
	sh:message "Value does not match pattern {$pattern}" ;
	sh:ask """
		ASK { 
			FILTER (!isBlank($value) && 
				IF(bound($flags), regex(str($value), $pattern, $flags), regex(str($value), $pattern)))
		}""" .

Constraint components provide instructions to validation engines on how to identify and validate constraints within a shape. In general, if a shape S has a value for a property p, and there is a constraint component C that specifies p as a parameter, and S has values for all mandatory parameters of C, then the set of these parameter values (including the optional parameters) declare a constraint and the validation engine uses a suitable validator from C to perform the validation of this constraint. In the example above, sh:PatternConstraintComponent declares the mandatory parameter sh:pattern, the optional parameter sh:flags, and a validator that can be used to perform validation against either node shapes or property shapes.