Abstract

SHACL (Shapes Constraint Language) is a language for describing and constraining the contents of RDF graphs. SHACL groups these descriptions and constraints into "shapes", which specify conditions that apply at a given RDF node. Shapes provide a high-level vocabulary to identify predicates and their associated cardinalities, datatypes and other constraints. Additional constraints can be associated with shapes using SPARQL and similar extension languages. These extension languages can also be used to define new high-level vocabulary terms. SHACL shapes can be used to communicate information about data structures associated with some process or interface, generate or validate data, or drive user interfaces. This document defines the SHACL language and its underlying semantics.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the RDF Data Shapes Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-data-shapes-wg@w3.org (subscribe, archives). All comments are welcome.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

Table of Contents

Revision History

The detailed list of changes and their diffs can be found in the Git repository.

Document Outline

The sections 2 - 5 cover the SHACL Core Profile and may be read independently from the later sections.

The sections 6 onwards are about the advanced features of the SHACL language, including templates, functions, and execution semantics.

The Appendix provides a Glossary of Key Concepts that may also serve as a quick overview of the language.

The examples in this document use Turtle [turtle]. The reader should be familiar with basic RDF concepts [rdf11-concepts] such as triples and (for the advanced concepts of SHACL) with SPARQL [sparql11-overview].

1. Introduction

SHACL (Shapes Constraint Language) is a language for describing and constraining RDF graphs. SHACL can be used with RDF graphs that are obtained by any means, e.g. from the file system, HTTP requests, or RDF datasets. SHACL groups descriptive information and constraints that apply to a given data node into "shapes". This document defines what it means for an RDF graph, referred to as the "data graph", to conform to a SHACL program, referred to as the "shapes graph". Conformance can be programatically checked by processors referred to as "SHACL engines". The process of checking conformance is referred to as "validation". A shape may include a "scope" which defines which data nodes must conform to it. When a data node is checked for conformance to a shape, that node is referred to as the "focus node". The output of the validation process is a "validation report" which indicates whether or not the data graph conforms to the shapes graph. If any constraints are not satisfied, then the validation report will include one or more "violations" which indicate the source of the problem.

For example, SHACL can be used to check whether all the nodes in a data graph that have a type link to foaf:Person have a single value for foaf:mbox, and that that value is an IRI. SHACL can also be used to check whether a particular node in a data graph, say the node ex:bug1, has at least one value for ex:reportedBy and all such values have an rdf:type link to foaf:Person.

The simplest interface to a SHACL processor has two inputs:

For example, one might use SHACL to determine whether data graphs that contain information about issues and users conform to the following constraints:

A shapes graph that defines these constraints has two shapes. The first, ex:IssueShape contains the two constraints on issues. The second, ex:UserShape, contains the two constraints on reporters. ex:IssueShape also contains scope information which in this case says that its constraints apply to all nodes that have an rdf:type link to ex:Issue.

Example 1: Definition of ex:IssueShape and ex:UserShape
ex:IssueShape
	a sh:Shape ;
	sh:scopeClass ex:Issue;
	sh:property [
		sh:predicate ex:state ;
		sh:allowedValues (ex:unassigned ex:assigned) ;
		sh:minCount 1 ;
		sh:maxCount 1 ;
	] ;
	sh:property [
		sh:predicate ex:reportedBy ;
		sh:valueShape ex:UserShape ;
		sh:minCount 1 ;
		sh:maxCount 1 ;
	] .

ex:UserShape
	a sh:Shape ;
	sh:property [
		sh:predicate foaf:name ;
		sh:datatype xsd:string ;
		sh:minCount 1 ;
		sh:maxCount 1 ;
	] ;
	sh:property [
		sh:predicate foaf:mbox ;
		sh:nodeKind sh:IRI ;
		sh:minCount 1 ;
	] .

The following data graph might be validated against this shapes graph.

Example 2: Definition of ex:IssueShape and ex:UserShape
inst:Issue1
	a ex:Issue ;
	ex:state ex:unassigned ;
	ex:reportedBy inst:User2 .

inst:User2
	a foaf:Person ;
	foaf:name "Bob Smith" ;
	foaf:mbox <mailto:bob@example.org> ;
	foaf:mbox <mailto:rs@example.org> .

inst:Issue3
	a ex:Issue ;
	ex:state ex:unsinged ;
	ex:reportedBy inst:User4 .

inst:User4
	a foaf:Person ;
	foaf:name "Bob Smith", "Robert Smith" ;
	foaf:mbox <mailto:bob@example.org> ;
	foaf:mbox <mailto:rs@example.org> .

The SHACL validation would validate ex:IssueShape against inst:Issue1 and inst:Issue3. Validating the first node would determine that inst:Issue1 satisfies the constraints in ex:IssueShape, along the way determining that inst:User2 satisfies the constraints in ex:UserShape. Validating the second node would determine that inst:Issue3 violates the constraint on values for ex:state, because ex:unsigned is not in the list of allowed values, and also violates the constraint on values for ex:reportedBy, because inst:User4 violates the ex:UserShape constraint on the maximum number of values for foaf:name.

1.1 Relationship between SHACL and RDFS

SHACL uses RDF and RDFS vocabulary (in particular rdf:type, rdfs:Class, rdfs:subClassOf, rdfs:label, rdfs:comment, rdf:Property, rdf:List, rdf:langLiteral, and rdfs:Resource) and notions (notably classes, instances, and subclasses). However, SHACL does not use this vocabulary or these notions in the way that they are 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.

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. TODO: what is the best wording to make this clearer?

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.

The button below can be used to show or hide the SPARQL definitions.

1.3 Namespaces

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

Prefix Namespace
rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs: http://www.w3.org/2000/01/rdf-schema#
sh: http://www.w3.org/ns/shacl#
xsd: http://www.w3.org/2001/XMLSchema#

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.

Part 1: Core Features

2. Shapes

In the SHACL RDF vocabulary, shapes are instances of the class sh:Shape. A shape is a group of constraints that can be validated against nodes. If a node is validated against a constraint then it is called the focus node. Shapes MAY have scopes that instruct a SHACL processor on how to select those focus nodes, and MAY also have filter shapes that narrow down the scope. For example, a shape can be used to state that all instances of a class must have a certain number of values for a given property. In that example, the instances of the class are the focus nodes in the scope, and the restriction on property values is expressed via a constraint. Both concepts are illustrated by the following figure, and introduced in the following sub-sections.

Fig. 1 Illustration of the scoping and filtering process

2.1 Scopes

SHACL shapes can have three kinds of scopes:

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.

2.1.1 Individual scopes (sh:nodeShape)

Issue 61: Direction of sh:nodeShape
There is an alternative proposal discussed that would reverse the direction of this, pointing from the shape to the nodes.

Individual nodes can point to the shapes that they are supposed to be validated against using the property sh:nodeShape. The values of sh:nodeShape must be IRIs. This pattern is illustrated in the following example.

Example 3: Scope based on sh:nodeShape
ex:ExampleShape
	a sh:Shape ;
	sh:constraint [
		...
	] .

ex:ExampleInstance
	sh:nodeShape ex:ExampleShape .

2.1.2 Class-based Scopes (sh:scopeClass and rdf:type)

RDF Schema provides a well-established framework to model domains in terms of classes and instances. A lot of existing data is already represented this way. The property sh:scopeClass can be used to link a sh:Shape with an rdfs:Class. The property rdf:type is used to determine which shapes a given node are expected to fulfill. The scope includes all instances of the sh:scopeClass and its subclasses, by following rdfs:subClassOf triples. This pattern is illustrated in the following example.

Example 4: Scope based on rdf:type and sh:scopeClass
ex:ExampleClass
	a rdfs:Class .

ex:ExampleShape
	a sh:Shape ;
	sh:scopeClass ex:ExampleClass ;
	sh:constraint [
		...
	] .

ex:ExampleInstance
	rdf:type ex:ExampleClass .
