1.1 Relationship between SHACL and RDFS

SHACL uses RDF and RDFS vocabulary (in particular rdf:type, rdfs:Class, rdfs:subClassOf, rdf:Property, rdf:List, rdf:langLiteral, and rdfs:Resource) and notions (notably classes, instances, and subclasses). However, SHACL does not always use this vocabulary or these notions in exactly the way that they are formally defined in RDF and RDFS [rdf11-mt].

When determining subclass and instance relationships SHACL only uses the transitive closure of rdfs:subClassOf, ignoring in particular the RDF axioms, the RDFS meaning of rdfs:Resource, the reflexivity of rdfs:subClassOf, the effect of subproperties of rdfs:subClassOf, and the effects of rdfs:domain and rdfs:range.

Note that rdfs:subClassOf transitivity is not uniformly applied throughout SHACL. It is only used when SHACL explicitly determines type and subclass relationships in the shapes graph and the data. In other places only triples that are explicitly present in the shapes graph or the data are considered. For example, SHACL property constraints on rdf:type and rdfs:subClassOf only utilize triples that are explicitly in the data. Similarly, subproperties of rdfs:label and rdfs:commment and subclasses of rdf:List are not recognized in the shapes graph.

These design decisions mean that SHACL processors do not have to natively support full RDFS inferencing. However, SHACL validation engines may operate on RDF graphs that include entailments - either pre-computed before being submitted to a SHACL processor or performed on the fly as part of SHACL processing. To support on the fly processing of entailments, SHACL includes the property sh:entailment to indicate what kind of inferencing is required by a given shapes graph. SHACL implementations may, but are not required to, support entailment regimes.

1.2 Relationship between SHACL and SPARQL

This specification uses SPARQL 1.1 for the normative definition of the semantics of the SHACL Core constraints and scopes. Implementations do not have to use the exact same SPARQL queries, and do not even have to use SPARQL at all. However, all implementation MUST produce the same outputs for the same inputs.

The SPARQL definitions in this document use the convention that the variables starting with $ must be substituted with values that have been passed into the query from the outside, similar to the semantics of a VALUES clause.

In some places, the specification assumes that the provided SPARQL engines are preserving the identity of blank nodes, so that repeated invocations of queries consistently identify and communicate the same blank nodes.

The definition of some constraints require access to a named graph represented with the variable $shapesGraph. Not all implementations (such as those using SPARQL endpoints) may be able to provide this named graph in the same dataset as the executing query. Such implementations may need to find alternative techniques (such as string insertion) leading to equivalent results.

The definition of some constraints assume that SPARQL engines provide a function called sh:hasShape as elaborated in the beginning of section 3. In the advanced sections, SHACL introduces mechanisms to define constraints, scopes and new functions in SPARQL. Implementations that only plan to cover the SHACL Core features are not required to support those mechanisms.

1.3 Namespaces

Within this document, the following namespace prefix bindings are used:

1.4 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].

TODO: We still need to mark non-normative sections.

2.1 Scopes

SHACL shapes can have three kinds of scopes:

• Node scopes link a shape with a specific node via sh:scopeNode.
• Class-based scopes link all instances of a given class with a shape, using sh:scopeClass and rdf:type.
• General scopes define a flexible mechanism to produce arbitrary focus nodes for a given data graph.

If multiple scope definitions are present for a shape then a SHACL processor MUST use the union of the focus nodes produced by those scopes.

ex:PersonShape
	a sh:Shape ;
	sh:scopeNode ex:Alice ;
	sh:constraint [
		...
	] .

ex:Alice
	a rdfs:Resource ;
	...

foaf:Person
	a rdfs:Class .

ex:PersonShape
	a sh:Shape ;
	sh:scopeClass foaf:Person ;
	sh:property [
		sh:predicate foaf:name ;
		sh:minCount 1
	] .

ex:Alice
	rdf:type foaf:Person .

ex:Person
	a rdfs:Class, sh:Shape ;
	sh:scopeClass ex:Person ;
	sh:property [
		...
	] .

ex:Alice
	rdf:type ex:Person .

SELECT ?X
WHERE {
	?X rdf:type/rdfs:subClassOf* sh:Shape .
	?X rdf:type/rdfs:subClassOf* rdfs:Class .
}

SELECT DISTINCT ?this
WHERE {
	?this $predicate ?any .
}

ex:PropertyScopeExampleShape
	a sh:Shape ;
	sh:scope [
		a sh:PropertyScope ;
		sh:predicate ex:property ;
	] ;
	sh:constraint [
		...
	] .

SELECT DISTINCT ?this
WHERE {
	?any $predicate ?this .
}

SELECT DISTINCT ?this
WHERE {
	?this ?anyPredicate ?anyObject .
}

ex:PropertyScopeExampleShape
	a sh:Shape ;
	sh:scope [
		a sh:AllSubjectsScope ;
	] ;
	sh:constraint [
		...
	] .

SELECT DISTINCT ?this
WHERE {
	?anySubject ?anyPredicate ?this .
}

2.2 Filter Shapes

In some cases, constraints should not apply to all focus nodes, produced by a scope. For example, instances of the given class ex:Person that were ex:residentIn the country ex:USA may have a different legal drinking age than others. In order to support such use cases, SHACL includes the concept of filter shapes that act as pre-conditions that all focus nodes need to fulfill before they are being validated. Formally, filter shapes eliminate entries from the collection of focus nodes selected by a shape's scopes, if the focus node produces a validation result with severity sh:Violation or a failure for the given filter shapes.