Issue 23: Classes and/or Shapes
There is no agreement in the WG on the relationship between sh:Shape and rdfs:Class. In the absence of such an agreement, this document uses sh:Shape in most examples but allows classes to be also shapes, with the class sh:ShapeClass as syntactic sugar.

If the type class of an instance is also an instance of sh:Shape then the sh:scopeClass triple MAY be omitted and rdf:type MAY directly link a resource with its shapes. In this scope, the IRIs of classes double as shape definitions, i.e. it is possible to directly link constraints to the IRI of a class. As syntactic sugar, the metaclass sh:ShapeClass can be used as a combination of rdfs:Class and sh:Shape. This pattern is illustrated in the following example.

Example 5: Scope based on rdf:type only
ex:ExampleClassAndShape
	a rdfs:Class ;    # These two triples can be simplified via sh:ShapeClass
	a sh:Shape ;
	sh:constraint [
		...
	] .

ex:ExampleInstance
	rdf:type ex:ExampleClass .
Issue 78: Abstract classes
The following paragraph about sh:abstract is not yet approved by the WG. Options include:
  • No support of abstract classes
  • Use sh:abstract entirely for documentation purposes
  • Use sh:abstract also as a constraint check, possibly producing a warning

Classes with type sh:ShapeClass may be declared to be abstract by setting their property sh:abstract to true. Abstract classes SHOULD not be instantiated directly, i.e. every instance of an abstract class SHOULD also have an rdf:type triple to a non-abstract subclass of the abstract class.

2.1.3 General scopes (sh:scope)

SHACL includes a generic mechanism to select focus nodes. A sh:Shape can point to one or more instances of sh:Scope. SHACL includes several subclasses of sh:Scope that define a high-level vocabulary for common scope patterns. The full SHACL language also includes a generic mechanism based on executable languages such as SPARQL, elaborated in an advanced section.

2.1.3.1 Property scopes (sh:PropertyScope)

The scope class sh:PropertyScope selects all subjects that have at least one value for a given property sh:predicate. In the following SPARQL query, the variable $predicate is assumed to be substituted with the given value of sh:predicate.

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

The following example uses sh:PropertyScope to define a constraint that applies to all resources that have any value for the property ex:property:

Example 6: Shape with sh:PropertyScope
ex:PropertyScopeExampleShape
	a sh:Shape ;
	sh:scope [
		a sh:PropertyScope ;
		sh:predicate ex:property ;
	] ;
	sh:constraint [
		...
	] .
2.1.3.2 Inverse property scopes (sh:InversePropertyScope)

The scope class sh:InversePropertyScope selects all objects that appear in at least one triple with a given property sh:predicate. In the following SPARQL query, the variable $predicate is assumed to be substituted with the given value of sh:predicate.

SPARQL DEFINITION
SELECT DISTINCT ?this
WHERE {
	?any $predicate ?this .
}
2.1.3.3 All subjects scopes (sh:AllSubjectsScope)

The scope class sh:AllSubjectsScope selects all subjects in the data graph.

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

The following example uses sh:AllSubjectsScope to define a constraint that shall apply to all subjects in the data graph:

Example 7: Shape with sh:AllSubjectsScope
ex:PropertyScopeExampleShape
	a sh:Shape ;
	sh:scope [
		a sh:AllSubjectsScope ;
	] ;
	sh:constraint [
		...
	] .
2.1.3.4 All objects scopes (sh:AllObjectsScope)

The scope class sh:AllObjectsScope selects all objects in the data graph, unless they are literals.

SPARQL DEFINITION
SELECT DISTINCT ?this
WHERE {
	?anySubject ?anyPredicate ?this .
	FILTER (!isLiteral(?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:bornIn 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.

Example 8: Constraint with a filter shape
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.

Example 9: Shape with a filter shape
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 .
Issue 49: Do filters apply to sh:valueShape etc
It is still undecided whether filters shall also be applied for shapes that are directly invoked, e.g. via sh:valueShape.

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.

Fig. 2 Illustration of some relationships between classes of SHACL and RDF Schema

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:

3. Core Constraint Types

The following sections define the constraint types built into the SHACL Core. Compliant SHACL engines MUST support all of these constraints.

Note that the textual definitions of the constraint types refer to the Validation Results Vocabulary introduced in a later section.

The SPARQL definitions in this section assume the following variable bindings:

Each row in the result set of the SPARQL queries in this document represents one validation result. The other variables in the SELECT clause are mapped to the details of each validation result, e.g. ?object is mapped to sh:object. (Clarify what exact compliance level is required, e.g. do they need to produce focus nodes) If a row in a SPARQL result set produces true as value for the variable ?failure then a failure must be reported.

The SPARQL definitions in this section also assume the existence of a built-in SPARQL function sh:hasShape, which takes the following arguments:

Argument Value Type Summary
?focusNode rdfs:Resource The focus node to validate.
?shape sh:Shape The shape to validate the focus node against.
?shapesGraph rdfs:Resource The current shapes graph.
?recursionIsError xsd:boolean If set to true then any recursive occurrence of the same resource against the same shape signals a failure, with the function returning undefined. If not true then any recursive occurrence must return true.

The result of the sh:hasShape function is either true, false or undefined. The function returns true if the validation of the ?focusNode against the given ?shape produces no validation results with severity sh:Violation. The validation algorithm of sh:hasShape itself is based the validateNodeAgainstShape operation. Note that any validation results produced inside of the sh:hasShape function are temporary, i.e. they are not added to the results graph of the surrounding execution environment. However, some implementations may add those nested validation results as annotations to the surrounding validation results, via sh:detail.

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:

Example 10: Property constraint represented by a blank node
ex:InlinePropertyConstraintExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:minCount 1 ;
		sh:valueClass ex:SomeClass ;
		rdfs:label "some property" ;
		rdfs:comment "Description of the role of ex:someProperty (in the context of the constraint)" ;
	] .

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

Example 11: Property constraint represented by a IRI
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:valueClass ex:SomeClass .

Property constraints may have an rdfs:label to provide a human-readable label for the property in the scope where it appears. If present, tools SHOULD prefer those locally defined labels over globally defined labels at the rdf:Property itself. For example, if a form displays a resource that is in the scope of a given shape, and the shape defines a sh:property constraint with an rdfs:label, then the tool SHOULD use the provided label. Similarly, property constraints may have an rdfs:comment to provide a description of the property in the given context. Both rdfs:label and rdfs:comment may have multiple values, but SHOULD only have one value per language tag.

Property constraints may have a single value for sh:defaultValue. The default value does not have fixed semantics in SHACL, but MAY be used by user interface tools to pre-populate input widgets. The value type of the sh:defaultValue SHOULD align with the specified sh:datatype, sh:directValueType or sh:valueClass of the same constraint.

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.

Properties Summary
sh:allowedValues Enumeration of allowed values
sh:datatype Datatype of all values
sh:hasValue A specific required value
sh:minCount, sh:maxCount Minimum and maximum cardinality
sh:minLength, sh:maxLength Minimum and maximum string length
sh:maxExclusive Maximum exclusive value (>)
sh:maxInclusive Maximum inclusive value (>=)
sh:minExclusive Minimum exclusive value (<)
sh:minInclusive Minimum inclusive value (<=)
sh:nodeKind Node kind (IRI, blank node, or literal) of all values
sh:pattern Regular expression string matching
sh:valueClass and sh:directValueType Type of all values
sh:valueShape Nested shape of all values
sh:qualifiedValueShape, sh:qualifiedMinCount, sh:qualifiedMaxCount Nested shape of a given minimum/maximum number of values

3.1.1 sh:allowedValues

The property sh:allowedValues can be used to enumerate the values a property can have. When specified, the value of the given property must be members of the specified set.

Property Value Type Summary
sh:allowedValues rdf:List Enumeration of allowed values
TEXTUAL DEFINITION
The values of sh:allowedValues must be well-formed instances of rdf:List. The members of that rdf:List must not be blank nodes. A validation result must be produced for every triple that has the focus node as its subject, the sh:predicate as its predicate and an object that is not a member of the given list. Matching of literals needs to be exact, e.g. "04"^^xsd:byte does not match "4"^^xsd:integer. Each produced result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective invalid value as its sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER NOT EXISTS {
		GRAPH $shapesGraph {
			$allowedValues (rdf:rest*)/rdf:first ?value .
		}
	}
}
Example 12: Shape with sh:allowedValues constraint
ex:AllowedValuesExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:allowedValues ( ex:Value1 ex:Value2 ex:Value3 ) ;
	] .

ex:AllowedValuesExampleValidResource
	ex:someProperty ex:Value2 .

3.1.2 sh:datatype

The property sh:datatype can be used to restrict the datatype of all values of the given property. The values of sh:datatype must be instances of the class rdfs:Datatype, such as xsd:string.

Property Value Type Summary
sh:datatype rdfs:Datatype Datatype of all values (e.g., xsd:integer)
TEXTUAL DEFINITION
A validation result must be produced for each triple that has the focus node as its subject, the sh:predicate as its predicate and where the object is not a literal, or is a literal with a mismatching datatype. A literal matches a datatype if the literal's datatype has the same IRI, or if its datatype is rdf:langLiteral or xsd:string and the expected datatype is sh:text. Each produced validation result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective violating value as its sh:object.
SPARQL DEFINITION
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) || ($datatype = sh:text && ?valueDatatype IN (rdf:langString, xsd:string))) .
	}
}
Example 13: Shape with sh:datatype constraint
ex:DatatypeExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:datatype sh:text ;
	] .

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

ex:DatatypeShapeExampleInvalidResource
	ex:someProperty 42 .

3.1.3 sh:directValueType

The property sh:directValueType can be used to restrict the rdf:type of all values of the given property. The values of sh:directValueType must be classes (instances of rdfs:Class). The main difference with sh:valueClass is that sh:directValueType does not include subclasses of the type.

Property Value Type Summary
sh:directValueType rdfs:Class Type of all values
TEXTUAL DEFINITION
A validation result must be produced for each triple that has the focus node as its subject, the sh:predicate as its predicate and where the object does not have an rdf:type triple with the given value type as object. Each produced validation result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective violating value as its sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER NOT EXISTS {
		?value a $directValueType .
	}
}

3.1.4 sh:hasValue

The property sh:hasValue can be used to verify that the focus node has a given RDF node among the values of the given predicate.

Property Value Type Summary
sh:hasValue any A specific required value
TEXTUAL DEFINITION
A validation result must be produced if there is no triple that has the focus node as its subject, the sh:predicate as its predicate and the sh:hasValue as its object. Each produced validation result must have the focus node as its sh:subject, and the sh:predicate as its sh:predicate.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) $predicate
WHERE {
	FILTER NOT EXISTS {
		$this $predicate $hasValue .
	}
}
Example 14: Shape with sh:hasValue constraint
ex:HasValueExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:property ;
		sh:hasValue ex:Green ;
	] .

ex:HasValueExampleValidResource
	ex:property ex:Green .

3.1.5 sh:minCount, sh:maxCount

The properties sh:minCount and sh:maxCount restrict the number of triples with the focus node as the subject and the given property as the predicate.

Property Value Type Summary
sh:minCount xsd:integer The minimum cardinality. Default value is 0.
sh:maxCount xsd:integer The maximum cardinality. Default interpretation is unlimited.
TEXTUAL DEFINITION
The default value of sh:minCount is 0. Let ?count be the number of triples that have the focus node as the subject and the sh:predicate as the predicate. A validation result must be produced in either of the following cases: If ?count is less than the value of sh:minCount, or if sh:maxCount is present and ?count is greater than the value of sh:maxCount. The produced validation result must have the focus node as its sh:subject, and the predicate as its sh:predicate.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) $predicate
WHERE {
	{
		SELECT (COUNT(?value) AS ?count)
		WHERE {
			$this $predicate ?value .
		}
	}
	FILTER (?count < $minCount || (bound($maxCount) && ?count > $maxCount))
}
Example 15: Shape with sh:minCount and sh:maxCount constraints
ex:CountExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:minCount 1 ;
		sh:maxCount 1 ;
	] .

ex:CountExampleValidResource
	ex:someProperty ex:OneValue .

3.1.6 sh:minLength, sh:maxLength

The properties sh:minLength and sh:maxLength restrict the string length of objects of triples with the focus node as the subject and the given property as the predicate. This can be applied to any type of literal and IRIs, but not for blank nodes.

Property Value Type Summary
sh:minLength xsd:integer The minimum length. Default value is 0.
sh:maxLength xsd:integer The maximum length. Default interpretation is unlimited.
TEXTUAL DEFINITION
The default value of sh:minLength is 0. A validation result must be produced for each triple that has the focus node as its subject, the sh:predicate as its predicate and where the length of the string representation (as defined by the SPARQL str function) of the object is either less than the specified minimum length or more than the specified maximum length, or if the object is a blank node. Each produced validation result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective violating value as its sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER NOT EXISTS {
		BIND (STRLEN(str(?value)) AS ?valueLength) .
		FILTER (bound(?valueLength) && 
			(?valueLength >= COALESCE($minLength, 0)) &&
			(!bound($maxLength) || ?valueLength <= $maxLength)) .
	}
}
Example 16: Shape with sh:minLength and sh:maxLength constraints
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" .

3.1.7 sh:minExclusive, sh:minInclusive, sh:maxExclusive, sh:maxInclusive

The properties from the following table restrict the range of objects of triples with the focus node as the subject and the given property as the predicate. The supported datatypes of these properties are xsd:string, xsd:boolean, xsd:dateTime and all numeric datatypes such as xsd:integer.

Property Value Type Summary Definition
sh:minExclusive (supported datatypes) The minimum exclusive value <
sh:minInclusive (supported datatypes) The minimum inclusive value <=
sh:maxExclusive (supported datatypes) The maximum exclusive value >
sh:maxInclusive (supported datatypes) The maximum inclusive value >=
TEXTUAL DEFINITION
A validation result must be produced for each triple that has the focus node as its subject, the sh:predicate as its predicate and where the object does not match the literal range specified by the table above, using the semantics of the SPARQL operators <, <=, > and >=. A validation result must also be produced if the object cannot be compared to the specified range. Each produced validation result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective violating value as its sh:object.

Note that if the comparison cannot be performed, for example when someone compares a string with an integer, then the engine will produce a validation result. This is different from, say, a plain SPARQL query, in which such failures would silently not lead to any results.

The following SPARQL definition covers sh:minExclusive - the other variations can be derived by replacing the > operator.

SPARQL DEFINITION
SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (!($value > $minExclusive)) .
}
Example 17: Shape with sh:minInclusive and sh:maxInclusive constraints
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" .

3.1.8 sh:nodeKind

The property sh:nodeKind can be used to restrict the RDF node kind of all values of the given property.

Property Value Type Summary
sh:nodeKind sh:NodeKind Node kind (IRI, blank node, or literal) of all values

The values of sh:nodeKind must be instances of the class sh:NodeKind. The SHACL system vocabulary defines that sh:NodeKind has exactly 3 instances: sh:BlankNode, sh:IRI and sh:Literal.

TEXTUAL DEFINITION
A validation result must be produced for each triple that has the focus node as its subject, the sh:predicate as its predicate and where the object does not match the given node kind. Each produced validation result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective violating value as its sh:object.
SPARQL DEFINITION
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)) .
	}
}
Example 18: Shape with sh:nodeKind constraint
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" .

3.1.9 sh:pattern

The property sh:pattern can be used to validate whether all values of the given property match a given regular expression. The values of sh:pattern must be valid pattern arguments for the SPARQL REGEX function.