The following example states that the sh:minCount constraint only applies to resources that have a certain value for ex:requiredProperty.

ex:FilteredExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:minCount 1 ;
		sh:filterShape [
			a sh:Shape ; # Optional triple
			sh:property [
				sh:predicate ex:requiredProperty ;
				sh:hasValue ex:requiredValue ;
			]
		] ;
	] .

ex:FilteredShapeValidExampleInstance
	ex:someProperty ex:someValue ;
	ex:requiredProperty ex:requiredValue .

Alternatively, sh:filterShape can be defined for a whole shape, with the meaning that the filter applies to all constraints defined by the shape, as shown in the following example.

ex:FilteredExampleShape
	a sh:Shape ;
	sh:filterShape [
		sh:property [
			sh:predicate ex:requiredProperty ;
			sh:hasValue ex:requiredValue ;
		]
	] ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:minCount 1 ;
	] .

ex:FilteredShapeValidExampleInstance
	ex:someProperty ex:someValue ;
	ex:requiredProperty ex:requiredValue .

Filters always contribute to the meaning of a shapes. This includes both the computation of scopes and when shapes are directly referenced via sh:valueShape. In general, a filter shape acts like the test condition of an IF-THEN statement. For example, suppose some optional property has a default value. Then a shape might express the constraint that IF the property is present THEN its value must be equal to the default value. In this case the filter would test for the presence of the property and the constraint would test that its value was equal to the default value.

When a SHACL processor validates a focus node against a shape, it begins by validating any filters associated with the shape via sh:filterShape. If any of the filters produce a violation then the processor interprets this as indicating that none of the constraints of the shape are applicable to the focus node and no violations for the shape are reported. Conversely, if none of the filters produce a violation then the processor proceeds to evaluate the constraints and reports any violations produced by them.

Similarly, when a SHACL processor validates a focus node against a constraint, it begins by validating any filters associated with the constraint via sh:filterShape. If any of the filters produce a violation then the processor interprets this as indicating that the constraint is not applicable to the focus node and no violations for the constraint are reported. Conversely, if none of the filters produce a violation then the processor proceeds to evaluate the constraint and reports any violations produced by it.

The following figure illustrates some relationships between core classes of SHACL and RDF Schema. Note that the use of a UML-like notation does not imply that these RDF concepts are classes in an object-oriented sense.

2.3 Constraints

A shape defines a group of constraints. SHACL includes a collection of Core constraint types that are covered in the next section. Additional types of constraints can be added using the extension mechanism.

Shapes can be linked to their constraints via the following properties:

• sh:property links a shape with constraints about a given property of the focus node. These constraints are called property constraints.
• sh:inverseProperty links a shape with constraints about a given property traversed in the inverse direction of the focus node. These constraints are called inverse property constraints.
• sh:constraint link a shape with constraints that do not involve just a single dedicated property. SHACL includes several built-in constraint types such as logical operators.

3.1 Property Constraints (sh:property)

A property constraint is a constraint that defines restrictions on the values of a given property in the context of the focus node. Here, the focus node is the subject and the property is the predicate of relevant triples. The property sh:property can be used to link a shape with its property constraints.

In SHACL, property constraints are instances of the class sh:PropertyConstraint. When used as values of sh:property, property constraints do not require an rdf:type triple. However, if those values are IRIs, then they SHOULD have an rdf:type triple. Note that sh:property may also have values that are sub-classes of sh:PropertyConstraint, but in this case the rdf:type triple is required. It is not valid to use sh:property for constraints that are not instance of sh:PropertyConstraint.

The following examples illustrate two ways of using property constraints. The first example uses a blank node:

ex:InlinePropertyConstraintExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:name "some property" ;
		sh:description "Description of the role of ex:someProperty (in the context of the constraint)" ;
		sh:minCount 1 ;
		sh:class ex:SomeClass ;
	] .

The second example defines a constraint as an IRI node, allowing it to be more easily referenced and shared across multiple shapes:

ex:StandAlonePropertyConstraintExampleShape
	a sh:Shape ;
	sh:property ex:StandAloneConstraint .

ex:StandAloneConstraint
	a sh:PropertyConstraint ;
	sh:predicate ex:someProperty ;
	sh:defaultValue ex:SomeInstance ;
	sh:minCount 1 ;
	sh:class ex:SomeClass .

The following sections provide details on the properties that may be used with sh:PropertyConstraint. None of these properties can be repeated within the same sh:PropertyConstraint. In order to define multiple constraints using the same property, such as multiple sh:hasValue constraints, the shape must use multiple sh:property definitions.

Note that this chapter is work in progress to implement the resolution to ISSUE-98. In a nutshell, these constraint types can be used either at sh:constraint (to apply to the focus node itself), at sh:property (to apply to all values of a given property), or at sh:inverseProperty (to apply to all inverse values of a given property). Which combinations are supported is summarized in the following table. The flow of the sub-sections needs to be adjusted and generalized accordingly.

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (isLiteral(?value) || 
		!(
			$class = rdfs:Resource ||
			($class = rdf:List && EXISTS { ?value rdf:first ?any }) ||
			EXISTS { ?value rdf:type/rdfs:subClassOf* $class }
		))
}