Property Value Type Summary
sh:pattern xsd:string Regular expression that all values must match
TEXTUAL DEFINITION
A validation result must be produced for each triple that has the focus node as its subject, the sh:predicate as its predicate and where the string representation (as defined by the SPARQL str function) of the object does not match the given regular expression (as defined by the SPARQL REGEX function). Each produced validation result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective violating value as its sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (isBlank(?value) || !regex(str(?value), $pattern)) .
}
Example 19: Shape with sh:pattern constraint
ex:PatternExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:pattern "^Ali" ;
	] .

ex:PatternShapeExampleValidResource
	ex:someProperty "Alice" .

ex:PatternShapeExampleInvalidResource
	ex:someProperty "The Alice" .

3.1.10 sh:valueClass

The property sh:valueClass can be used to verify that each value of the given property is an instance of a given type. The values of sh:valueClass must be classes (instances of rdfs:Class). The main difference with sh:directValueType is that sh:valueClass also includes subclasses of the type.

Property Value Type Summary
sh:valueClass rdfs:Class Type of all values
TEXTUAL DEFINITION
A validation result must be produced for each triple that has the focus node as its subject, the sh:predicate as its predicate and where the object is either a literal or a non-literal without a matching rdf:type. A non-literal matches a type if it has an rdf:type value that is the type or one of its (transitive) subclasses, via rdfs:subClassOf. If the value class is rdfs:Resource then all resources match, including untyped resources. Finally, if the value class is rdf:List then the object matches if it has an rdf:first triple. Each produced validation result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective violating value as its sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) $predicate (?value AS ?object)
WHERE {
	$this $predicate ?value .
	FILTER (isLiteral(?value) || 
		!(
			$valueClass = rdfs:Resource ||
			($valueClass = rdf:List && EXISTS { $value rdf:first ?any }) ||
			EXISTS { $value rdf:type/rdfs:subClassOf* $valueClass }
		))
	}
}
Example 20: Shape with sh:valueClass constraint
ex:ValueClassExampleShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:someProperty ;
		sh:valueClass ex:ClassA ;
	] .
	
ex:InstanceOfClassA
	a ex:ClassA .

ex:ValueClassExampleValidResource
	ex:someProperty ex:InstanceOfClassA .

3.1.11 sh:valueShape

The property sh:valueShape can be used verify that all values of the given property must have a given shape. The value type of sh:valueShape is sh:Shape, but the rdf:type triple of those shapes can be omitted.

Property Value Type Summary
sh:valueShape sh:Shape The required shape of all values
TEXTUAL DEFINITION
A validation result must be produced for each triple that has the focus node as its subject, the sh:predicate as its predicate and where validating the object against the shape specified by sh:valueShape produces any validation results with severity sh:Violation or a failure. Each produced validation result must have the focus node as its sh:subject, the sh:predicate as its sh:predicate and the respective violating value as its sh:object.
SPARQL DEFINITION
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) .
}
Issue 22: Recursion of sh:valueShape

It is not yet decided how to handle recursive shape definitions in sh:valueShape and similar constructs.

In the following example, all values of the property ex:someProperty are supposed to validate with no results for the shape specified by a blank node that ensures that the property ex:nestedProperty has at least one value.

Example 21: Shape with sh:valueShape constraint
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 ;
	] .

3.1.12 sh:qualifiedValueShape, sh:qualifiedMinCount, sh:qualifiedMaxCount

The property sh:qualifiedValueShape can be used verify that a certain number of values of the given property must have a given shape. The value type of sh:qualifiedValueShape is sh:Shape, and it needs to be accompanied by a sh:qualifiedMinCount or a sh:qualifiedMaxCount (both typed xsd:integer), or both. The rdf:type of the value shapes can be omitted.

Property Value Type Summary
sh:qualifiedValueShape sh:Shape The required shape of the specified values
sh:qualifiedMinCount xsd:integer The minimum number of values that must have the shape
sh:qualifiedMaxCount xsd:integer The maximum number of values that can have the shape
TEXTUAL DEFINITION
A validation result must be produced if the number of triples that have the focus node as its subject, the sh:predicate as its predicate and where validating the object against the shape specified by sh:qualifiedValueShape produces no validation results with severity sh:Violation or a failure is outside of the interval specified by sh:qualifiedMinCount and sh:qualifiedMaxCount. The interval defaults to 0 if the min count is not specified, and unlimited if the max count is not specified. The produced validation result must have the focus node as its sh:subject, and the sh:predicate as its sh:predicate.
SPARQL DEFINITION
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
			{
				FILTER EXISTS { $this $predicate ?value } .
				$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) || (bound($qualifiedMaxCount) && (?count > $qualifiedMaxCount)))) .
}

In the following example, the property ex:parent must have exactly two values, and at least one of them needs to be female.

Example 22: Shape with sh:qualifiedValueShape constraint
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 .

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:

Example 23: Shape with an inverse property constraint
ex:InversePropertyConstraintExampleShape
	a sh:Shape ;
	sh:inverseProperty [
		sh:predicate ex:someProperty ;  # e.g. "child"
		sh:minCount 1 ;
		rdfs:label "is someProperty of" ;  # e.g. "parent"
	] .

3.3 Property Pair Constraints

SHACL includes a collection of constraint types that are about a given pair of properties at the same focus node. All constraint types in this section take the following arguments:

Property Value Type Summary
sh:predicate1 rdf:Property The first property being constrained.
sh:predicate2 rdf:Property The second property being constrained.

The values of sh:predicate1 and sh:predicate2 must be distinct.

3.3.1 sh:EqualConstraint

The sh:EqualConstraint constrains a pair of properties so that the value sets of both properties at a given focus node must be equal.

TEXTUAL DEFINITION
A validation result must be produced for each value of sh:predicate1 that does not exist as value of sh:predicate2 and for each value of sh:predicate2 that does not exist as value of sh:predicate1 at the given focus node. The produced validation result must have the corresponding values of the existing triple as sh:subject, sh:predicate and sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) ?predicate ?object
WHERE {
	{
		$this $predicate1 ?object .
		FILTER NOT EXISTS {
			$this $predicate2 ?object .
		}
		BIND ($predicate1 AS ?predicate) .
	}
	UNION
	{
		$this $predicate2 ?object .
		FILTER NOT EXISTS {
			$this $predicate1 ?object .
		}
		BIND ($predicate2 AS ?predicate) .
	}
}

The following example illustrates the use of sh:EqualConstraint in a shape to verify that certain nodes must have the same value sets for ex:firstName and ex:givenName.

Example 24: Shape with an sh:EqualsConstraint
ex:EqualExampleShape
	a sh:Shape ;
	sh:constraint [
		a sh:EqualsConstraint ;
		sh:predicate1 ex:firstName ;
		sh:predicate2 ex:givenName ;
	] .

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

3.3.2 sh:NotEqualConstraint

The sh:NotEqualConstraint constrains a pair of properties so that the value sets of both properties at a given focus node must not share any values.

TEXTUAL DEFINITION
A validation result must be produced for each value of sh:predicate1 that also exists as value of sh:predicate2 at the given focus node. The produced validation result must have the focus node as its sh:subject, the sh:predicate1 as its sh:predicate and the value as its sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) ($predicate1 AS ?predicate) ?object
WHERE {
	$this $predicate1 ?object .
	$this $predicate2 ?object .
}

The following example illustrates the use of sh:NotEqualConstraint in a shape to verify that certain nodes must not share any values for ex:prefLabel and ex:altLabel.

Example 25: Shape with an sh:NotEqualConstraint
ex:NotEqualExampleShape
	a sh:Shape ;
	sh:constraint [
		a sh:NotEqualsConstraint ;
		sh:predicate1 ex:prefLabel ;
		sh:predicate2 ex:altLabel ;
	] .

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

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

3.3.3 sh:LessThanConstraint

The sh:LessThanConstraint constrains a pair of properties so that the values of the first property must be smaller than the values of the second property at a given focus node.