ex:ClassExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:class ex:ClassA ;
	] .
	
ex:InstanceOfClassA
	a ex:ClassA .

ex:ClassExampleValidResource
	ex:someProperty ex:InstanceOfClassA .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (isLiteral(?value) || NOT EXISTS {
			GRAPH $shapesGraph {
				$classIn (rdf:rest*)/rdf:first ?class .
			}
			FILTER (?class = rdfs:Resource ||
				(?class = rdf:List && EXISTS { ?value rdf:first ?any }) ||
				EXISTS { ?value rdf:type/rdfs:subClassOf* ?class })
		})
}

ex:ClassInExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:classIn ( ex:ClassA ex:ClassB ) ;
	] .
	
ex:InstanceOfClassA
	a ex:ClassA .
	
ex:InstanceOfClassB
	a ex:ClassB .

ex:ClassExampleValidResource
	ex:someProperty ex:InstanceOfClassA ;
	ex:someProperty ex:InstanceOfClassB .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER NOT EXISTS {
		{
			FILTER isLiteral(?value) .
		} .
		BIND (datatype(?value) AS ?valueDatatype) .
		FILTER (?valueDatatype = $datatype) .
	}
}

ex:DatatypeExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:datatype xsd:string ;
	] .

ex:DatatypeShapeExampleValidResource
	ex:someProperty "Some value" .

ex:DatatypeShapeExampleInvalidResource
	ex:someProperty "Value with language tag"@en ;
	ex:someProperty 42 .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (!isLiteral(?value) || NOT EXISTS {
			GRAPH $shapesGraph {
				$datatypeIn (rdf:rest*)/rdf:first ?datatype .
			} 
			BIND (datatype(?value) AS ?valueDatatype) .
			FILTER (?valueDatatype = $datatype) .
		})
	}
}

ex:DatatypeInExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:datatypeIn ( xsd:string rdf:langString ) ;
	] .

ex:DatatypeInShapeExampleValidResource
	ex:someProperty "Value with language tag"@en ;
	ex:someProperty "Some string value" .

ex:DatatypeInShapeExampleInvalidResource
	ex:someProperty 42 .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER NOT EXISTS {
		?value a $directType .
	}
}

SELECT $this ($this AS ?subject) $predicate ?object
WHERE {
	{
		$this $predicate ?object .
		FILTER NOT EXISTS {
			$this $equals ?object .
		}
	}
	UNION
	{
		$this $equals ?object .
		FILTER NOT EXISTS {
			$this $predicate ?object .
		}
	}
}

ex:EqualExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:firstName ;
		sh:equals ex:givenName ;
	] .

ex:ValidInstance1
	ex:firstName "John" ;
	ex:givenName "John" .

SELECT $this ($this AS ?subject) $predicate
WHERE {
	FILTER NOT EXISTS {
		$this $predicate $hasValue .
	}
}

ex:HasValueExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:property ;
		sh:hasValue ex:Green ;
	] .

ex:HasValueExampleValidResource
	ex:property ex:Green .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER NOT EXISTS {
		GRAPH $shapesGraph {
			$in (rdf:rest*)/rdf:first ?value .
		}
	}
}

ex:AllowedValuesExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:in ( ex:Value1 ex:Value2 ex:Value3 ) ;
	] .

ex:InExampleValidResource
	ex:someProperty ex:Value2 .

SELECT $this ($this AS ?subject) $predicate ?object
WHERE {
	$this $predicate ?object .
	$this $lessThan ?object2 .
	FILTER (!(?object < ?object2)) .
}

ex:LessThanExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:startDate ;
		sh:lessThan ex:endDate ;
	] .

SELECT $this ($this AS ?subject) $predicate ?object
WHERE {
	$this $predicate ?object .
	$this $lessThanOrEquals ?object2 .
	FILTER (!(?object <= ?object2)) .
}

SELECT $this ($this AS ?subject) $predicate
WHERE {
	{
		SELECT (COUNT(?value) AS ?count)
		WHERE {
			$this $predicate ?value .
		}
	}
	FILTER (?count < $minCount)
}

SELECT $this ($this AS ?subject) $predicate
WHERE {
	{
		SELECT (COUNT(?value) AS ?count)
		WHERE {
			$this $predicate ?value .
		}
	}
	FILTER (?count > $maxCount))
}

ex:CountExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:minCount 1 ;
		sh:maxCount 1 ;
	] .

ex:CountExampleValidResource
	ex:someProperty ex:OneValue .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (isBlank(?value) || STRLEN(str(?value)) < $minLength) .
}

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (isBlank(?value) || STRLEN(str(?value)) > $maxLength) .
}

ex:PasswordExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:password ;
		sh:minLength 8 ;
		sh:maxLength 10 ;
		rdfs:comment "Password must be between 8 and 10 characters long" ;
	] .

ex:PasswordExampleValidResource
	ex:password "password" .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (!($value > $minExclusive)) .
}

ex:NumericRangeExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:minInclusive 1 ;
		sh:maxInclusive 10 ;
	] .

ex:NumericExampleValidResource
	ex:someProperty 7 .

ex:NumericExampleInvalidResource1
	ex:someProperty 11 .

ex:NumericExampleInvalidResource2
	ex:someProperty "a string" .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER NOT EXISTS {
		FILTER ((isIRI(?value) && $nodeKind = sh:IRI) ||
			(isLiteral(?value) && $nodeKind = sh:Literal) ||
			(isBlank(?value) && $nodeKind = sh:BlankNode)) .
	}
}

ex:NodeKindExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:nodeKind ex:IRI ;
	] .

ex:NodeKindShapeExampleValidResource
	ex:someProperty ex:SomeIRI .

ex:NodeKindShapeExampleInvalidResource
	ex:someProperty ex:SomeIRI ;
	ex:someProperty "A literal" .

SELECT $this ($this AS ?subject) $predicate ?object
WHERE {
	$this $predicate ?object .
	$this $notEquals ?object .
}

ex:NotEqualsExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:prefLabel ;
		sh:notEquals ex:altLabel ;
	] .

ex:ValidInstance1
	ex:prefLabel "USA" ;
	ex:altLabel "United States" .

ex:InvalidInstance1
	ex:prefLabel "Germany" ;
	ex:altLabel "Germany" .

SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (isBlank(?value) || IF(bound($flags), !regex(str(?value), $pattern, $flags), !regex(str(?value), $pattern))) .
}

ex:PatternExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:pattern "^Ali" ;
		sh:flags "i" ;       # Ignore case
	] .

ex:PatternShapeExampleValidResource
	ex:someProperty "alice" .

ex:PatternShapeExampleInvalidResource
	ex:someProperty "The Alice" .

SELECT DISTINCT $this ($this AS ?subject) $predicate
WHERE {
	{
		FILTER ($uniqueLang) .
	}
	$this $predicate ?value .
	BIND (lang(?value) AS ?lang) .
	FILTER (bound(?lang) && ?lang != "") . 
	FILTER EXISTS {
		$this $predicate ?otherValue .
		FILTER (?otherValue != ?value && ?lang = lang(?otherValue)) .
	}
}

ex:UniqueLangExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:uniqueLang true ;
	] .

ex:UniqueLangShapeExampleValidResource
	ex:someProperty "Me" ;
	ex:someProperty "Me"@en ;
	ex:someProperty "Moi"@fr .

ex:UniqueLangShapeExampleInvalidResource
	ex:someProperty "Me"@en ;
	ex:someProperty "Myself"@en .

SELECT $this ($this AS ?subject) $predicate ?object ?failure
WHERE {
	$this $predicate ?object .
	BIND (sh:hasShape(?object, $valueShape, $shapesGraph, false) AS ?hasShape) .
	BIND (!bound(?hasShape) AS ?failure) .
	FILTER (?failure || !?hasShape) .
}

ex:ValueShapeExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:valueShape [
			a sh:Shape ;   # Optional
			sh:predicate [
				sh:predicate ex:nestedProperty ;
				sh:minCount 1 ;
			]
		]
	] .

ex:ValueShapeExampleValidResource
	ex:someProperty [
		ex:nestedProperty 42 ;
	] .

SELECT $this ($this AS ?subject) $predicate ?failure
WHERE {
	{
		SELECT (SUM(?s) AS ?count)
		WHERE {
			{
				FILTER NOT EXISTS { $this $predicate ?value } .
				BIND (0 AS ?s) .
			}
			UNION
			{
				$this $predicate ?value .
				BIND (sh:hasShape(?value, $qualifiedValueShape, $shapesGraph, true) AS ?hasShape) .
				BIND (IF(bound(?hasShape), IF(?hasShape, 1, 0), 'error') AS ?s) .
			}
		}
	}
	BIND (!bound(?count) AS ?failure) .
	FILTER IF(?failure, true, ?count < $qualifiedMinCount) .
}

SELECT $this ($this AS ?subject) $predicate ?failure
WHERE {
	{
		SELECT (SUM(?s) AS ?count)
		WHERE {
			{
				FILTER NOT EXISTS { $this $predicate ?value } .
				BIND (0 AS ?s) .
			}
			UNION
			{
				$this $predicate ?value .
				BIND (sh:hasShape(?value, $qualifiedValueShape, $shapesGraph, true) AS ?hasShape) .
				BIND (IF(bound(?hasShape), IF(?hasShape, 1, 0), 'error') AS ?s) .
			}
		}
	}
	BIND (!bound(?count) AS ?failure) .
	FILTER IF(?failure, true, ?count > $qualifiedMaxCount) .
}

ex:QualifiedValueShapeExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:parent ;
		sh:minCount 2 ;
		sh:maxCount 2 ;
		sh:qualifiedValueShape [
			a sh:Shape ;   # Optional
			sh:property [
				sh:predicate ex:gender ;
				sh:hasValue ex:female ;
			]
		] ;
		sh:qualifiedMinCount 1 ;
	] .

ex:QualifiedValueShapeExampleValidResource
	ex:parent ex:John ;
	ex:parent ex:Jane .

ex:John
	ex:gender ex:male .

ex:Jane
	ex:gender ex:female .