TEXTUAL DEFINITION
A validation result must be produced for each pair of values of sh:predicate1 and sh:predicate2 at the given focus node, where the first value is not less than the second value, based on SPARQL's < operator. A validation result must also be produced if the two values cannot be compared. The produced validation result must have the focus node as its sh:subject, the sh:predicate1 as its sh:predicate and the value of the first predicate as its sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) ($predicate1 AS ?predicate) ?object
WHERE {
	$this $predicate1 ?object .
	$this $predicate2 ?object2 .
	FILTER (!(?object < ?object2)) .
}

The following example illustrates the use of sh:LessThanConstraint in a shape to verify that all values of ex:startDate must "before" the values of ex:endDate.

Example 26: Shape with an sh:LessThanConstraint
ex:LessThanExampleShape
	a sh:Shape ;
	sh:constraint [
		a sh:LessThanConstraint ;
		sh:predicate1 ex:startDate ;
		sh:predicate2 ex:endDate ;
	] .

3.3.4 sh:LessThanOrEqualConstraint

The sh:LessThanOrEqualConstraint constrains a pair of properties so that the values of the first property must be smaller than or equal to the values of the second property at a given focus node.

TEXTUAL DEFINITION
A validation result must be produced for each pair of values of sh:predicate1 and sh:predicate2 at the given focus node, where the first value is not less than or equal to the second value, based on SPARQL's <= operator. A validation result must also be produced if the two values cannot be compared. The produced validation result must have the focus node as its sh:subject, the sh:predicate1 as its sh:predicate and the value of the first predicate as its sh:object.
SPARQL DEFINITION
SELECT $this ($this AS ?subject) ($predicate1 AS ?predicate) ?object
WHERE {
	$this $predicate1 ?object .
	$this $predicate2 ?object2 .
	FILTER (!(?object <= ?object2)) .
}

3.4 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.

3.4.1 sh:NotConstraint

SHACL supports a high-level negation constraint that can be used to verify that the focus node does not have a given shape. This is comparable to a logical "not" operator.

Property Value Type Summary
sh:shape sh:Shape The shape to negate
TEXTUAL DEFINITION
A validation result must be produced if the focus node produces no validation results with severity sh:Violation for the shape given via sh:shape. A failure must be reported if the validation of the shape produces a failure.
SPARQL DEFINITION
SELECT $this ?failure
WHERE {
	BIND (sh:hasShape($this, $shape, $shapesGraph, true) AS ?hasShape) .
	BIND (!bound(?hasShape) AS ?failure) .
	FILTER (?failure || ?hasShape) .
}

The following example illustrates the use of sh:NotConstraint in a shape to verify that certain nodes cannot have any value of ex:property.

Example 27: Shape with a negation
ex:NotExampleShape
	a sh:Shape ;
	sh:constraint [
		a sh:NotConstraint ;
		sh:shape [
			a sh:Shape ;
			sh:property [
				sh:predicate ex:property ;
				sh:minCount 1 ;
			] ;
		]
	] .

ex:InvalidInstance1
  	ex:property "Some value" .

3.4.2 sh:AndConstraint

SHACL supports a high-level syntax for conjunctive constraints that can be used to test whether the focus node has all out of several shapes. This is comparable to a logical "and" operator.