ex:PersonFormShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:firstName ;
		sh:name "first name" ;
		sh:description "The person's given name(s)" ;
		sh:order 0 ;
		sh:group ex:NameGroup ;
	] ;
	sh:property [
		sh:predicate ex:lastName ;
		sh:name "last name" ;
		sh:description "The person's last name" ;
		sh:order 1 ;
		sh:group ex:NameGroup ;
	] ;
	sh:property [
		sh:predicate ex:streetAddress ;
		sh:name "street address" ;
		sh:description "The street address including number" ;
		sh:order 11 ;
		sh:group ex:AddressGroup ;
	] ;
	sh:property [
		sh:predicate ex:locality ;
		sh:name "locality" ;
		sh:description "The suburb, city or town of the address" ;
		sh:order 12 ;
		sh:group ex:AddressGroup ;
	] ;
	sh:property [
		sh:predicate ex:postalCode ;
		sh:name "postal code" ;
		sh:name "zip code"@en-US ;
		sh:description "The postal code of the locality" ;
		sh:order 13 ;
		sh:group ex:AddressGroup ;
	] .
	
ex:NameGroup
	a sh:PropertyGroup ;
	sh:order 0 ;
	rdfs:label "Name" .

ex:AddressGroup
	a sh:PropertyGroup ;
	sh:order 1 ;
	rdfs:label "Address" .

3.2 Inverse Property Constraints (sh:inverseProperty)

TODO: This section is quite similar to the one about sh:property, only in the inverse direction. Before writing all this down, we'd rather wait until the forward direction has stabilized. A quick example should suffice for now:

ex:InversePropertyConstraintExampleShape
	a sh:Shape ;
	sh:inverseProperty [
		sh:predicate ex:someProperty ;  # e.g. "child"
		sh:minCount 1 ;
		sh:name "is someProperty of" ;  # e.g. "parent"
	] .

3.3 Other Core Constraints

While the previous sections have introduced constraints that focused on a single property within a shape, this section introduces other constraint types that can be used with shapes.

SELECT $this ?failure
WHERE {
	BIND (sh:hasShape($this, $not, $shapesGraph, true) AS ?hasShape) .
	BIND (!bound(?hasShape) AS ?failure) .
	FILTER (?failure || ?hasShape) .
}

ex:NotExampleShape
	a sh:Shape ;
	sh:constraint [
		sh:not [
			a sh:Shape ;
			sh:property [
				sh:predicate ex:property ;
				sh:minCount 1 ;
			] ;
		]
	] .

ex:InvalidInstance1
  	ex:property "Some value" .

SELECT $this ?failure
WHERE {
	{
		SELECT (SUM(?s) AS ?count)
		WHERE {
			GRAPH $shapesGraph {
				$and rdf:rest*/rdf:first ?shape .
			}
			BIND (sh:hasShape($this, ?shape, $shapesGraph, true) AS ?hasShape) .
			BIND (IF(bound(?hasShape), IF(!?hasShape, 1, 0), 'error') AS ?s) .
		}
	}
	BIND (!bound(?count) AS ?failure) .
	FILTER IF(?failure, true, ?count > 0) .
}

ex:SuperShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:property ;
		sh:minCount 1 ;
	] .

ex:ExampleAndShape
	a sh:Shape ;
	sh:constraint [
		sh:and (
			ex:SuperShape
			[
				sh:property [
					sh:predicate ex:property ;
					sh:maxCount 1 ;
				]
			]
		)
	] .


ex:ValidInstance1
	ex:property "One" .

# Invalid: more than one property
ex:InvalidInstance2
	ex:property "One" ;
	ex:property "Two" .

SELECT $this ?failure
WHERE {
	{
		SELECT (SUM(?s) AS ?count)
		WHERE {
			GRAPH $shapesGraph {
				$or rdf:rest*/rdf:first ?shape .
			}
			BIND (sh:hasShape($this, ?shape, $shapesGraph, true) AS ?hasShape) .
			BIND (IF(bound(?hasShape), IF(?hasShape, 1, 0), 'error') AS ?s) .
		}
	}
	BIND (!bound(?count) AS ?failure) .
	FILTER IF(?failure, true, ?count = 0) .
}

ex:OrConstraintExampleShape
	a sh:Shape ;
	sh:constraint [
		sh:or (
			[
				sh:property [
					sh:predicate ex:exampleProperty1 ;
					sh:minCount 1 ;
				]
			]
			[
				sh:property [
					sh:predicate ex:exampleProperty2 ;
					sh:minCount 1 ;
				]
			]
		)
	] .
	
ex:OrConstraintExampleValidResource
	ex:exampleProperty1 ex:someValue .

SELECT $this ($this AS ?subject) ?predicate ?object
WHERE {
	{
		FILTER $closed .
	}
	$this ?predicate ?object .
	FILTER (NOT EXISTS {
		GRAPH $shapesGraph {
			$currentShape sh:property/sh:predicate ?predicate .
		}
	} && (!bound($ignoredProperties) || NOT EXISTS {
		GRAPH $shapesGraph {
			$ignoredProperties rdf:rest*/rdf:first ?predicate .
		}
	}))
}

ex:ClosedShapeExampleShape
	a sh:Shape ;
	sh:constraint [
		sh:closed true ;
		sh:ignoredProperties (rdf:type) ;
	] ;
	sh:property [
		sh:predicate ex:exampleProperty1 ;
	] ;
	sh:property [
		sh:predicate ex:exampleProperty2 ;
	] .
	
ex:ClosedShapeExampleValidResource
	ex:exampleProperty1 ex:someValue .
	
ex:ClosedShapeExampleInvalidResource
	ex:exampleProperty2 ex:someValue ;
	ex:someOtherProperty 42 .