Property Value Type Summary
sh:shapes rdf:List (members: sh:Shape) List of shapes to validate
TEXTUAL DEFINITION
A validation result must be produced if the following condition is false: The validation of the focus node against all of the shapes in the sh:shapes list produces a validation result with severity sh:Violation for at least one shape. A failure must be produced if the validation of one of the shapes fails.
SPARQL DEFINITION
SELECT $this ?failure
WHERE {
	{
		SELECT (SUM(?s) AS ?count)
		WHERE {
			GRAPH $shapesGraph {
				$shapes 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) .
}

The following example illustrates the use of sh:AndConstraint in a shape to verify that certain nodes have exactly one value of ex:property. This is achieved via the conjunction of a separate named shape (ex:SuperShape) which defines the minimum count, and a blank node shape that further constrains the maximum count. As shown here, sh:AndConstraint can be used to implement a specialization mechanism between shapes.

Example 28: Shape with a conjunction
ex:SuperShape
	a sh:Shape ;
	sh:property [
		sh:predicate ex:property ;
		sh:minCount 1 ;
	] .

ex:ExampleAndShape
	a sh:Shape ;
	sh:constraint [
		a sh:AndConstraint ;
		sh:shapes (
			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" .

3.4.3 sh:OrConstraint

SHACL supports a high-level syntax for disjunctive constraints that can be used to test whether the focus node has at least one out of several shapes. This is comparable to a logical "or" operator.

Property Value Type Summary
sh:shapes rdf:List (members: sh:Shape) List of shapes to validate
TEXTUAL DEFINITION
A validation result must be produced if the following condition is false: The validation of the focus node against all of the shapes in the sh:shapes list produces no validation results with severity sh:Violation for at least one shape. A failure must be produced if the validation of one of the shapes fails.
SPARQL DEFINITION
SELECT $this ?failure
WHERE {
	{
		SELECT (SUM(?s) AS ?count)
		WHERE {
			GRAPH $shapesGraph {
				$shapes 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) .
}

The following example illustrates the use of sh:OrConstraint in a shape to verify that certain nodes have at least one value of ex:exampleProperty1 or at least one value of ex:exampleProperty2.

Example 29: Shape with a disjunction
ex:OrConstraintExampleShape
	a sh:Shape ;
	sh:constraint [
		a sh:OrConstraint ;
		sh:shapes (
			[
				sh:property [
					sh:predicate ex:exampleProperty1 ;
					sh:minCount 1 ;
				]
			]
			[
				sh:property [
					sh:predicate ex:exampleProperty2 ;
					sh:minCount 1 ;
				]
			]
		)
	] .
	
ex:OrConstraintExampleValidResource
	ex:exampleProperty1 ex:someValue .

3.4.4 Closed Shapes (sh:ClosedShapeConstraint)

The RDF data model offers a huge amount of flexibility. Any resource can in principle have values for any property. However, in some cases it makes sense to restrict which properties can be applied to resources. The SHACL core language includes a construct called sh:ClosedShapeConstraint that can be assigned to a shape via the property sh:constraint to indicate that valid resources must only have values for those properties that have been explicitly declared via sh:property.

Property Value Type Summary
sh:ignoredProperties rdf:List (members: rdf:Property) Optional list of properties that are also permitted in addition to those explicitly enumerated via sh:property
TEXTUAL DEFINITION
A validation result must be produced for each triple that has the focus node as its subject and a predicate that is not explicitly enumerated as a sh:predicate of the sh:property constraints at the surrounding shape. If the argument sh:ignoredProperties is present then the properties enumerated in this list are also permitted. The produced validation result must have the corresponding values of the triple as sh:subject, sh:predicate and sh:object.

The core vocabulary includes an instance of sh:ClosedShapeConstraint called sh:Closed that can be used in places where no other arguments such as sh:ignoredProperties are needed.

SPARQL DEFINITION
SELECT $this ($this AS ?subject) ?predicate ?object
WHERE {
	$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 .
		}
	}))
}

The following example illustrates the use of sh:ClosedShapeConstraint in a shape to verify that certain nodes only have values for ex:exampleProperty1 and ex:exampleProperty2. The "ignored" properties sh:nodeShape and rdf:type would also be allowed.

Example 30: A closed shape
ex:ClosedShapeExampleShape
	a sh:Shape ;
	sh:constraint [
		a sh:ClosedShapeConstraint ;
		sh:ignoredProperties (sh:nodeShape 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 .

4. Declaring the Shapes Graph

A data graph MAY link to one or more shapes graphs via the property sh:shapesGraph. The subject of this predicate must be the graph resource, i.e. the name of the data graph in the dataset. The objects of this predicate must be IRI nodes, pointing at a named graph in the dataset. Tools may use this information to determine which shapes graph to use for validation. If present, tools SHOULD transitively follow any links from the shapes graph via the predicate owl:imports to other graphs and use the resulting union graph as parameter to the validation process.

In the following example, a tool may use the named graph <http://example.org/graph-shapes> and its imports as the shapes graph when validating the given graph.

Example 31: A data graph declaring a shapes graph
<http://example.org/graph>
	sh:shapesGraph <http://example.org/graph-shapes> .

ex:MyInstance
	a ex:MyClass .

5. Validation Results Vocabulary

The output of a SHACL constraint validation process is a set of validation results. SHACL includes an RDF vocabulary to represent such results together with structural information that may provide guidance on how to fix a violation, as well as human-readable messages.

The following code snippet represents a syntactically correct result that may have been produced by a constraint validation engine:

Example 32: A constructed validation result
ex:ExampleConstraintViolation
	a sh:ValidationResult ;
	sh:severity sh:Violation ;
	sh:focusNode ex:MyCurrentNode ;
	sh:subject ex:MyCurrentNode ;
	sh:predicate ex:someProperty ;
	sh:object ex:someInvalidValue ;
	sh:message "Incorrect value: expected something else here." .

Validation results must be instances of the class sh:ValidationResult. Its superclass sh:AbstractResult defines the properties described in the following sub-sections. SHACL implementations may produce instances of other subclasses of sh:AbstractResult, for example to report successfully completed constraint checks or accumulated results.

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 validated 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.

Severity Description
sh:Info An informative message, not a violation.
sh:Warning A non-critical constraint violation indicating a warning.
sh:Violation A constraint violation that should be fixed.

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.

Example 33: Declaring the Severity using sh:severity
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 for sh:maxCount)
		sh:predicate ex:myProperty ;
		sh:maxCount 1 ;
	] ;
.

Part 2: Advanced Features

Part 1 of this specification has introduced features that are built into the Core of SHACL. The goal of this Core was to provide a high-level vocabulary for common use cases to describe shapes. However, SHACL also provides mechanisms to go beyond the Core vocabulary and represent constraints and scopes with greater flexibility. These mechanisms are described in the sections of Part 2.

6. Native Constraints

The property sh:constraint provides the most general mechanism to associate a constraint with a shape. The values of this property must be constraints - instances of the class sh:Constraint. Note that the property sh:property SHOULD be used instead of sh:constraint if the constraint is a sh:PropertyConstraint. The property sh:inverseProperty SHOULD be used instead of sh:constraint if the constraint is a sh:InversePropertyConstraint.

SHACL supports two types of general constraints:

The following sub-sections are about the latter, while templates are covered at a later stage.

6.1 An Example Native Constraint

This section is non-normative.

For the sake of this example, we assume a data graph containing the following instances:

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

The following example illustrates the definition of a native constraint based on a SPARQL query. The property sh:sparql is used to point at a SELECT query as explained in a later section.

Example 35: Example Shape with a native SPARQL constraint
ex:LanguageExampleShape
	a sh:Shape ;
	sh:scopeClass ex:Country ;
	sh:constraint [
		sh:message "Values must be literals with German language tag." ;
		sh:sparql """
			SELECT $this ($this AS ?subject) (ex:germanLabel AS ?predicate) (?value AS ?object)
			WHERE {
				$this ex:germanLabel ?value .
				FILTER (!isLiteral(?value) || !langMatches(lang(?value), "de"))
			}
			""" ;
	] .

The scope of the shape includes all instances of ex:Country. For those instances (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 output of the graph validation for the instances above is shown in the next example:

Example 36: Example validation results
[
	a sh:ValidationResult ;
	sh:severity sh:Violation ;
	sh:focusNode ex:InvalidCountry ;
	sh:subject ex:InvalidCountry ;
	sh:predicate ex:focusNode ;
	sh:object "Spain"@en ;
	sh:sourceShape ex:LanguageExampleShape ;
	...
]

The SPARQL query returns result set rows for all bindings of ?value that violate the constraint. A validation result is produced for each row in that result set, using $this as the sh:focusNode and sh:subject, ex:germanLabel as sh:predicate and the violating value as sh:object.

In the example above, it is assumed that the existing SHACL engine is capable of evaluating native constraints using SPARQL, as described in the following section. Additional executable languages such as JavaScript may be provided based on other sets of properties like ex:javaScript, but that is outside of the scope of this specification.

6.2 SPARQL-based Native Constraints

Native constraints are instances of sh:NativeConstraint, which is a subclass of sh:Constraint. However, the rdf:type triple of native constraints can be ommitted for typeless resources that are object of a sh:constraint triples. If a native constraint has a value for the property sh:sparql then it can be considered to be a native SPARQL constraint. 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 pre-pend PREFIX statements for all namespace prefixes defined in the current shapes graph.

6.2.1 Pre-bound Variables in SPARQL Constraints ($this, $shapesGraph, $currentShape)

When SPARQL constraints are executed, the engine must pre-bind values for the following variables with special meaning. The effect of this pre-binding is that all occurrences of these variables in the top-level query will have the provided values, similar to inserting a SPARQL VALUES clause into the beginning of the query, but also supporting blank nodes.

Issue 68: Pre-binding of Variables in SPARQL

We need a suitable formal definition of what pre-binding means - the statement above with VALUES may not be entirely correct.

Variable Interpretation
$this The focus node.
$shapesGraph The named graph containing the shape definitions (and possibly other data). Can be used as in GRAPH $shapesGraph { ... } to query shapes, constraints, background data and complex arguments such as rdf:Lists.
$currentShape The currently validated shape. Typically used in conjunction with $shapesGraph.
Issue 47: Access to $shapesGraph
There is no consensus yet if and under which conditions SPARQL queries can access the shapes graph. This document assumes that access exists.

6.2.2 Mapping of Result Variables to Validation Results

Each row of the result set produced by a SELECT query must be converted into one validation result resource. The properties of those resources are derived by the following rules, through a combination of result variables and the properties linked to the constraint itself. The production rules are meant to be executed from top to bottom, so that the first bound value will be used.

Property Production Rules
sh:severity
  1. For template constraints, the value of sh:severity of the constraint node (template instance)
  2. The value of sh:severity of the subject of the sh:sparql triple
  3. sh:Violation as default
sh:focusNode
  1. The value of the variable $this
sh:subject
  1. The value of the variable ?subject
sh:predicate
  1. The value of the variable ?predicate
sh:object
  1. The value of the variable ?object
sh:message
  1. The value of the variable ?message
  2. The values of sh:message of the subject of the sh:sparql triple. These values may reference any variable from the SELECT result variables via {?varName}. If the constraint is a template constraint, then the template's argument variables can also be used. The {?varName} blocks SHOULD be substituted with suitable string representations of the values of said variables.
sh:sourceConstraint
  1. The constraint that was validated
sh:sourceShape
  1. The shape that was validated

6.2.3 Injecting Annotation Properties into Validation Results

It is possible to inject additional annotation properties into the validation result resources created for each row of the SELECT result sets. Any such property needs to be declared via a value of sh:resultAnnotation at the subject holding the sh:sparql triple. The values of sh:resultAnnotation must be IRIs or blank nodes with the following properties:

Property Value type Count Description
sh:annotationProperty rdf:Property 1 (mandatory) The annotation property that shall be set
sh:annotationVarName xsd:string 0..1 The name of the SPARQL variable to take the values from
sh:annotationValue 0..unlimited Constant nodes that shall be used as values

If a sh:resultAnnotation defines a sh:annotationVarName then the engine must copy the bindings for the given variable into the constructed validation results for the same row.

The values of sh:annotationProperty must not be from the SHACL namespace, to avoid clashes with variables that are already produced by other means.

Here is a slightly complex example, illustrating the use of result annotations.

Example 37: Constraint with an annotation
ex:ShapeWithPathViolationExample
	a sh:Shape ;
	sh:constraint [
		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
	sh:nodeShape ex:ShapeWithPathViolationExample ;
	ex:property1 ex:ExampleIntermediateResource .

ex:ExampleValueResource
	ex:property2 ex:ExampleIntermediateResource .

Which produces the following validation result resource:

Example 38: Constraint example result output
[
	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. Template Constraints

Native constraints in a language like SPARQL as introduced in the previous section typically provide a lot of flexibility. However, SPARQL-based constraints may also be hard to understand for some people, and may be repetitive. Templates can be used to encapsulate and parameterize such native queries. Constraint templates can be instantiated anywhere where a native constraint may appear (in particular, at sh:constraint). Scope templates can be instantiated anywhere where a native scope may appear, at sh:scope. All of the constraint and scope types built into the SHACL Core are also represented as templates in the SHACL RDF vocabulary. Such templates form a high-level vocabulary that may also be directly interpreted ("hard-coded") without reliance on the fact that they are templates.

Constraint templates are represented as IRI nodes that are instances of the class sh:ConstraintTemplate. Scope templates are represented as IRI nodes that are instances of the class sh:ScopeTemplate. SHACL also includes a more general superclass sh:Template that may be used for other kinds of templates (rules, stored queries etc). Well-defined, non-abstract templates must provide at least one body using a property such as sh:sparql.

7.1 An Example Template Constraint

This section is non-normative.

The following example illustrates the definition of a constraint template based on a SPARQL query. It is a variation of the native example constraint from the previous section. That SPARQL query included two constants: the specific property ex:germanLabel and the language tag de. Templates make it possible to generalize such scenarios, so that constants get substituted with arguments. This allows the query logic to be reused in multiple places, without having to write any new SPARQL.

Example 39: Constraint template based on SPARQL
ex:LanguageConstraint
	a sh:ConstraintTemplate ;
	rdfs:label "Language constraint" ;
	rdfs:subClassOf sh:TemplateConstraint ;
	sh:argument [
		sh:predicate ex:predicate ;
		sh:valueClass rdf:Property ;
		rdfs:label "predicate" ;
		rdfs:comment "The property to validate the values of." ;
    ] ;
	sh:argument [
		sh:predicate ex:lang ;
		sh:datatype xsd:string ;
		rdfs:label "language" ;
		rdfs:comment "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))
		}
		""" .

Once a template has been defined, it can be instantiated as a constraint, as illustrated in the following example:

Example 40: Shape definition using ex:LanguageConstraint
ex:TemplateLanguageExampleShape
	a sh:Shape ;
	sh:scopeClass ex:Country ;
	sh:constraint [
		a ex:LanguageConstraint ;
		ex:predicate ex:germanLabel ;
		ex:lang "de" ;
	] ;
	sh:constraint [
		a ex:LanguageConstraint ;
		ex:predicate ex:englishLabel ;
		ex:lang "en" ;
	] .

The example shape above specifies that all values of ex:germanLabel must carry the language tag de while all values of ex:englishLabel must have en as their language. These details are specified via two instances of ex:LanguageConstraint that provide values for the arguments required by the template.

The following sections introduce the properties that constraint templates may have. All of these properties except for sh:sparql are independent of SPARQL-based execution and apply to constraint templates based on other languages such as JavaScript too. A later section provides additional details for SPARQL-based SHACL templates.

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):

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 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:valueClass 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 validated - 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.

Example 41: An example property constraint template with a shape that uses it
ex:LanguagePropertyConstraint
	a sh:ConstraintTemplate ;
	rdfs:subClassOf sh:PropertyConstraint ;
	sh:argument [
		sh:predicate ex:lang ;
		sh:datatype xsd:string ;
		rdfs:label "language" ;
		rdfs:comment "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 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.

Example 42: Template definition using a validation function
ex:LanguageConstraint
	a sh:PropertyValueConstraintTemplate ;
	rdfs:label "Language constraint" ;
	rdfs:subClassOf sh:TemplateConstraint ;
	sh:argument [
		sh:predicate ex:predicate ;
		sh:valueClass rdf:Property ;
		rdfs:label "predicate" ;
		rdfs:comment "The property to validate the values of." ;
    ] ;
	sh:argument [
		sh:predicate ex:lang ;
		sh:datatype xsd:string ;
		rdfs:label "language" ;
		rdfs:comment "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 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 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. General Scopes (sh:scope)

In addition to the scope classes introduced in the core section, such as sh:PropertyScope, SHACL provides facilities to define custom scopes. Similar to constraints, scopes may either have be native scopes or be an instance of sh:TemplateScope. All this is analogous to how constraints work, but with the additional restrictions:

8.1 SPARQL-based Scopes

The SPARQL queries linked to a scope via sh:sparql must be of the query form SELECT, or a fragment that produces a valid SELECT query if wrapped by SELECT ?this WHERE { ... }. 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 engines can validate whether a given shape applies to a given focus node as part of the validateNode operation.

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

Example 43: SPARQL-based scope example
ex:USCitizenShape
	a sh:Shape ;
	sh:scope [
		sh:sparql """
			SELECT ?this
			WHERE {
				?this a ex:Person .
				?this ex:bornIn ex:USA .
			}
			""" ;
	] ;
	sh:constraint ...

9. Functions

SHACL functions define operations that produce an RDF node based on zero or more arguments and a dataset. Functions can be called within SPARQL queries to encapsulate complex logic of other SPARQL queries, or executable logic in other languages such as JavaScript. However, the general declaration mechanism for SHACL functions is independent from SPARQL and may also be exploited by other environments.

Functions must be declared as instances of the class sh:Function. Well-defined, non-abstract functions must provide at least one body property such as sh:sparql.

9.1 An Example Function

This section is non-normative.

The following example illustrates the definition of a function based on a SPARQL query.

Example 44: SHACL function with a SPARQL body
ex:exampleFunction
	a sh:Function ;
	rdfs:comment "Computes the sum of its two arguments ?arg1 and ?arg2." ;
	sh:returnType xsd:integer ;
	sh:argument [
		sh:predicate sh:arg1 ;
		sh:datatype xsd:integer ;
		rdfs:comment "The first operand" ;
	] ;
	sh:argument [
		sh:predicate sh:arg2 ;
		sh:datatype xsd:integer ;
		rdfs:comment "The second operand" ;
	] ;
	sh:sparql """
		SELECT ($arg1 + $arg2 AS ?result)
		WHERE {
		}
		""" .

Based on the declaration above, SPARQL engines with full SHACL support can handle expressions such as ex:exampleFunction(40, 2), producing 42.

The following sections introduce the properties that all such functions may have. A later section provides additional details for SPARQL-based SHACL functions.

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. Arguments are ordered, corresponding to the notation of function calls in SPARQL such as ex:exampleFunction(?arg1, ?arg2).

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.

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:index at the surrounding sh:Argument.
  3. The default index for all other cases is the number of other arguments. This means that non-built-in arguments without a sh:index will be placed at the end of the order.

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:valueClass. 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 the engine how to cast a native value into an RDF value type.

9.4 sh:cachable

A sh:Function may have a property sh:cachable set to true. Functions that are marked as cachable must always return the same value for the same combination of arguments, regardless of the query graphs. Engines can use this information to cache and reuse previous function calls without repeatedly executing their body.

9.5 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:index values larger than 1. The following example illustrates a validation function for the running example of the section on constraint templates.

Example 45: A validation function
ex:hasLanguage
	a sh:Function ;
	rdfs:subClassOf sh:ValidationFunctions ;
	sh:argument [
		sh:predicate ex:lang ;
		sh:datatype xsd:string ;
		sh:index 1 ;
		rdfs:label "language" ;
		rdfs:comment "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.6 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 engine 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.

Some execution 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.

10. Supported Operations

Issue: Specification of Operations
It is undecided to what extent this (operations) section is needed, and to what level of detail it should be specified. For now we present some high-level functions, but more details would be useful.

This section enumerates the basic operations that complete SHACL engines SHOULD support. The specification does not prescribe how these operations are exposed to the user of a SHACL system. The functions are written in Java, assuming the presence of the following basic interfaces:

// Represents RDF nodes: literals, IRIs or blank nodes.
interface Node {
}

// Represents an RDF triple
interface Triple {
	Node getSubject();
	Node getPredicate();
	Node getObject();
}

// Represents an RDF Graph
interface Graph {
	// Find operation - each argument may be null to indicate a wildcard
	Set<Triple> find(Node subject, Node predicate, Node object);
}

interface Dataset {
	Graph getDefaultGraph();
	Graph getNamedGraph(String iri);
}

The code snippets also assume access to interfaces defining constants for the various namespaces used in the code. For example, the value of SH.Shape is the IRI String for the sh:Shape class.

All operations have access to the following fields:

Field Type Description
dataset Dataset The dataset to operate on, must have a default graph and contain the shapesGraph
dataGraph Graph The default Graph of the dataset
shapesGraph Graph The shapes Graph
shapesGraphIRI String The IRI of the shapes Graph
resultsGraph Graph The Graph that will contain the validation results after completion

All operations produce validation results. For the sake of this specification, we assume that the validation results are represented as instances of sh:ValidationResult that are added to the resultsGraph. Actual implementations may use different data structures and result formats and input and output to these operations.

10.1 validateGraph

This operation validates a whole data graph against all shapes associated with its resources, based on the available scope definitions.

Argument Type Description
minSeverity String The IRI of the minimum severity, e.g. SH.Violation specifying which constraints to exclude/include.
void validateGraph(String minSeverity) {
	for(Node shape : getAllInstances(iri(SH.Shape), shapesGraph)) {
		validateShape(shape, minSeverity);
	}
}

10.2 validateShape

Validates all nodes that are in the scope of a given shape against the constraints of that shape.

Argument Type Description
shape Node The Node representing the shape to validate
minSeverity String The IRI of the minimum severity, e.g. sh:Violation specifying which constraints to exclude/include.
void validateShape(Node shape, String minSeverity) {
	for(Node focusNode : getNodesInScopeOfShape(shape)) {
		validateNodeAgainstShape(focusNode, shape, minSeverity);
	}
}

10.3 validateNodeAgainstShape

Validates a given node against the constraints of a given shape.

Argument Type Description
focusNode Node The focus Node to validate
shape Node The Node representing the shape to validate
minSeverity String The IRI of the minimum severity, e.g. sh:Violation specifying which constraints to exclude/include.
boolean validateNodeAgainstShape(Node focusNode, Node shape, String minSeverity) {
	boolean hasResults = false;
	if(isNodeValidForFilterShapes(focusNode, shape)) {
		for(Node constraint : getConstraintsOfShape(shape)) {
			if(hasMinSeverity(constraint, shape, minSeverity)) {
				if(isNodeValidForFilterShapes(focusNode, constraint)) {
					hasResults |= validateNodeAgainstConstraint(focusNode, constraint, shape);
				}
			}
		}
	}
	return hasResults;
}

The function returns true if there has been at least one validation result with the given minimum severity.

The helper function getConstraintsOfShape produces a Set of all values of the properties sh:constraint, sh:property, sh:inverseProperty and sh:argument for the given shape node in the shapes graph.

10.4 validateNodeAgainstConstraint

Validates a given node against a given constraints from a given shape.

Argument Type Description
focusNode Node The focus Node to validate
constraint Node The constraint to validate
shape Node The Node representing the shape containing the constraint
boolean validateNodeAgainstConstraint(Node focusNode, Node constraint, Node shape) {
	if(isNativeConstraint(constraint, shape)) {
		return executeNativeConstraint(constraint, shape, focusNode);
	}
	else {
		boolean hasResult = false;
		for(Node template : getAllTypes(constraint, shapesGraph)) {
			if(hasType(template, iri(SH.ConstraintTemplate), shapesGraph)) {
				hasResult |= executeTemplateConstraint(constraint, template, shape, focusNode);
			}
		}
		return hasResult;
	}
}

The function returns true if there has been at least one validation result with the given minimum severity.

10.5 validateNode

Validates a given node against all shapes that it is in the scope of.

Argument Type Description
focusNode Node The focus Node to validate
minSeverity String The IRI of the minimum severity, e.g. sh:Violation specifying which constraints to exclude/include.
boolean validateNode(Node focusNode, String minSeverity) {
	boolean hasResult = false;
	for(Node shape : getShapesWithNodeInScope(focusNode)) {
		hasResult |= validateNodeAgainstShape(focusNode, shape, minSeverity);
	}
	return hasResult;
}

The function returns true if there has been at least one validation result with the given minimum severity.

10.6 Validation of shapes graphs and the sh:defaultValueType property

The SHACL system vocabulary itself is using shapes, allowing SHACL constraint validation to be executed on shapes graphs, e.g. to validate the syntax of shape definitions. However, some system properties such as sh:property, sh:filterShape and sh:argument may have untyped blank nodes or IRIs as their values. If, for example, a value of sh:property is a blank node that does not have any rdf:type, then the assumption is that the blank node has type sh:PropertyConstraint. Unless these implicit triples are present in the data graph, constraint validation will not apply the constraints defined for sh:PropertyConstraint.

If an engine intends to validate the syntax of a SHACL shapes graph itself, it should (temporarily) add the missing rdf:type triples. The SHACL system vocabulary includes some helper triples using the predicate sh:defaultValueType to specify the default rdf:type for certain properties. For example, the default value type of sh:property is sh:PropertyConstraint. These triples can be queried by a pre-processor to construct the missing type triples for the affected nodes. SHACL includes a template sh:DefaultValueTypeRule which encapsulates a SPARQL query that can be used for that purpose:

CONSTRUCT {
	?node a ?defaultValueType .
}
WHERE {
	?predicate sh:defaultValueType ?defaultValueType .
	?anySubject ?predicate ?node .
	FILTER (NOT EXISTS { ?node a ?anyType }) .
}

The operations in this section assume that these default value types are present in the shapes graph, e.g. simplifying the test whether a given node is a sh:NativeConstraint.

11. Entailment

By default, SHACL does not assume any entailment regime [sparql11-entailment] to be actviated on the data graph. However, the property sh:entailment can be used to instruct a SHACL engine to ensure that a given entailment is activated. The values of sh:entailment must be IRIs, with common use cases covered by [sparql11-entailment]. The subject of sh:entailment must be the IRI of the shapes graph itself.

If the engine is not capable of supporting the given entailment regime, then it must produce a failure. Standard-compliant SHACL implementations are not required to support any entailment regimes.

Appendix

A. Glossary of Key Concepts

A.1 Shape

A.2 Constraint

A.3 Constraint Validation

A.4 Focus Node

A.5 Scope

A.6 Filter Shape

A.7 Template

A.8 Function

B. References

B.1 Normative references

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[rdf11-concepts]
Richard Cyganiak; David Wood; Markus Lanthaler. RDF 1.1 Concepts and Abstract Syntax. 25 February 2014. W3C Recommendation. URL: http://www.w3.org/TR/rdf11-concepts/
[rdf11-mt]
Patrick Hayes; Peter Patel-Schneider. RDF 1.1 Semantics. 25 February 2014. W3C Recommendation. URL: http://www.w3.org/TR/rdf11-mt/
[sparql11-entailment]
Birte Glimm; Chimezie Ogbuji. SPARQL 1.1 Entailment Regimes. 21 March 2013. W3C Recommendation. URL: http://www.w3.org/TR/sparql11-entailment/
[sparql11-overview]
The W3C SPARQL Working Group. SPARQL 1.1 Overview. 21 March 2013. W3C Recommendation. URL: http://www.w3.org/TR/sparql11-overview/
[turtle]
Eric Prud'hommeaux; Gavin Carothers. RDF 1.1 Turtle. 25 February 2014. W3C Recommendation. URL: http://www.w3.org/TR/turtle/