ex:ClosedShapeExampleShape
	a sh:Shape ;
	sh:constraint sh:Closed ;
	sh:property [
		sh:predicate ex:exampleProperty1 ;
	] ;
	sh:property [
		sh:predicate ex:exampleProperty2 ;
	] .

5.1 sh:focusNode

Validation results may have a single value for the property sh:focusNode to point to an IRI or blank node that has caused the result. This represents the focus node that was validated when the validation result was produced.

5.2 sh:subject, sh:predicate and sh:object

Validation results are often caused by a single RDF triple, or a predicate in the context of a given subject or object. This information can be encoded via the properties sh:subject, sh:predicate and sh:object, each of which can have at most one value. sh:predicate can only be present if either sh:subject or sh:object have also been specified. If sh:object is unspecified, then the interpretation is that the result is caused by the subject/predicate combination. If sh:subject is unspecified, then the interpretation is that the result is caused by the object/predicate combination.

5.3 sh:sourceConstraint, sh:sourceShape and sh:sourceTemplate

Validation results may point at one sh:Constraint that has caused the result, specified via the property sh:sourceConstraint, and at the sh:Shape defining the constraint, via sh:sourceShape. Validation results that were produced by a template call may point at the sh:ConstraintTemplate that caused the result.

5.4 sh:detail

The property sh:detail may link a (parent) result with one or more other (child) results that provide further details about the cause of the (parent) result. Depending on the capabilities of the constraint validation engine, this may include failures of nested constraints that have been evaluated via sh:valueShape.

5.5 sh:message

Validation results may have values for the property sh:message to communicate additional textual details to humans. While sh:message may have multiple values, there SHOULD not be two values with the same language tag.

5.6 sh:severity

Each validation result must have exactly one of the following values for the property sh:severity.

5.7 Declaring the Severity of a Constraint

Constraints can specify their severity level using the property sh:severity, which must point at one of the severity types. sh:Violation is the default if unspecified. Constraints based on templates use the sh:severity declared at the template itself unless overridden at the constraint. The following example clarifies this.

ex:MyShape
	a sh:Shape ;
	sh:property [
		# Violations of either minCount and datatype are produced as warnings
		sh:predicate ex:myProperty ;
		sh:minCount 1 ;
		sh:datatype xsd:string ;
		sh:severity sh:Warning ;
	] ;
	sh:property [
		# Violation of maxCount are produced as sh:Violations (which is the default severity for sh:maxCount)
		sh:predicate ex:myProperty ;
		sh:maxCount 1 ;
	] ;
.

6.2 SPARQL-based Native Constraints

Native SPARQL constraints are instances of sh:SPARQLConstraint, which is a subclass of sh:NativeConstraint, which in turn is a subclass of sh:Constraint. Native SPARQL constraints must have one value for the property sh:sparql. The SPARQL queries linked to a constraint via sh:sparql must be string literals that can be parsed into legal SPARQL 1.1 queries of the query form SELECT. Before parsing, a SHACL processor must prepend PREFIX statements for all namespace prefixes defined in the current shapes graph.

ex:ShapeWithPathViolationExample
	a sh:Shape ;
	sh:scopeNode ex:ExampleRootResource ;
	sh:constraint [
		a sh:SPARQLConstraint ;
		sh:resultAnnotation [
			sh:annotationProperty ex:time ;
			sh:annotationVarName "time"
		] ;
		sh:sparql """
			SELECT $this ?subject (ex:property2 AS ?predicate) (?first AS ?object) ?message ?time
			WHERE {
				$this ex:property1 ?first .
				?subject ex:property2 ?first .
				FILTER isBlank(?value) .
				BIND (CONCAT("The ", "message.") AS ?message) .
				BIND (NOW() AS ?time) .
			}
			""" ;
	] .
	
ex:ExampleRootResource
	ex:property1 ex:ExampleIntermediateResource .

ex:ExampleValueResource
	ex:property2 ex:ExampleIntermediateResource .

[
	a sh:ValidationResult ;
	sh:severity sh:Violation ;
	sh:focusNode ex:ExampleRootResource ;
	sh:subject ex:ExampleValueResource ;
	sh:predicate ex:property2 ;
	sh:object ex:ExampleIntermediateResource ;
	sh:message "The message." ;
	sh:sourceConstraint [ the blank node of the sh:constraint above ] ;
	sh:sourceShape ex:ShapeWithPathViolationExample ;
	ex:time "2015-03-27T10:58:00"^^xsd:dateTime ;  # Example
] .

7.2 Template Arguments

The arguments of a template are linked via the property sh:argument. Each argument must be an instance of sh:Argument, but the rdf:type triples of these instances can be omitted.

Each sh:Argument must have exactly one value for the property sh:predicate. The values of sh:predicate must be IRIs. The local name of a IRI is defined as the longest NCNAME at the end of the IRI, not immediately preceeded by the first colon in the IRI. The local names of the values of sh:predicate must fulfill the following conditions (to ensure a correct mapping from arguments into SPARQL variables is possible):

• The local name must be a valid SPARQL VARNAME
• There must not be any other declared sh:Argument for the same template (and its transitive superclasses) that has a sh:predicate with the same local name

An sh:Argument may have its property sh:optional set to true to indicate that the argument is not mandatory.

An sh:Argument may declare a default value via sh:defaultValue. For non-optional arguments, the validation engine must use the declared default value for template instances that do not define a value for this argument. Template instances can have at most one value for each argument predicate.

An sh:Argument may declare one value for the property sh:class or one value for sh:datatype, similar to their counterparts in property constraints. Likewise, an sh:Argument may specify a sh:NodeKind via sh:nodeKind. This can be used to communicate the expected value type of the argument in template instances. Some implementations MAY use this information to prevent the execution of a template with invalid arguments.

7.3 Template Instantiation

sh:Template is subclass of rdfs:Class, which means that templates can be instantiated via rdf:type. Such template instances can be used as values of sh:constraint, among others, as demonstrated in an example above.

Template instances are called complete when they have values for all non-optional arguments. Only template instances that are complete will be used - incomplete templates will be (silently) ignored during constraint validation.

Constraint templates may be placed in a rdfs:subClassOf relationship with other templates. The implication of doing this is that when an instance of the superclass template is validated, then all (transitive) superclass templates will also be validated, assuming their arguments are complete.

7.4 sh:labelTemplate

The property sh:labelTemplate can be used to suggest how instances of the template shall be rendered to humans. The sh:labelTemplate must be a string that can reference the arguments using the syntax {?varName}, where varName is the name of the SPARQL variable that corresponds to the argument. At display time, these {?...} blocks SHOULD be substituted with the actual values used in the template instance.

7.5 Property Constraint Templates

Some constraints are about a specific property only, and SHACL provides the system properties sh:property and sh:inverseProperty for those cases. In order to define constraints that can be used similar to the built-in Core constraint properties such as sh:minCount, a SHACL template needs to declared to be a subclass of sh:PropertyConstraint (for sh:property) or sh:InversePropertyConstraint (for sh:inverseProperty). Such templates "inherit" the argument sh:predicate. This is illustrated in the following example.

ex:LanguagePropertyConstraint
	a sh:ConstraintTemplate ;
	rdfs:subClassOf sh:PropertyConstraint ;
	sh:argument [
		sh:predicate ex:lang ;
		sh:datatype xsd:string ;
		sh:name "language" ;
		sh:description "The language tag, e.g. \"de\"." ;
	] ;
	sh:labelTemplate "Values of {?predicate} must be literals with language \"{?lang}\"" ;
	sh:message "Values must be literals with language \"{?lang}\"" ;
	sh:sparql """
		SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
		WHERE {
			$this $predicate ?value .
			FILTER (!isLiteral(?value) || !langMatches(lang(?value), $lang))
		}
		""" .

ex:TemplateLanguageWithPropertyConstraintExampleShape
	a sh:Shape ;
	sh:scopeClass ex:Country ;
	sh:property [
		a ex:LanguagePropertyConstraint ;
		sh:predicate ex:germanLabel ;
		sh:datatype rdf:langString ;
		sh:maxCount 1 ;
		ex:lang "de" ;
	] .

As shown above, shapes can instantiate such templates via sh:property and mix custom constraint properties such as ex:lang with those from the SHACL Core vocabulary, such as sh:maxCount.

7.6 Templates with a sh:validationFunction

Constraint templates that are instances of sh:PropertyValueConstraintTemplate or sh:InversePropertyValueConstraintTemplate (which are subclasses of sh:ConstraintTemplate) do not require an executable body (such a sh:sparql) if they instead point at a sh:Function via the property sh:validationFunction. These so called validation functions must take an argument with the predicate sh:value as its first argument and return either true or false. This validation function must be used by a constraint validation engine to construct a procedure that iterates over all values of the (possibly inverse) property, and then runs a filter test using the function. If the filter returns false then a validation result must be produced. Validation functions may take additional arguments, and the validation engine must fill them with the matching arguments from the surrounding template. The SHACL system vocabulary contains several examples of such validation functions, e.g. sh:AbstractDatatypePropertyConstraint.

The following example defines a constraint template using a validation function from a later section.

ex:LanguageConstraint
	a sh:PropertyValueConstraintTemplate ;
	rdfs:label "Language constraint" ;
	rdfs:subClassOf sh:TemplateConstraint ;
	sh:argument [
		sh:predicate ex:predicate ;
		sh:class rdf:Property ;
		sh:name "predicate" ;
		sh:description "The property to validate the values of." ;
    ] ;
	sh:argument [
		sh:predicate ex:lang ;
		sh:datatype xsd:string ;
		sh:name "language" ;
		sh:description "The language tag, e.g. \"de\"." ;
	] ;
	sh:labelTemplate "Values of {?predicate} must be literals with language \"{?lang}\"" ;
	sh:message "Values must be literals with language \"{?lang}\"" ;
	sh:validationFunction ex:hasLanguage .

7.7 SPARQL-based Constraint Templates

If a sh:Template has a value for sh:sparql, then the corresponding instances need to follow the same execution rules as outlined for SPARQL-based Constraints and SPARQL-based Scopes. The only difference is that the SPARQL queries need to be executed with additional pre-bound variables, derived from the arguments of the template. The names of those variables must match the local name of the argument predicates, including the arguments defined by any (transitive) superclasses of the template. For example, if an argument is represented with the predicate ex:myArgument then the variable ?myArgument must be pre-bound with the value of the argument in the template instance.

If a sh:PropertyValueConstraintTemplate has a value for sh:validationFunction, then the validation engine needs to produce a SPARQL query equivalent to the following pattern:

SELECT $this ($this AS ?subject) $predicate ?object
WHERE {
	$this $predicate ?object .
	FILTER (!{validationFunction}(?object, {+ other matching arguments})) .
}

If a sh:InversePropertyValueConstraintTemplate has a value for sh:validationFunction, then the validation engine needs to produce a SPARQL query equivalent to the following pattern:

SELECT $this ?subject $predicate ($this AS ?object)
WHERE {
	?subject $predicate $this .
	FILTER (!{validationFunction}(?subject, {+ other matching arguments})) .
}

8.1 SPARQL-based Scopes

SPARQL-based scopes must be instances of sh:SPARQLScope, which is a subclass of sh:NativeScope. The SPARQL queries linked to a scope via sh:sparql must be of the query form SELECT. The SELECT queries must project to the result variable ?this. The resulting scope consists of all distinct bindings for the variable ?this.

The SELECT queries must also be executable when converted to an ASK query and with a pre-bound value for ?this. The set of bindings for ?this that return true for such ASK queries must be identical to the set produced by the SELECT query. This constraint makes sure that validation engines can validate whether a given shape applies to a given focus node.

The following example illustrates a well-formed SPARQL-based scope that produces all persons born in the USA:

ex:USCitizenShape
	a sh:Shape ;
	sh:scope [
		a sh:SPARQLScope ;
		sh:sparql """
			SELECT ?this
			WHERE {
				?this a ex:Person .
				?this ex:bornIn ex:USA .
			}
			""" ;
	] ;
	sh:constraint ...

9.2 Function Arguments

The arguments of a function are linked to its sh:Function via the property sh:argument. Each argument must be an instance of sh:Argument, but their rdf:type triple can be omitted.

Each sh:Argument must have exactly one value for the property sh:predicate. The values of sh:predicate must be IRIs, and follow the same restrictions outlined for Template Arguments. Arguments are "inherited" from the superclasses of the function. For example if a superclass already declares sh:arg1 then subclasses may only define sh:arg2 etc.

Arguments are ordered, corresponding to the notation of function calls in SPARQL such as ex:exampleFunction(?arg1, ?arg2). The ordering of function arguments (e.g. for printing in SPARQL strings) is determined by their index. For each function, the indices must be 0, 1, 2 etc. The index of each declared sh:Argument is determined as follows:

1. The index of the built-in argument predicates sh:arg1, sh:arg2 etc is their numeric name part minus 1, e.g. sh:arg1 has index 0.
2. The index of other argument predicates is the value of the property sh:order at the surrounding sh:Argument.
3. Arguments that are neither of the form sh:argX nor have an sh:order are place at the end, whereby arguments that have sh:optional set to true get a higher index than non-optional arguments.

Each sh:Argument may have its property sh:optional set to true to indicate that the argument is not mandatory. If an argument has been declared optional, then all succeeding arguments must also be declared optional.

Similar to Property Constraints, each sh:Argument may declare one value for the property sh:datatype or one value for the property sh:class. This can be used to communicate the expected value type of the argument in function calls. Some implementations MAY use this information to prevent the execution of a function with invalid arguments.

9.3 sh:returnType

A function may declare a single return type via sh:returnType. This information may serve for documentation purposes, only. However, in some execution languages such as JavaScript, the declared sh:returnType may inform a processor how to cast a native value into an RDF value type.

9.4 Validation Functions

It is a common design pattern for functions to take a value as input and validate whether that value fulfills certain conditions or not. In support of this pattern, SHACL supports validation functions, which are instances of sh:Function that are also subclasses of sh:ValidationFunctions. From that superclass, these functions "inherit" the (first) argument sh:value. Validation functions may define additional arguments with sh:order values larger than 1. The following example illustrates a validation function for the running example of the section on constraint templates.

ex:hasLanguage
	a sh:Function ;
	rdfs:subClassOf sh:ValidationFunctions ;
	sh:argument [
		sh:predicate ex:lang ;
		sh:datatype xsd:string ;
		sh:order 1 ;
		sh:name "language" ;
		sh:description "The language to match against, e.g. \"de\"." ;
	] ;
	sh:returnType xsd:boolean ;
	sh:sparql """
  		ASK {
  			FILTER (isLiteral($value) && langMatches(lang($value), $lang)) .
		}
		""" .

An example invocation of the function above is: ex:hasLanguage("Spain"@en, "en"), producing true.

9.5 SPARQL-based Functions

If a sh:Function has a value for sh:sparql then it can be regarded as a SPARQL-based function. In the SPARQL query, the SPARQL processor needs to pre-bind variables based on the provided arguments of the function call. The SPARQL query must be of type ASK or SELECT. For ASK queries, the function's return value is the result of the ASK query execution. For SELECT queries, the function's return value is the first binding of the first result variable in the result set. Since all other bindings will be ignored, such SELECT queries SHOULD only return a single result variable and at most one row.

Recursive use of functions is undefined: If a SPARQL-based function contains calls to other functions so that the same function with the same combination of arguments would be visited twice then the result of the function call is undefined. An implementation may either return no result (unbound) or terminate the surrounding SPARQL query with an error.

Some validation engines may ignore the specified sh:sparql query and rely on an alternative (possibly native) implementation instead, as long as the functions return the same values as the specified sh:sparql query. This can be used to optimize frequently needed functions. Some processors may even use the sh:sparql query to rewrite other SPARQL queries via inlining techniques.