Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
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. The vocabulary of SHACL has been designed to support similar extension languages besides SPARQL. 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.
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 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-rdf-shapes@w3.org (subscribe, archives). All comments are welcome.
Publication as a 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.
The detailed list of changes and their diffs can be found in the Git repository.
$shapesGraph
is optional (ISSUE-47)sh:QCC
(ISSUE-92)sh:partition
. (ISSUE-92)sh:XorConstraint
as resolved, renamed sh:Error
to sh:Violation
sh:class
, editorial changes, renamed sh:ClosedShape to sh:Closed, added sh:sourceTemplateThe introduction includes a Terminology section that may also serve as a quick overview of the language.
The sections 2 - 4 cover the SHACL Core Profile and may be read independently from the later sections.
The sections 5 onwards are about the advanced features of the SHACL language, including SPARQL-based constraint components, scopes and functions.
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].
This document specifies SHACL (Shapes Constraint Language), a language for describing and constraining RDF graphs. This section introduces SHACL with an overview of the key terminology and an example to illustrate basic concepts.
Throughout this document, the following terminology is used.
p
for a node n
in an RDF graph are the
objects of the triples in the graph that have n
as subject and p
as predicate. The inverse values of (or for) a property p
for a node n
in an RDF graph are the subjects of the triples in the graph that have n
as object and p
as predicate.
Sub
in an RDF graph is a SHACL subclass of another node Super
in the graph if there is a sequence of triples in the graph each with predicate rdfs:subClassOf
such that the subject of the first triple is Sub
, the object of the last triple is Super
, and the object of each triple except the last is the subject of the next. If Sub
is a SHACL subclass of Super
in an RDF graph then Super
is a SHACL superclass of Sub
in the graph.
sh:Shape
. A shape provides a collection of scopes, filters, and constraints that specify how a data graph is validated against the shape. Shapes can also provide non-validating information, such as labels and names.
sh:minCount
is a parameter for the component that checks whether the focus node has at least a minimum number of values for a particular property. Validating a node against a constraint involves validating the node against each of its components.
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# |
ex: |
http://example.com/ns# |
Note that the URI of the graph defining the SHACL vocabulary itself is equivalent to the namespace above, i.e. it includes the #
. References to the SHACL vocabulary, e.g. via owl:imports
SHOULD include the #
.
Throughout the document, color-coded boxes containing RDF graphs in Turtle will appear. These fragments of Turtle documents use the prefix bindings given above.
# This box represents an input shapes graph
# Triples that can be ommitted are marked as grey e.g.
<s> <p> <o> .
# This box represents an input data graph. # When highlighting is used in the examples: # Elements highlighted in blue are focus nodes that are # selected by some scope of a shape under discussion # and validate against the shape's filters, if any. ex:Bob a ex:Person . # Elements highlighted in red are focus nodes that fail validation ex:Alice a ex:Person .
# This box represents an output results graph
SHACL Definitions appear in blue boxes:
# This box contains SPARQL or textual definitions.
The following example data graph contains three nodes that are SHACL instances of the class ex:Person
.
ex:Alice a ex:Person ; ex:child ex:Calvin ; ex:ssn "987-65-432A" . ex:Bob a ex:Person ; ex:child ex:Calvin ; ex:ssn "123-45-6789" ; ex:ssn "124-35-6789" . ex:Calvin a ex:Person ; ex:school ex:TrinityAnglicanSchool .
This example uses SHACL to define the following constraints:
ex:Person
may have at most one value for the property ex:ssn
, and this value must be a literal with the datatype xsd:string
that matches a specified regular expression.
ex:Person
may have unlimited values for the property ex:child
, and these values must be IRIs and they must be SHACL instances of ex:Person
.
ex:child
in the inverse direction. A SHACL instance of ex:Person
may have at most 2 parents, i.e. may be the object of at most two triples where the predicate is ex:child
.
ex:Person
may not have values for any other property apart from
ex:ssn
, ex:child
and rdf:type
.
The constraints above can be represented using the following shapes graph:
ex:PersonShape a sh:Shape ; sh:scopeClass ex:Person ; # Applies to all persons sh:property [ sh:predicate ex:ssn ; sh:maxCount 1 ; sh:datatype xsd:string ; sh:pattern "^\\d{3}-\\d{2}-\\d{4}$" ; ] ; sh:property [ sh:predicate ex:child ; sh:class ex:Person ; sh:nodeKind sh:IRI ; ] ; sh:inverseProperty [ rdfs:comment "A person's parents are represented via ex:child used in the inverse direction." ; sh:predicate ex:child ; sh:name "parent" ; sh:maxCount 2 ; ] ; sh:constraint [ sh:closed true ; sh:ignoredProperties ( rdf:type ) ; ] .
We can use the shape definition above to skim through some of the key terminology used by SHACL. The focus nodes for the shape ex:PersonShape
are all SHACL instances of the class ex:Person
. These focus nodes are the scope of the shape and are defined using the property sh:scopeClass
. The shape has two property constraints, linked to the shape using the property sh:property
, one inverse property constraint represented as value of sh:inverseProperty
, and one node constraint linked to the shape using sh:constraint
.
Some of the constraints specify multiple constraint components in order to restrict multiple aspects of the property values. For example, in the property constraint for ex:ssn
, three constraint components are used. These constraint components are identified by their parameters sh:datatype
, sh:pattern
and sh:maxCount
. For each focus node, property values of ex:ssn
will be validated against all three components. The constraint on the inverse property values of sh:child
has only one constraint component identified by the sh:maxCount
parameter. Note that this constraint uses the non-validating property sh:name
to suggest a human-readable name for the property when used in the inverse direction.
SHACL validation based on the provided data graph and shapes graph would produce the following validation results:
[ a sh:ValidationResult ; sh:sourceConstraintComponent sh:RegexConstraintComponent ; sh:focusNode ex:Alice ; sh:subject ex:Alice ; sh:predicate ex:ssn ; sh:object "987-65-432A" ; sh:severity sh:Violation ; ] ; [ a sh:ValidationResult ; sh:sourceConstraintComponent sh:MaxCountConstraintComponent ; sh:focusNode ex:Bob ; sh:subject ex:Bob ; sh:predicate ex:ssn ; sh:severity sh:Violation ; ] ; [ a sh:ValidationResult ; sh:sourceConstraintComponent sh:ClosedConstraintComponent ; sh:focusNode ex:Calvin ; sh:subject ex:Calvin ; sh:predicate ex:school ; sh:object ex:TrinityAnglicanSchool ; sh:severity sh:Violation ; ] .
The first validation result is produced because ex:Alice
has a value for ex:ssn
that does not match the regular expression specified by the property sh:regex
. The second validation result is produced because ex:Bob
has more than the permitted number of values for the property ex:ssn
as specified by the sh:maxCount
of 1. The third validation result is produced because the shape ex:PersonShape
has a node constraint using the property sh:closed
but ex:Calvin
uses the property ex:school
which is neither one of the predicates from any of the
property constraints at the shape, nor one of the properties listed using sh:ignoredProperties
.
SHACL uses the RDF and RDFS vocabularies, but full RDFS inferencing is not required. However, SHACL processors MUST identify SHACL instances of a class both in the data graph and the shapes graph without mutating either graph during the validation process. Furthermore, SHACL processors may operate on RDF graphs that include entailments - either pre-computed before being submitted to a SHACL processor or performed on the fly as part of SHACL processing. To support processing of entailments, SHACL includes the property sh:entailment
to indicate what inferencing is required by a given shapes graph. SHACL implementations may, but are not required to, support entailment regimes.
This specification uses parts of SPARQL 1.1 in the normative definition of the semantics of the SHACL Core constraints and scopes. However, SPARQL is not required for the implementation of the SHACL Core language.
SPARQL variables using $
marker represent external values that must be pre-bound in the SPARQL query before execution.
In some places, the specification assumes that the provided SPARQL engines are preserving the identity of blank nodes, so that repeated invocations of queries consistently identify and communicate the same blank nodes.
The definition of some constraints requires or is simplified through access to the shapes graph during query execution. SHACL validation engines MAY pre-bind the variable $shapesGraph
to provide access to the shapes graph. Access to the shapes graph is not a requirement for supporting the SHACL core language. The variable $shapesGraph
can also be used in user-defined SPARQL constraints and SPARQL-based constraint components. However, such constraints may not be interoperable across different SHACL validation engines or not applicable to remote RDF datasets.
Some SHACL constraints are defined with the use of the sh:hasShape
function. SHACL additionally introduces mechanisms to define constraints, scopes and new functions in SPARQL. Implementations that cover only the the SHACL Core features are not required to implement these mechanisms or the sh:hasShape
function.
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, MUST NOT, and SHOULD are to be interpreted as described in [RFC2119].
TODO: We still need to mark non-normative sections.
Shapes are SHACL instances of sh:Shape
and define one or more constraints that a set of focus nodes can be validated against. The set of focus nodes for a shape may be defined explicitly in a shape using scopes and filters. The focus nodes may also be determined as part of the validation of constraints that include references to shapes using properties such as sh:shape
and sh:or
.
Shapes can also provide non-validating information, such as labels and names. The following figure depicts a workflow of the scoping and filtering process. SHACL validation engines MAY alter the order of the depicted steps as long as the returned validation results are correct.
Scopes specify which nodes in the data graph are considered in-scope for a shape and SHACL includes six core scope types: node scopes, class-based scopes, property scopes, inverse property scopes, all subjects scopes and all objects scopes.
The SHACL language additionally defines a general scoping mechanism based on SPARQL.
When multiple scopes are provided in a shape, the scope of a shape is the union of all in-scope nodes produced by these scopes. In addition to the explicit scoping mechanism, a shape may get an implicit scope when it is mentioned from other shapes (e.g. in shape-based constraint components). Nodes specified by scopes are not required to exist in the data graph.
A node scope with value $scopeNode
, defines $scopeNode
as the node in-scope in the data graph.
SELECT DISTINCT ?this WHERE { BIND ($scopeNode AS ?this) }
Node scopes are defined with the sh:scopeNode
predicate. The values of sh:scopeNode
can be a IRIs or literals.
ex:PersonShape a sh:Shape ; sh:scopeNode ex:Alice .
ex:Alice a ex:Person .
ex:Bob a ex:Person .
With the example data above, only ex:Alice
is in-scope for the provided shape.
A class scope for class $scopeClass
is defined as the set of all SHACL instances of $scopeClass
in the data graph.
$scopeClass
must be an IRI that is expected to be a SHACL class.
SELECT DISTINCT ?this WHERE { ?this rdf:type/rdfs:subClassOf* $scopeClass }
Class scopes are defined with the sh:scopeClass
predicate.
ex:PersonShape a sh:Shape ; sh:scopeClass ex:Person .
ex:Alice a ex:Person . ex:Bob a ex:Person . ex:NewYork a ex:Place .
In this example, only ex:Alice
and ex:Bob
are in-scope. Note that, according to the SHACL instance definition, all the rdfs:subClassOf
declarations must exist in the data graph. However, the ex:Person a rdfs:Class
triple is not required to exist in either graphs.
In the following example, the selected in-scope node is only ex:Who
.
ex:Doctor rdfs:subClassOf ex:Person .
ex:Who a ex:Doctor .
ex:House a ex:Nephrologist .
When, in the shapes graph, a shape is a SHACL instance of both sh:Shape
and rdfs:Class
then the shape is a class scope of itself.
ex:Person a rdfs:Class, sh:Shape .
ex:Alice a ex:Person .
In this example, only ex:Alice
is in-scope, because it is a SHACL instance of
ex:Person
which is both a class and a shape in the shapes graph.
A property scope for property $scopeProperty
is defined as the set of subjects in the data graph that appear in a triple with $scopeProperty
as a predicate.
SELECT DISTINCT ?this WHERE { ?this $scopeProperty ?any . }
A shape defines a property scope with the predicate sh:scopeProperty
, the values of which must be IRIs.
ex:PropertyScopeExampleShape a sh:Shape ; sh:scopeProperty ex:knows .
ex:Alice ex:knows ex:Bob .
ex:Bob ex:livesIn ex:NewYork .
In the example above, only ex:Alice
is in-scope for the given shape, because it is the subject of a triple that has ex:knows
as its predicate.
An inverse property scope for property $scopeInverseProperty
is defined as the set of objects in the data graph that appear in a triple with $scopeInverseProperty
as a predicate.
SELECT DISTINCT ?this WHERE { ?any $scopeInverseProperty ?this . }
A shape defines an inverse property scope with the predicate sh:scopeInverseProperty
, the values of which must be IRIs.
ex:InversePropertyScopeExampleShape a sh:Shape ; sh:scopeInverseProperty ex:knows .
ex:Alice ex:knows ex:Bob .
ex:Bob ex:livesIn ex:NewYork .
In the example above, only ex:Bob
is in-scope for the given shape, because it is the object of a triple that has ex:knows
as its predicate.
There are proposals to either delete AllSubjectsScope and AllObjectsScope from the SHACL Core, or to change their syntax into properties similar to those above.
An all subjects scope is defined as the set of all subjects that appear in triples in the data graph.
SELECT DISTINCT ?this WHERE { ?this ?anyPredicate ?anyObject . }
A shape defines an all subjects scope with the sh:scope
predicate and object an RDF node of SHACL type sh:AllSubjectsScope
.
ex:AllSubjectsScopeExampleShape a sh:Shape ; sh:scope [ a sh:AllSubjectsScope ; ] .
ex:Alice ex:knows ex:Bob . ex:Bob ex:livesIn ex:NewYork .
In the example above, only ex:Alice
and ex:Bob
are in-scope for the given shape, because they are subjects of any triple in the data graph.
An all objects scope is defined as the set of all objects that appear in triples in the data graph.
SELECT DISTINCT ?this WHERE { ?anySubject ?anyPredicate ?this . }
A shape defines an all objects scope with the sh:scope
predicate and object an RDF node of SHACL type sh:AllObjectsScope
.
ex:AllObjectsScopeExampleShape a sh:Shape ; sh:scope [ a sh:AllObjectsScope ; ] .
ex:Alice ex:knows ex:Bob . ex:Bob ex:livesIn ex:NewYork .
In the example above, ex:Bob
and ex:NewYork
are in-scope for the given shape, because they are objects of any triple in the data graph.
A filter is a shape in a shapes graph that can be used to limit the in-scope nodes that are validated against the constraints of another shape. Only those nodes that validate against all the filters of a shape are validated against its constraints. A filter is specified with the sh:filterShape
predicate. When the filter is specified in a shape, the filter applies for all the shape constraints. When the filter is specified in a specific constraint, the filter applies for that specific constraint only.
The following example states that the sh:minCount
constraint on ex:email
is filtered to include only SHACL instances of ex:Person
that are ex:member
s of ex:W3c
.
ex:ExampleFilteredShape
a sh:Shape ;
sh:scopeClass ex:Person ;
sh:filterShape [
a sh:Shape ; # Optional triple
sh:property [
sh:predicate ex:member ;
sh:hasValue ex:W3c ;
]
] ;
sh:property [
sh:predicate ex:email ;
sh:minCount 1 ;
] .
ex:Alice a ex:Person ; ex:member ex:W3c ; ex:email <mailto:alice@example.org> . ex:John a ex:Person ; ex:member ex:W3c . ex:Bob a ex:Person ; ex:member ex:Acme .
[ a sh:ValidationResult ; sh:severity sh:Violation ; sh:focusNode ex:John ; sh:subject ex:John ; sh:predicate ex:email ; sh:message "sh:minCount for ex:email is '1'." ; sh:sourceConstraintComponent sh:MinCountConstraintComponent ; ] .
The following example shows a sh:filterShape
that is defined on a specific constraint, instead of the whole shape.
ex:FilteredExampleShape a sh:Shape ; sh:scopeClass ex:Person ; sh:property [ sh:predicate ex:email ; sh:minCount 1 ; sh:filterShape [ sh:property [ sh:predicate ex:member ; sh:hasValue ex:W3c ; ] ] ; ] .
Note that filter shapes are always validated prior to applying their associated shape or constraint. This includes scenarios such as sh:shape
where a shape is explicitly referenced by another constraint. However, during the validation of a shape referenced via sh:shape
, the declared scopes of these shapes are not used to limit the set of focus nodes.
A shape defines constraints and sh:Constraint
is the SHACL superclass of all constraint types. The SHACL core language defines the following three constraint types:
sh:PropertyConstraint
is the class of constraints that specify conditions that must be met with respect to triples with the focus node as a subject and a particular property as a predicate.
sh:InversePropertyConstraint
is the class of constraints that specify conditions that must be met with respect to triples with the focus node as an object and a particular property as a predicate.
sh:NodeConstraint
is the class of constraints that specify arbitrary conditions that must be met with respect to the focus node.
Additional types of constraints can be added using the extension mechanism, either SPARQL-based constraints or SPARQL-based constraint components.
Shapes link to their constraints via the following properties:
sh:property
links shapes to property constraints. The default value type of sh:property
is sh:PropertyConstraint
.
sh:inverseProperty
links shapes to inverse property constraints. The default value type of sh:inverseProperty
is sh:InversePropertyConstraint
.
sh:constraint
links shapes to node constraints. The default value type of sh:constraint
is sh:NodeConstraint
.
The values of sh:property
, sh:inverseProperty
, and sh:constraint
must be IRIs or blank nodes. The values of sh:property
and sh:inverseProperty
must be the
subject of precisely one triple with predicate sh:predicate
, and the object of this triple must be an IRI.
The WG is still working out whether and how a concept of default value types is specified and used in SHACL.
All three properties have a default value type and thus, the rdf:type
triple can be omitted.
Instances of constraint types can be reused across different shapes. However, all constraint types are pairwise disjoint and no more than one property of sh:property
, sh:inverseProperty
and sh:constraint
can link to the same RDF node within the same shapes graph.
Constraints may contain
non-validating properties (such as sh:description
) or
parameters of constraint components (e.g. sh:minCount
).
Constraint components define one or more parameter properties and validation instructions (such as those implemented as SPARQL queries) that can be used to perform the validation for the given focus node and parameter values. The relationship between a constraint component and the constraint types that it can be used with is called the context of the component. For example, the context of the component defining the sh:closed
property is sh:NodeConstraint
. This means that the property sh:closed
can only be used in SHACL instances of sh:NodeConstraint
. The catalog of constraint components in the Core of SHACL is defined in section 4.
The following examples illustrate two ways of using (property) constraints. The first example uses a blank node:
ex:InlinePropertyConstraintExampleShape a sh:Shape ; sh:property [ sh:predicate ex:someProperty ; sh:name "some property" ; sh:description "Description of the role of ex:someProperty (in the context of the constraint)" ; sh:minCount 1 ; sh:class ex:SomeClass ; ] .
The second example defines a constraint as an IRI node, allowing it to be more easily referenced and shared across multiple shapes:
ex:StandAlonePropertyConstraintExampleShape a sh:Shape ; sh:property ex:StandAlonePropertyConstraintExampleShape_someProperty . ex:StandAlonePropertyConstraintExampleShape_someProperty a sh:PropertyConstraint ; sh:predicate ex:someProperty ; sh:defaultValue ex:SomeInstance ; sh:minCount 1 ; sh:class ex:SomeClass .
Parameters of constraint components that only declare one parameter (such as sh:class
) may be used multiple times within the same constraint node. In the following example this technique is used to restrict the values of a property to be SHACL instances of both
ex:Customer
and ex:MalePerson
.
ex:ShapeWithTwoClasses a sh:Shape ; sh:property [ sh:predicate ex:someProperty ; sh:class ex:Customer ; sh:class ex:MalePerson ; ] .
A SHACL validation engine takes two immutable RDF graphs as input, a valid shapes graph and a data graph, and validates the data graph against the shapes graph as described herein.
sh:Violation
for the node.
The validation process returns a validation report containing all validation results. By default, the validation report contains validation results of all severity levels but the user can request validation results with a custom minimum severity. According to the definition of validation, a validation report may contain validation results but as long as none is of severity sh:Violation
the data graph is considered valid. For simpler validation scenarios, SHACL validation engines SHOULD provide an additional validation interface that returns only VALID or INVALID.
During validation, the data graph and the shapes graph must remain immutable, i.e. both graphs at the end of the validation must be identical to the graph at the beginning of validation.
A SHACL validation engine MUST implement all constructs in the core of SHACL (Sections 2, 3, 4). A SHACL engine MAY not implement the other parts of SHACL.
The shapes graph contains shape definitions that a data graph can be tested against. Shape definitions can be reusable validation components. Importing multiple shapes graphs can be achieved with the predicate owl:imports
. SHACL validation engines SHOULD transitively follow all values of owl:imports
to other graphs and use the resulting union graph as shapes graph to the validation process.
In addition to shape definitions, the shapes graph may contain additional information for the validation engine such as entailment directives.
The data graph contains the RDF data that a SHACL engine can validate. SHACL treats it as a general RDF graph and makes no assumption if it is e.g. an RDF dataset, an in-memory graph or a named graph in a remote SPARQL endpoint.
The data graph SHOULD include all the ontology axioms related to the data and especially all the rdfs:subClassOf
triples in order for SHACL to correctly identify class scopes and validate core SHACL constraints. If such triples are missing, the validation could report false violations or miss to report some violations.
A data graph can include triples used to suggest one or more shapes graphs to a SHACL validation engine with the predicate sh:shapesGraph
. Every value of this property is an IRI representing a shapes graph that should be used to validate the data graph. A SHACL validation engine MAY use such suggestions to determine which shapes graph to use for validating a data graph.
In the following example, a tool may use the union of ex:graph-shapes1
and ex:graph-shapes2
graphs (and their owl:imports
) as the shapes graph when validating the given graph.
[] sh:shapesGraph ex:graph-shapes1 ; sh:shapesGraph ex:graph-shapes2 .
The validation report is the result of the validation process and includes a set of zero or more validation results. Each validation result is assigned a severity that can be informative, non-critical (warning) or violation. A validation process is considered successful when the validation report contains only informative or non-critical results. In addition to severities, each validation results contains a set of required or optional values that are described in the SHACL Validation Results Vocabulary.
The validation results produced by a SHACL validation engine MUST be the product of validation of the data graph only. Some engines MAY also report errors in the shapes graph, but those errors MUST NOT be mixed with the data validation results using the same results vocabulary.
SHACL includes an RDF vocabulary to represent validation results together with structural information that may provide guidance on how to identify or fix a violation.
The following graph represents a example validation result:
ex:ExampleConstraintViolation a sh:ValidationResult ; sh:severity sh:Violation ; sh:focusNode ex:Bob ; sh:subject ex:Bob ; sh:predicate ex:age ; sh:object "twenty two" ; sh:message "ex:age expects a literal of datatype xsd:integer." ; sh:sourceConstraintComponent sh:DatatypeConstraintComponent .
Validation results must be SHACL instances of the class sh:ValidationResult
. Its SHACL superclass, sh:AbstractResult
, defines the properties described in the following sub-sections. SHACL implementations may produce SHACL instances of other SHACL subclasses of sh:AbstractResult
, for example to report successfully completed constraint checks or accumulated results.
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.
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.
Validation results may link to 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 may link to the constraint component that caused the result via sh:sourceConstraintComponent
.
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 violations of nested constraints that have been evaluated via sh:shape
.
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.
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. |
Constraints can specify their severity level using the property sh:severity
, which must link to one of the severities. sh:Violation
is the default if unspecified. Constraints based on constraint components use the sh:severity
declared at the component IRI unless overridden at the constraint. The following example clarifies this.
ex:MyShape a sh:Shape ; sh:property [ # Violations of either minCount and datatype are produced as warnings sh:predicate ex:myProperty ; sh:minCount 1 ; sh:datatype xsd:string ; sh:severity sh:Warning ; ] ; sh:property [ # The default severity for sh:maxCount is sh:Violation sh:predicate ex:myProperty ; sh:maxCount 1 ; ] .
The following sections define the constraint components built into the SHACL Core. Compliant SHACL validation engines MUST support all of these constraint components.
The choice of constraint components that are defined by the SHACL Core was made based on the requirements collected by the [shacl-ucr] document. Special attention was paid to the balance between trying to cover as many common use cases as possible and keeping the size of the core language manageable. Not all use cases (such as describing constraints on members of an rdf:List
) can be expressed by the Core Vocabulary alone. Instead, SHACL provides extension mechanisms as described in the second part of this specification. It is expected that reusable libraries of SHACL extensions will be maintained by third parties.
Note that the textual definitions of the constraint components refer to the Validation Results Vocabulary. Each constraint component is identified by an IRI that is referenced in the validation results via sh:sourceConstraintComponent
. Many constraint components can be used in multiple contexts, e.g. both in a property constraint context and an inverse property constraint context.
The textual description of each component refers to the concept of value nodes which is defined as follows, including rules for the creation of validation results:
sh:subject
, the sh:predicate
as its sh:predicate
and the respective violating value node as its sh:object
.
sh:object
, the sh:predicate
as its sh:predicate
and the respective violating value node as its sh:subject
.
The SPARQL definitions in this section may only be written for one of the three possible contexts, for brevity. Corresponding queries can be formulated for the other cases (such as the inverse direction) easily. The SPARQL definitions also assume the variable bindings and result variable mapping rules detailed in the
section on SPARQL-based Constraints. In a nutshell, the variable $this
represents the currently validated focus node. In sh:PropertyConstraint
s and sh:InversePropertyConstraint
s, the value of the variable $predicate
is the value of sh:predicate
in the constraint.
Note that the parameter tables in each of the following sections have a column called Value Type which indicates the expected type of the parameter values for documentation purposes, without enforcing any formal restrictions.
The SPARQL definitions in this section also assume the existence of a built-in SPARQL function sh:hasShape
.
The following table summarizes the parameters used by the core constraint components. The table clarifies whether these parameters can be used as part of a
sh:NodeConstraint
(NC, to apply to the focus node itself), a sh:PropertyConstraint
(PC, to apply to all values of a given property), or a sh:InversePropertyConstraint
(IPC, to apply to all inverse values of a given property).
Parameters | NC | PC | IPC | Summary |
---|---|---|---|---|
sh:class and
sh:classIn
|
☑ | ☑ | ☑ | Type, based on rdf:type |
sh:closed
|
☑ | Only allow the declared properties | ||
sh:datatype and
sh:datatypeIn
|
☑ | ☑ | Datatype, for literals | |
sh:disjoint |
☑ | Property without overlapping values | ||
sh:equals |
☑ | Property with equal values | ||
sh:hasValue |
☑ | ☑ | A specific required value | |
sh:in |
☑ | ☑ | ☑ | Enumeration of allowed values |
sh:lessThan |
☑ | Must have lesser values than another property | ||
sh:lessThanOrEquals |
☑ | Must have lesser or equal values than another property | ||
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) |
sh:not ,
sh:and and
sh:or
|
☑ | ☑ | ☑ | Logical operators on shapes |
sh:pattern |
☑ | ☑ | ☑ | Regular expression string matching |
sh:stem |
☑ | ☑ | ☑ | IRIs must start with the given string |
sh:uniqueLang |
☑ | No duplicate language tags | ||
sh:shape |
☑ | ☑ | ☑ | Nested shape of all values |
sh:qualifiedValueShape , sh:qualifiedMinCount , sh:qualifiedMaxCount |
☑ | ☑ | Nested shape of a given minimum/maximum number of values |
The constraint components in this section have in common that they define restrictions on the type of the nodes.
It is an open issue how to best represent properties that may either take a literal or a non-literal.
The property sh:class
can be used to verify that each value node is a SHACL instance of a given type.
Constraint Component: sh:ClassConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:class |
rdfs:Resource |
Type of all values |
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER NOT EXISTS { ?value rdf:type/rdfs:subClassOf* $class } . }
ex:ClassExampleShape a sh:Shape ; sh:scopeNode ex:Bob, ex:Alice, ex:Carol ; sh:property [ sh:predicate ex:knows ; sh:class ex:Person ; ] .
ex:Alice a ex:Person .
ex:Bob ex:knows ex:Alice .
ex:Carol ex:knows ex:Bob .
The property sh:classIn
can be used to verify that each value node is a SHACL instance of a type from a given list. The values of sh:classIn
must be lists of resources.
sh:classIn
is a generalization of sh:class
allowing users to state that the values must have at least one out of several types.
Constraint Component: sh:ClassInConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:classIn |
rdf:List (members: rdfs:Resource ) |
List of types of all values |
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER NOT EXISTS { GRAPH $shapesGraph { $classIn (rdf:rest*)/rdf:first ?class . } FILTER NOT EXISTS { ?value rdf:type/rdfs:subClassOf* ?class } } }
ex:ClassInExampleShape a sh:Shape ; sh:scopeNode ex:Bob, ex:Alice, ex:Carol ; sh:property [ sh:predicate ex:affiliatedWith ; sh:classIn ( ex:University ex:Organisation ) ; ] .
ex:MIT a ex:University .
ex:W3c a ex:Organisation .
ex:Bob ex:affiliatedWith ex:MIT .
ex:Alice ex:affiliatedWith ex:W3c .
ex:Carol ex:affiliatedWith ex:ABC .
The property sh:datatype
can be used to restrict the datatype of all value nodes. The values of sh:datatype
must be resources representing datatypes, such as xsd:string
.
Constraint Component: sh:DatatypeConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:datatype |
rdfs:Resource |
Datatype of all value nodes (e.g., xsd:integer ) |
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER (!isLiteral(?value) || datatype(?value) != $datatype) . }
ex:DatatypeExampleShape a sh:Shape ; sh:scopeNode ex:Alice, ex:Bob ; sh:property [ sh:predicate ex:age ; sh:datatype xsd:integer ; ] .
ex:Alice ex:age "23"^^xsd:integer .
ex:Bob ex:age "twenty two" .
The property sh:datatypeIn
can be used to restrict the datatype of all value nodes. The values of sh:datatypeIn
must be lists of resources representing datatypes, such as xsd:string
.
sh:datatypeIn
is a generalization of sh:datatype
allowing users to state that the values must have one out of several datatypes.
Constraint Component: sh:DatatypeInConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:datatype |
rdf:List (members: rdfs:Resource ) |
Allowed datatypes of all value nodes (e.g., xsd:integer ) |
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER (!isLiteral(?value) || NOT EXISTS { GRAPH $shapesGraph { $datatypeIn (rdf:rest*)/rdf:first ?datatype . } BIND (datatype(?value) AS ?valueDatatype) . FILTER (?valueDatatype = $datatype) . }) } }
ex:DatatypeInExampleShape a sh:Shape ; sh:scopeNode ex:Bob, ex:Alice, ex:Ted ; sh:property [ sh:predicate ex:name ; sh:datatypeIn ( xsd:string rdf:langString ) ; ] .
ex:Bob ex:name "Bob"@en .
ex:Alice ex:name "Alice" .
ex:Ted ex:name 23 .
The property sh:nodeKind
is used to restrict the RDF node kind of each value node.
Constraint Component: sh:NodeKindConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:nodeKind |
sh:NodeKind |
Node kind (IRI, blank node, literal or combinations of these) of all value nodes |
The values of sh:nodeKind
must be SHACL instances of the class sh:NodeKind
. The SHACL system vocabulary defines that sh:NodeKind
has exactly six instances:
sh:BlankNode
, sh:IRI
and sh:Literal
as well as the following values that represent combinations of the former three, i.e. either-or:
sh:BlankNodeOrIRI
, sh:BlankNodeOrLiteral
and sh:IRIOrLiteral
.
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER NOT EXISTS { FILTER ((isIRI(?value) && $nodeKind IN ( sh:IRI, sh:BlankNodeOrIRI, sh:IRIOrLiteral ) ) || (isLiteral(?value) && $nodeKind IN ( sh:Literal, sh:BlankNodeOrLiteral, sh:IRIOrLiteral ) ) || (isBlank(?value) && $nodeKind IN ( sh:BlankNode, sh:BlankNodeOrIRI, sh:BlankNodeOrLiteral ) )) . } }
ex:NodeKindExampleShape a sh:Shape ; sh:scopeNode ex:Bob, ex:Alice ; sh:property [ sh:predicate ex:knows ; sh:nodeKind ex:IRI ; ] .
ex:Bob ex:knows ex:Alice .
ex:Alice ex:knows "Bob" .
The constraint components in this section can be applied to either a property constraint or an inverse property constraint, to represent restrictions on the number of values that the focus node may have for these properties.
The property sh:minCount
restricts the number of triples involving the focus node and a given predicate.
Constraint Component: sh:MinCountConstraintComponent
Supported Contexts: sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:minCount |
xsd:integer |
The minimum cardinality. If the value is 0 then this constraint is always satisfied and so may be omitted. |
sh:minCount
.
SELECT $this ($this AS ?subject) $predicate WHERE { { SELECT (COUNT(?value) AS ?count) WHERE { $this $predicate ?value . } } FILTER (?count < $minCount) }
ex:MinCountExampleShape a sh:Shape ; sh:scopeNode ex:Alice, ex:Bob ; sh:property [ sh:predicate ex:name ; sh:minCount 1 ; ] .
ex:Alice ex:name "Alice" .
ex:Bob ex:givenName "Bob"@en .
The property sh:maxCount
restricts the number of triples involving the focus node and a given predicate.
Constraint Component: sh:MaxCountConstraintComponent
Supported Contexts: sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:maxCount |
xsd:integer |
The maximum cardinality. If this parameter is omitted then there is no limit on the number of triples. |
sh:maxCount
.
SELECT $this ($this AS ?subject) $predicate WHERE { { SELECT (COUNT(?value) AS ?count) WHERE { $this $predicate ?value . } } FILTER (?count > $maxCount)) }
ex:MaxCountExampleShape a sh:Shape ; sh:scopeNode ex:Bob ; sh:property [ sh:predicate ex:birthDate ; sh:maxCount 1 ; ] .
ex:Bob ex:birthDate "May 5th 1990" .
The following constraint components represent range restrictions on nodes that are comparable via operators such as <
and >
.
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
.
Constraint Components: sh:MinExclusiveConstraintComponent
, sh:MinInclusiveConstraintComponent
, sh:MaxExclusiveConstraintComponent
, sh:MaxInclusiveConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
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 | >= |
<
, <=
, >
and >=
. A validation result must also be produced if the node cannot be compared to the specified range.
Note that if the comparison cannot be performed, for example when someone compares a string with an integer, then the validation 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 and the $minExclusive
variable.
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . BIND (?value > $minExclusive AS ?result) . FILTER (!?result || !bound(?result)) . }
ex:NumericRangeExampleShape a sh:Shape ; sh:scopeNode ex:Bob, ex:Alice, ex:Ted ; sh:property [ sh:predicate ex:age ; sh:minInclusive 0 ; sh:maxInclusive 150 ; ] .
ex:Bob ex:age 23 . ex:Alice ex:age 220 . ex:Ted ex:age "twenty one" .
The constraint components in this section have in common that they are representing restrictions on the string representation of certain nodes.
The property sh:minLength
restricts the string length of value nodes. This can be applied to any literals and IRIs, but not to blank nodes.
Constraint Component: sh:MinLengthConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:minLength |
xsd:integer |
The minimum length. If the value is 0 then there is no restriction on the string length but this constraint is still violated if the node is a blank node. |
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER (isBlank(?value) || STRLEN(str(?value)) < $minLength) . }
The property sh:maxLength
restrict the string length of value nodes This can be applied to any literals and IRIs, but not to blank nodes.
Constraint Component: sh:MaxLengthConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:maxLength |
xsd:integer |
The maximum length. If this constraint is omitted then there is no restriction on the string length and no requirement that the node is a literal or IRI. |
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER (isBlank(?value) || STRLEN(str(?value)) > $maxLength) . }
ex:PasswordExampleShape a sh:Shape ; sh:scopeNode ex:Bob, ex:Alice ; sh:property [ sh:predicate ex:password ; sh:minLength 8 ; sh:maxLength 10 ; ] .
ex:Bob ex:password "123456789" .
ex:Alice ex:password "1234567890ABC" .
The property sh:pattern
can be used to validate whether all value nodes match a given regular expression. The values of sh:pattern
must be valid pattern arguments for the SPARQL REGEX function.
Constraint Component: sh:PatternConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:pattern |
xsd:string |
Regular expression that all value nodes must match |
sh:flags |
xsd:string (optional) |
An optional string of flags, interpreted as in SPARQL 1.1 REGEX |
sh:flags
is present then this must be interpreted according to the SPARQL REGEX function.
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER (isBlank(?value) || IF(bound($flags), !regex(str(?value), $pattern, $flags), !regex(str(?value), $pattern))) . }
ex:PatternExampleShape a sh:Shape ; sh:scopeNode ex:Bob, ex:Alice, ex:Carol ; sh:property [ sh:predicate ex:bCode ; sh:pattern "^B" ; # starts with 'B' sh:flags "i" ; # Ignore case ] .
ex:Bob ex:bCode "b101" .
ex:Alice ex:bCode "B102" .
ex:Carol ex:bCode "C103" .
The property sh:stem
validates whether all value nodes are IRIs and the IRI starts with a given string value.
Constraint Component: sh:StemConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:stem |
xsd:string |
String value that an IRI must start with |
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER (!isIRI(?value) || !STRSTARTS(str(?value), $stem) ) . }
ex:StemExampleShape a sh:Shape ; sh:scopeNode ex:Bob, ex:Alice, ex:Carol ; sh:property [ sh:predicate ex:w3cHomepage ; sh:stem "https://www.w3.org/People/" ; ] .
ex:Alice ex:w3cHomepage <https://www.w3.org/People/Alice> . ex:Bob ex:w3cHomepage <https://example.com/People/Bob> . ex:Carol ex:w3cHomepage "https://www.w3.org/People/Carol" .
The property sh:uniqueLang
can be set to true
to specify that no pair of value nodes may use the same language tag. The values of sh:uniqueLang
must be xsd:boolean
s.
Constraint Component: sh:UniqueLangConstraintComponent
Supported Contexts: sh:PropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:uniqueLang |
xsd:boolean |
true to activate this constraint |
sh:uniqueLang
is set to true
then a validation result must be produced for each non-empty language tag that is used by at least two value nodes.
SELECT DISTINCT $this ($this AS ?subject) $predicate ?lang WHERE { { FILTER ($uniqueLang) . } $this $predicate ?value . BIND (lang(?value) AS ?lang) . FILTER (bound(?lang) && ?lang != "") . FILTER EXISTS { $this $predicate ?otherValue . FILTER (?otherValue != ?value && ?lang = lang(?otherValue)) . } }
ex:UniqueLangExampleShape a sh:Shape ; sh:scopeNode ex:Alice, ex:Bob ; sh:property [ sh:predicate ex:label ; sh:uniqueLang true ; ] .
ex:Alice
ex:label "Alice" ;
ex:label "Alice"@en ;
ex:label "Alice"@fr .
ex:Bob
ex:label "Bob"@en ;
ex:label "Bobby"@en .
The constraint components in this section restrict the sets of values represented by the sh:predicate
used in the property constraint, and another property that is specified as the value of the respective parameter such as sh:equals
.
sh:equals
constrains a pair of properties so that the sets of values of both properties at a given focus node must be equal.
Constraint Component: sh:EqualsConstraintComponent
Supported Contexts: sh:PropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:equals |
rdfs:Resource |
Property to compare with |
sh:predicate
that does not exist as value of sh:equals
and for each value of sh:equals
that does not exist as value of sh:predicate
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
.
SELECT $this ($this AS ?subject) $predicate ?object WHERE { { $this $predicate ?object . FILTER NOT EXISTS { $this $equals ?object . } } UNION { $this $equals ?object . FILTER NOT EXISTS { $this $predicate ?object . } } }
The following example illustrates the use of sh:equals
in a shape to verify that certain nodes must have the same set of values for ex:firstName
and ex:givenName
.
ex:EqualExampleShape a sh:Shape ; sh:scopeNode ex:Bob ; sh:property [ sh:predicate ex:firstName ; sh:equals ex:givenName ; ] .
ex:Bob ex:firstName "Bob" ; ex:givenName "Bob" .
sh:disjoint
constrains a pair of properties so that the sets of values of both properties at a given focus node must not share any nodes.
Constraint Component: sh:DisjointConstraintComponent
Supported Contexts: sh:PropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:disjoint |
rdfs:Resource |
The property to compare the values with |
sh:predicate
that also exists as value of sh:disjoint
at the given focus node. The produced validation result must have the focus node as its sh:subject
, the sh:predicate
as its sh:predicate
and the value as its sh:object
.
SELECT $this ($this AS ?subject) $predicate ?object WHERE { $this $predicate ?object . $this $disjoint ?object . }
The following example illustrates the use of sh:disjoint
in a shape to verify that certain nodes must not share any values for ex:prefLabel
and ex:altLabel
.
ex:DisjointExampleShape a sh:Shape ; sh:scopeNode ex:USA, ex:Germany ; sh:property [ sh:predicate ex:prefLabel ; sh:disjoint ex:altLabel ; ] .
ex:USA
ex:prefLabel "USA" ;
ex:altLabel "United States" .
ex:Germany
ex:prefLabel "Germany" ;
ex:altLabel "Germany" .
sh:lessThan
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.
Constraint Component: sh:LessThanConstraintComponent
Supported Contexts: sh:PropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:lessThan |
rdfs:Resource |
The property to compare the values with |
sh:predicate
and sh:lessThan
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:predicate
as its sh:predicate
and the value of the property specified by sh:predicate
as its sh:object
.
SELECT $this ($this AS ?subject) $predicate ?object WHERE { $this $predicate ?object . $this $lessThan ?object2 . FILTER (!(?object < ?object2)) . }
TODO: Decide what should happen if values are not comparable, i.e. < fails, similar to minExclusive etc.
The following example illustrates the use of sh:lessThan
in a shape to verify that all values of ex:startDate
must be "before" the values of ex:endDate
.
ex:LessThanExampleShape a sh:Shape ; sh:property [ sh:predicate ex:startDate ; sh:lessThan ex:endDate ; ] .
sh:lessThanOrEquals
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.
Constraint Component: sh:LessThanOrEqualsConstraintComponent
Supported Contexts: sh:PropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:lessThanOrEquals |
rdfs:Resource |
The property to compare the values with |
sh:predicate
and sh:lessThanOrEquals
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:predicate
as its sh:predicate
and the value of the property specified by sh:predicate
as its sh:object
.
SELECT $this ($this AS ?subject) $predicate ?object WHERE { $this $predicate ?object . $this $lessThanOrEquals ?object2 . FILTER (!(?object <= ?object2)) . }
The constraint components in this section implement the common logical operators and, or and not.
There is a proposal to generalize the following components to also allow their values to be constraints, not just shapes.
SHACL supports a high-level negation constraint that can be used to verify that a value node does not have a given shape. This is comparable to a logical "not" operator.
Constraint Component: sh:NotConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:not |
sh:Shape |
The shape to negate |
sh:Violation
for the shape given via sh:not
. A failure must be reported if the validation of the shape produces a failure.
SELECT $this ?failure WHERE { BIND (sh:hasShape($this, $not, $shapesGraph) AS ?hasShape) . BIND (!bound(?hasShape) AS ?failure) . FILTER (?failure || ?hasShape) . }
The following example illustrates the use of sh:not
in a shape to verify that certain nodes cannot have any value of ex:property
.
ex:NotExampleShape a sh:Shape ; sh:scopeNode ex:InvalidInstance1 ; sh:constraint [ sh:not [ a sh:Shape ; sh:property [ sh:predicate ex:property ; sh:minCount 1 ; ] ; ] ] .
ex:InvalidInstance1 ex:property "Some value" .
SHACL supports a high-level syntax for conjunctive constraints that can be used to test whether a value node has all out of several shapes. This is comparable to a logical "and" operator.
Constraint Component: sh:AndConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:and |
rdf:List (members: sh:Shape ) |
List of shapes to validate the value nodes against |
sh:and
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 produces a failure.
SELECT $this ?failure WHERE { { SELECT (SUM(?s) AS ?count) WHERE { GRAPH $shapesGraph { $and rdf:rest*/rdf:first ?shape . } BIND (sh:hasShape($this, ?shape, $shapesGraph) AS ?hasShape) . BIND (IF(bound(?hasShape), IF(!?hasShape, 1, 0), 'error') AS ?s) . } } BIND (!bound(?count) AS ?failure) . FILTER IF(?failure, true, ?count > 0) . }
Note that although sh:and
has an rdf:List
of shapes as its value, the order of those shapes does not impact the validation results.
The following example illustrates the use of sh:and
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:and
can be used to implement a specialization mechanism between shapes.
ex:SuperShape a sh:Shape ; sh:property [ sh:predicate ex:property ; sh:minCount 1 ; ] . ex:ExampleAndShape a sh:Shape ; sh:scopeNode ex:ValidInstance, InvalidInstance ; sh:constraint [ sh:and ( ex:SuperShape [ a sh:Shape ; sh:property [ sh:predicate ex:property ; sh:maxCount 1 ; ] ] ) ] .
ex:ValidInstance
ex:property "One" .
# Invalid: more than one property
ex:InvalidInstance
ex:property "One" ;
ex:property "Two" .
SHACL supports a high-level syntax for disjunctive constraints that can be used to test whether a value node has at least one out of several shapes. This is comparable to a logical "or" operator.
Constraint Component: sh:OrConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:or |
rdf:List (members: sh:Shape ) |
List of shapes to validate the value nodes against |
sh:or
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 produces a failure.
SELECT $this ?failure WHERE { { SELECT (SUM(?s) AS ?count) WHERE { GRAPH $shapesGraph { $or rdf:rest*/rdf:first ?shape . } BIND (sh:hasShape($this, ?shape, $shapesGraph) AS ?hasShape) . BIND (IF(bound(?hasShape), IF(?hasShape, 1, 0), 'error') AS ?s) . } } BIND (!bound(?count) AS ?failure) . FILTER IF(?failure, true, ?count = 0) . }
Note that although sh:or
has an rdf:List
of shapes as its value, the order of those shapes does not impact the validation results.
The following example illustrates the use of sh:or
in a shape to verify that certain nodes have at least one value of ex:firstName
or at least one value of ex:givenName
.
ex:OrConstraintExampleShape a sh:Shape ; sh:scopeNode ex:Bob ; sh:constraint [ sh:or ( [ sh:property [ sh:predicate ex:firstName ; sh:minCount 1 ; ] ] [ sh:property [ sh:predicate ex:givenName ; sh:minCount 1 ; ] ] ) ] .
ex:Bob ex:firstName "Robert" .
The constraint components in this section can be used to represent complex restrictions based on applying shape definitions on the property values.
The property sh:shape
can be used verify that all value nodes must have a given shape. The value type of sh:shape
is sh:Shape
, but the rdf:type
triple of those shapes can be omitted.
Constraint Component: sh:ShapeConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:shape |
sh:Shape |
The required shape of all value nodes |
sh:shape
produces any validation results with severity sh:Violation
. A failure must be produced if the validation of any value node has produced a failure.
SELECT $this ($this AS ?subject) $predicate ?object ?failure WHERE { $this $predicate ?object . BIND (sh:hasShape(?object, $shape, $shapesGraph) AS ?hasShape) . BIND (!bound(?hasShape) AS ?failure) . FILTER (?failure || !?hasShape) . }
According to resolution 2015.12.16/04 shapes graphs with dependency loops are invalid and suitable limitations of this will be explored. Until issue 22 is closed, definitions regarding recursion are not endorsed by the WG.
A shape may refer to itself directly or indirectly via sh:shape
, sh:filterShape
, etc. Such a shape is said to be recursive. The meaning of non-recursive shapes is always well-founded. In contrast, the meaning of a recursive shape may not be well-founded. As a starting point, the SHACL specification only defines the meaning of non-recursive shapes. However, there are use-cases where recursion is valuable, either for its inherent expressive power or because it makes the intension of shapes clearer. The Working Group will therefore explore conditions under which recursive shapes can be assigned a well-defined meaning and will relax the restrictions on recursion accordingly.
In the following example, all values of the property ex:someProperty
will validate with no results for the shape specified by a blank node that ensures that the property ex:nestedProperty
has at least one value.
ex:ShapeExampleShape a sh:Shape ; sh:property [ sh:predicate ex:someProperty ; sh:shape [ a sh:Shape ; # Optional sh:predicate [ sh:predicate ex:nestedProperty ; sh:minCount 1 ; ] ] ] .
ex:ShapeExampleValidResource ex:someProperty [ ex:nestedProperty 42 ; ] .
The property sh:qualifiedValueShape
can be used verify that a certain number of value nodes 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.
Constraint Component: sh:QualifiedValueShapeConstraintComponent
Supported Contexts: sh:PropertyConstraint
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. If this constraint is omitted then there is no minimum number of values required. |
sh:qualifiedMaxCount |
xsd:integer |
The maximum number of values that can have the shape. If this constraint is omitted then there is no maximum number of values required. |
C
be the number of value nodes where validating the node against the shape specified by sh:qualifiedValueShape
produces no validation results with severity sh:Violation
. A failure must be produced if the validation of any of the value nodes produces a failure. A validation result must be produced if C
is less than the specified sh:qualifiedMinCount
.
SELECT $this ($this AS ?subject) $predicate ?failure WHERE { { SELECT (SUM(?s) AS ?count) WHERE { { FILTER NOT EXISTS { $this $predicate ?value } . BIND (0 AS ?s) . } UNION { $this $predicate ?value . BIND (sh:hasShape(?value, $qualifiedValueShape, $shapesGraph) AS ?hasShape) . BIND (IF(bound(?hasShape), IF(?hasShape, 1, 0), 'error') AS ?s) . } } } BIND (!bound(?count) AS ?failure) . FILTER IF(?failure, true, ?count < $qualifiedMinCount) . }
Note that in the SPARQL query above, we assume that the SUM
operation fails if one of the values of ?s
is not a number. This mechanism is used by the error handling, which sets ?s
to the string 'error'
whenever one of the individual sh:hasShape
calls fails.
C
be the number of value nodes where validating the node against the shape specified by sh:qualifiedValueShape
produces no validation results with severity sh:Violation
. A failure must be produced if the validation of any of the value nodes produces a failure. A validation result must be produced if C
is greater than the specified sh:qualifiedMaxCount
.
SELECT $this ($this AS ?subject) $predicate ?failure WHERE { { SELECT (SUM(?s) AS ?count) WHERE { { FILTER NOT EXISTS { $this $predicate ?value } . BIND (0 AS ?s) . } UNION { $this $predicate ?value . BIND (sh:hasShape(?value, $qualifiedValueShape, $shapesGraph) AS ?hasShape) . BIND (IF(bound(?hasShape), IF(?hasShape, 1, 0), 'error') AS ?s) . } } } BIND (!bound(?count) AS ?failure) . FILTER IF(?failure, true, ?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.
ex:QualifiedValueShapeExampleShape a sh:Shape ; sh:scopeNode ex:QualifiedValueShapeExampleValidResource ; 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 .
In some cases a given property may be multi-valued and it may be required that the set of values be partitioned into two or more subsets, each of which satisfies certain constraints.
For example, suppose that in the Library of Congress BIBFRAME (bf:
) Cultural Heritage vocabulary each person (bf:Person
) must be identified by (bf:identifiedBy
) exactly one identifier from id.loc.gov
and may have another identifier from viaf.org
. No other identifiers are allowed. Thus the set of all identifiers is partitioned into two subsets, the first of which contains exactly one member and the second of which contains zero or one members. The following example shows a snippet of some valid BIBFRAME data.
<bf_Person1> bf:identifiedBy <http://id.loc.gov/authorities/names/n80103961#RWO> ; bf:identifiedBy <https://viaf.org/viaf/268367832/#Knape,_Joachim> .
The following example shows a snippet of some invalid BIBFRAME data.
<bf_Person1> bf:identifiedBy <http://id.loc.gov/authorities/names/n80103961#RWO> ; bf:identifiedBy <https://viaf.org/viaf/268367832/#Knape,_Joachim> ; bf:identifiedBy "this is a mistake" . # should be an error
Qualified cardinality constraints provide a basis for expressing this type of partitioning requirement, but using them imposes a burden on the shapes author. In the BIBFRAME example the author would need to express the requirement that the set of all identifiers that are from neither id.loc.gov
nor viaf.org
is empty, i.e. it has a maximum cardinality of 0. Clearly, as more subsets of values are involved, the burden on the author increases. The sh:partition
constraint makes it easier to express this type of requirement than it would be to use multiple qualified cardinality constraints. In effect, sh:partition
chains together a sequence of qualified cardinality constraints and removes the set of context nodes matched by each from further consideration. If every context node gets matched in this process, then the sh:partition
constraint reports no violations. Otherwise, any context nodes remaining are reported as violations of the constraint. The BIBFRAME example constraint is expressed as follows.
ex:BibframeShape a sh:Shape ; sh:property [ sh:predicate bf:identifiedBy ; sh:partition ( [sh:minCount 1; sh:maxCount 1; sh:pattern "^http://id.loc.gov/"] [sh:maxCount 1; sh:pattern "^https://viaf.org/"] ) ] .
The value of the sh:partition
constraint parameter MUST be an rdf:List
that contains zero or more resources. Each resource in the list defines conditions on a subset of the context nodes and MAY contain the following parameters:
sh:minCount
. This defines the minimum cardinality of the corresponding subset.sh:maxCount
. This defines the maximum cardinality of the corresponding subset.sh:nodeKind
, sh:partition
,
sh:minExclusive
, etc. The corresponding subset consists of those remaining nodes for which the boolean function is true
.
Note that a resource that contains no parameters matches all nodes. Such a resource is useful as the last member of the list where it acts as a default matching rule in the case where nodes that do not match any of the preceeding constraints are allowed. Note also that a qualified cardinality constraint defined using sh:qualifiedValueShape
,
sh:qualifiedMinCount
, and sh:qualifiedMaxCount
is equivalent to a sh:partition
constraint that contains two resources with the first one containing the corresponding parameters and the last one being the default matching rule that matches any set of nodes.
Each member of the list is used by the SHACL processor to match a subset of the context nodes. The SHACL processor matches as many nodes as possible and then compares the result with the specified minimum and maximum cardinalities if specified. This is referred to as a greedy matching algorithm. Greedy pattern matching is commonly used with textual regular expressions. Nodes that match are removed from further matching. Thus the set of all context nodes becomes partitioned by the matching algorithm. The following paragraphs define this algorithm more precisely.
Let D be a data graph and let F be a focus node in D. Let S be a shapes graph, let T be a shape in S, and let C be a sh:partition
constraint in T. Let N be the set of context nodes for C in D at F. Recall that N depends on how C is related to T.
sh:constraint
, C) is in S then N consists of just the node F.sh:property
, C) and (C, sh:predicate
, P) are in S then N consists of all the nodes X such that (F, P, X) is in D.sh:inverseProperty
, C) and (C, sh:predicate
, P) are in S then N consists of all the nodes X such that (X, P, F) is in D.
Let the value of the sh:partition
parameter be the list (Q1, ..., Qn) of resources. The SHACL validator MUST perform the following steps to validate the constraint C at F.
Note that the order of resources within the list is significant. In general, if the members of the list are reordered then different context node sets will be matched and different violation results will be reported.
This section enumerates core constraint components that did not fit into the other categories.
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 property called sh:closed
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
.
Constraint Component: sh:ClosedConstraintComponent
Supported Contexts: sh:NodeConstraint
Property | Value Type | Summary |
---|---|---|
sh:closed |
xsd:boolean |
Set to true to close the shape |
sh:ignoredProperties |
rdf:List (members: rdf:Property ) |
Optional list of properties that are also permitted in addition to those explicitly enumerated via sh:property |
sh:closed
is true
then 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
in any of the sh:property
constraints at the surrounding shape. If the parameter 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:NodeConstraint
called sh:Closed
that can be used in places where no other parameters such as sh:ignoredProperties
are needed.
SELECT $this ($this AS ?subject) ?predicate ?object WHERE { { FILTER $closed . } $this ?predicate ?object . FILTER (NOT EXISTS { GRAPH $shapesGraph { $currentShape sh:property/sh:predicate ?predicate . } } && (!bound($ignoredProperties) || NOT EXISTS { GRAPH $shapesGraph { $ignoredProperties rdf:rest*/rdf:first ?predicate . } })) }
The following example illustrates the use of sh:closed
in a shape to verify that certain nodes only have values for ex:exampleProperty1
and ex:exampleProperty2
. The "ignored" property rdf:type
would also be allowed.
ex:ClosedShapeExampleShape a sh:Shape ; sh:scopeNode ex:Alice, ex:Bob ; sh:constraint [ sh:closed true ; sh:ignoredProperties (rdf:type) ; ] ; sh:property [ sh:predicate ex:firstName ; ] ; sh:property [ sh:predicate ex:lastName ; ] .
ex:Alice
ex:firstName "Alice" .
ex:Bob
ex:firstName "Bob" ;
ex:middleInitial "J" .
The next example illustrates a more compact syntax using the built-in instance sh:Closed
. In this form, no ignored properties can be specified.
ex:ClosedShapeExampleShape a sh:Shape ; sh:constraint sh:Closed ; sh:property [ sh:predicate ex:firstName ; ] ; sh:property [ sh:predicate ex:lastName ; ] .
The property sh:hasValue
can be used to verify that one of the value nodes is a given RDF node.
Constraint Component: sh:HasValueConstraintComponent
Supported Contexts: sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:hasValue |
any | A specific required value |
sh:hasValue
is not among the value nodes.
SELECT $this ($this AS ?subject) $predicate WHERE { FILTER NOT EXISTS { $this $predicate $hasValue . } }
ex:StanfordGraduate a sh:Shape ; sh:scopeNode ex:Alice ; sh:property [ sh:predicate ex:alumniOf ; sh:hasValue ex:Stanford ; ] .
ex:Alice ex:alumniOf ex:Harvard ; ex:alumniOf ex:Stanford .
The property sh:in
exclusively enumerates the permitted value nodes. For example when specified as part of a property constraint, then each value of the given property must be a member of the specified list.
Constraint Component: sh:InConstraintComponent
Supported Contexts: sh:NodeConstraint
, sh:PropertyConstraint
, sh:InversePropertyConstraint
Property | Value Type | Summary |
---|---|---|
sh:in |
rdf:List |
Enumeration of allowed values |
sh:in
must be well-formed rdf:List
s. The members of that rdf:List
must not be blank nodes. A validation result must be produced for every value node 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
.
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER NOT EXISTS { GRAPH $shapesGraph { $in (rdf:rest*)/rdf:first ?value . } } }
ex:InExampleShape a sh:Shape ; sh:scopeNode ex:RainbowPony ; sh:property [ sh:predicate ex:color ; sh:in ( ex:Pink ex:Purple ) ; ] .
ex:RainbowPony ex:color ex:Pink .
While the previous sections introduced properties that represent validation conditions, this section covers properties that are ignored by SHACL validation engines. The use of these properties is entirely optional and not subject to formal interpretation contracts. They may be used for purposes such as form building or predictable printing of RDF files.
Property constraints may have one or more values for sh:name
to provide human-readable labels 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 sh:name
, then the tool SHOULD use the provided name. Similarly, property constraints may have an sh:description
to provide a description of the property in the given context. Both sh:name
and sh:description
may have multiple values, but SHOULD only have one value per language tag.
Property constraints may have one value for the property sh:order
to indicate the relative order of the property constraint for purposes such as form building. The values of sh:order
must be decimals.
sh:order
is not used for validation purposes. If present, the recommended use of sh:order
is to sort the property constraints in an ascending order, for example so that properties with smaller order are placed above (or to the left) of properties with larger order.
Property constraints may link to an SHACL instance of the class sh:PropertyGroup
using the property sh:group
to indicate that the constraint belongs to a group of related property constraints. Each group may have additional triples that serve application purposes, such as an rdfs:label
for form building. Groups may also have an sh:order
property to indicate the relative ordering of groups within the same form.
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
or sh:class
of the same constraint.
The following example illustrates the use of these various features together.
ex:PersonFormShape a sh:Shape ; sh:property [ sh:predicate ex:firstName ; sh:name "first name" ; sh:description "The person's given name(s)" ; sh:order 0 ; sh:group ex:NameGroup ; ] ; sh:property [ sh:predicate ex:lastName ; sh:name "last name" ; sh:description "The person's last name" ; sh:order 1 ; sh:group ex:NameGroup ; ] ; sh:property [ sh:predicate ex:streetAddress ; sh:name "street address" ; sh:description "The street address including number" ; sh:order 11 ; sh:group ex:AddressGroup ; ] ; sh:property [ sh:predicate ex:locality ; sh:name "locality" ; sh:description "The suburb, city or town of the address" ; sh:order 12 ; sh:group ex:AddressGroup ; ] ; sh:property [ sh:predicate ex:postalCode ; sh:name "postal code" ; sh:name "zip code"@en-US ; sh:description "The postal code of the locality" ; sh:order 13 ; sh:group ex:AddressGroup ; ] . ex:NameGroup a sh:PropertyGroup ; sh:order 0 ; rdfs:label "Name" . ex:AddressGroup a sh:PropertyGroup ; sh:order 1 ; rdfs:label "Address" .
A form building application may use the information above to display information as follows:
first name: | John |
last name: | Doe |
street address: | 123 Silverado Ave |
locality: | Cupertino |
zip code: | 54321 |
Part 1 of this specification 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 following sections.
SHACL supports two mechanisms to define constraints using SPARQL:
The following sub-sections are about the latter.
sh:SPARQLConstraint
is a SHACL subclass of sh:Constraint
and is the class of all SPARQL-based constraints. SPARQL-based constraints must have exactly one value for the property sh:select
. The SPARQL queries linked to a constraint via sh:select
must be string literals that can be parsed into legal SPARQL 1.1 queries of the query form SELECT
.
There is an ongoing discussion about whether and how to inject prefixes into SPARQL queries, so the following paragraph may change.
Before parsing the values of sh:select
, a SHACL processor must prepend PREFIX
declarations for all namespace prefixes declared via the property sh:prefix
in the current shapes graph. The subjects of sh:prefix
triples must be IRIs, which become the IRIREF
in the PREFIX
declaration. The objects of sh:prefix
triples must be string literals, which become the PNAME_NS
in the PREFIX
declaration. For the example shapes graph below, a SHACL processor would produce the line PREFIX ex: <http://example.com/ns#>
. No such PREFIX
must be generated if the SPARQL string already contains a PREFIX
statement for the same prefix at the top-level query (ignoring prefixes from nested SELECT queries). The SHACL processor must produce an failure if the shapes graph contains multiple sh:prefix
triples with the same object. Since the use of sh:prefix
triples may lead to conflicts, it is recommended to only use them in closed and controlled environments or for well-established prefixes. In the rest of this document, the sh:prefix
statements may have been omitted for brevity.
The following example illustrates the definition of a SPARQL-based constraint.
ex:ValidCountry a ex:Country ;
ex:germanLabel "Spanien"@de .
ex:InvalidCountry a ex:Country ;
ex:germanLabel "Spain"@en .
<http://example.com/ns#> sh:prefix "ex" . ex:LanguageExampleShape a sh:Shape ; sh:scopeClass ex:Country ; sh:sparql [ a sh:SPARQLConstraint ; sh:message "Values must be literals with German language tag." ; sh:select """ 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 above includes all SHACL instances of ex:Country
. For those RDF nodes (represented by the variable $this
), the SPARQL query walks through the values of ex:germanLabel
and verifies that they are literals with a German language code. The validation results for the aforementioned data graph is shown below:
[ a sh:ValidationResult ; sh:severity sh:Violation ; sh:focusNode ex:InvalidCountry ; sh:subject ex:InvalidCountry ; sh:predicate ex:germanLabel ; 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, following the mapping rules explained later: Each validation result will have $this
as the sh:focusNode
and sh:subject
,
ex:germanLabel
as sh:predicate
and the violating value as sh:object
.
The following table enumerates variables that have special meaning in SPARQL constraints. When SPARQL constraints are executed, the validation engine should pre-bind values for these variables.
Variable | Interpretation |
---|---|
$this |
The focus node. |
$shapesGraph |
Can be used to query the shapes graph as in GRAPH $shapesGraph { ... } . If the shapes graph is a named graph in the same dataset as the data graph then it is the IRI of the shapes graph in the dataset. Not all SHACL validation engines need to support this variable. Processors that do not support $shapesGraph MUST report an error if they encounter a query that references this variable. Use of GRAPH $shapesGraph { ... } should be handled with extreme caution. It may result in constraints that are not interoperable across different SHACL validation engines and that may not run on remote RDF datasets.
|
$currentShape |
The currently validated shape. Typically used in conjunction with $shapesGraph . The same support policies as for $shapesGraph apply for this variable.
|
If one of the rows of the result set produced by a SELECT query contains the binding true
for the variable ?failure
, then the validation engine must signal an error.
Otherwise, 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 |
|
sh:focusNode |
|
sh:subject |
|
sh:predicate |
|
sh:object |
|
sh:message |
|
sh:sourceConstraint |
|
sh:sourceShape |
|
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:select
or sh:ask
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 default values |
For each row of a SELECT result set, a SHACL processor must walk through the declared result annotations. The mapping from result annotations to SPARQL variables uses the following rules:
sh:resultAnnotation
defines a sh:annotationVarName
then the validation engine must look for the variable named after the sh:annotationVarName
sh:annotationProperty
using the same local name mechanism as described earlier
If a variable name could be determined, then the validation engine must copy the bindings for the given variable into the constructed validation results for the current row. If the variable has no binding in the result set row, then the value of sh:annotationValue
must be used, if present.
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.
ex:ShapeWithPathViolationExample a sh:Shape ; sh:scopeNode ex:ExampleRootResource ; sh:sparql [ sh:resultAnnotation [ sh:annotationProperty ex:time ; sh:annotationVarName "time" ] ; sh:select """ SELECT $this ?subject (ex:property2 AS ?predicate) (?first AS ?object) ?message ?time WHERE { $this ex:property1 ?first . ?subject ex:property2 ?first . FILTER isBlank(?value) . BIND (CONCAT("The ", "message.") AS ?message) . BIND (NOW() AS ?time) . } """ ; ] .
ex:ExampleRootResource ex:property1 ex:ExampleIntermediateResource . ex:ExampleValueResource ex:property2 ex:ExampleIntermediateResource .
Which produces the following validation result resource:
[ 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 ] .
SPARQL-based constraints as introduced in the previous section provide a lot of flexibility. However, SPARQL-based constraints may be hard to understand for some people or lead to repetition. Constraint components are a way to abstract the complexity of SPARQL and define high level reusable components similar to the core constraint components. The definition of such constraint components can be represented in the SHACL RDF vocabulary and thus shared and reused.
sh:ConstraintComponent
is the class of all constraint components. Each constraint component must define:
sh:class
, sh:stem
)This section is non-normative.
The following example demonstrates how SPARQL-based constraint components can be applied to define core elements of the SHACL language itself. The example implements sh:pattern
and sh:flags
using a SPARQL ASK query to validate that each value node matches a given regular expression. Note that this is only an example implementation and should not be considered normative.
sh:PatternConstraintComponent a sh:ConstraintComponent ; sh:context sh:NodeConstraint, sh:PropertyConstraint, sh:InversePropertyConstraint ; sh:parameter [ sh:predicate sh:pattern ; sh:order 0 ; ] ; sh:parameter [ sh:predicate sh:flags ; sh:optional true ; sh:order 1 ; ] ; sh:nodeValidator shimpl:hasPattern ; sh:propertyValidator shimpl:hasPattern ; sh:inversePropertyValidator shimpl:hasPattern . shimpl:hasPattern a sh:SPARQLAskValidator ; sh:message "Value does not match pattern {$pattern}" ; sh:ask "ASK { FILTER (!isBlank($value) && IF(bound($flags), regex(str($value), $pattern, $flags), regex(str($value), $pattern))) }" .
The following sections introduce the properties that constraint components may have. Some of these properties are independent of SPARQL-based execution and apply to constraint components based on other potential extension languages such as JavaScript too.
The parameters of a constraint component are declared via the property sh:parameter
. Each parameter must be a SHACL instance of sh:Parameter
, but the rdf:type
triples can be omitted.
There is an open issue about the relationship between SPARQL variable name and sh:predicate. Possible revisions may require an additional property similar to sh:annotationVarName.
Each sh:Parameter
must have exactly one value p
for the property sh:predicate
and the value must be an IRI. The local name of an IRI is defined as the longest NCNAME at the end of the IRI, not immediately preceded by the first colon in the IRI. The local names of the values of sh:predicate
must fulfill the following conditions (to ensure that a correct mapping from parameters into SPARQL variables is possible):
sh:predicate
with the same local namethis
, shapesGraph
or currentShape
.subject
, predicate
or object
.
An sh:Parameter
may have its property sh:optional
set to true
to indicate that the parameter is not mandatory. Every sh:ConstraintComponent
must have at least one non-optional parameter.
The class sh:Parameter
is defined as a SHACL subclass of sh:PropertyConstraint
, and all properties that are applicable to property constraints may also be used for parameters. This includes descriptive properties such as sh:name
and sh:description
but also constraint parameters such as sh:class
. Some implementations MAY use these constraint parameters to prevent the execution of constraint components with invalid parameter values.
The property sh:labelTemplate
can be used at any constraint component to suggest how they could be rendered to humans. The values of sh:labelTemplate
must be strings (possibly with language tag) that can reference the values of the declared parameters using the syntax {?varName}
or {$varName}
, where varName
is the name of the SPARQL variable that corresponds to the parameter. At display time, these {...}
blocks SHOULD be substituted with the actual parameter values. There may be multiple label templates for the same subject, assuming they do not have the same language tags.
Each sh:ConstraintComponent
can define one or more contexts with the sh:context
predicate. The values of sh:Context
are restricted to:
sh:PropertyConstraint
, to allow the constraint component parameters in sh:property
definitions.sh:InversePropertyConstraint
, to allow the constraint component parameters in sh:inverseProperty
definitions.sh:NodeConstraint
, to allow the constraint component parameters in sh:constraint
definitions.For every provided context in the constraint component, a suitable validator must be declared. Each context defines a dedicated property that links to a validator according to the following table.
Context | Validator Property |
---|---|
sh:NodeConstraint |
sh:nodeValidator |
sh:PropertyConstraint |
sh:propertyValidator |
sh:InversePropertyConstraint |
sh:inversePropertyValidator |
SHACL includes two types of validators, based on SPARQL SELECT or SPARQL ASK queries. For each provided context, one validator must be defined in the shapes graph.
Validators that have the rdf:type
sh:SPARQLSelectValidator
must point at exactly one string representation of a SPARQL SELECT query via the property sh:select
. The value of sh:select
must be a valid SPARQL query using the aforementioned prefix handling rules.
The following example illustrates the definition of a constraint component based on a SPARQL SELECT query. It is a generalized variation of the SPARQL-based example constraint from the section on SPARQL-based constraints. That SPARQL query included two constants: the specific property ex:germanLabel
and the language tag de
. Constraint components make it possible to generalize such scenarios, so that constants get pre-bound with parameters. This allows the query logic to be reused in multiple places, without having to write any new SPARQL.
ex:LanguageConstraintComponentUsingSELECT a sh:ConstraintComponent ; rdfs:label "Language constraint component" ; sh:context sh:PropertyConstraint ; sh:parameter [ sh:predicate ex:lang ; sh:datatype xsd:string ; sh:minLength 2 ; sh:name "language" ; sh:description "The language tag, e.g. \"de\"." ; ] ; sh:labelTemplate "Values must be literals with language \"{$lang}\"" ; sh:propertyValidator [ a sh:SPARQLSelectValidator ; sh:message "Values must be literals with language \"{?lang}\"" ; sh:select """ SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER (!isLiteral(?value) || !langMatches(lang(?value), $lang)) } """ ] .
Once a constraint component has been defined, its parameters can be used in the declared contexts, as illustrated in the following example. The sh:context
of the given constraint component includes sh:PropertyConstraint
which means that the new parameter ex:lang
can be used in values of sh:property
. Furthermore, the SPARQL query can access the provided sh:predicate
using the variable $predicate
.
ex:LanguageExampleShape a sh:Shape ; sh:scopeClass ex:Country ; sh:property [ sh:predicate ex:germanLabel ; ex:lang "de" ; ] ; sh:property [ sh: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 property constraints that provide values for the ex:lang
parameter required by the constraint component.
A SPARQL-based SHACL validation engine executes the provided SPARQL query with the same pre-bound variables as outlined in the section for SPARQL-based Constraints ($this
etc). Additionally, the value of each declared parameter of the constraint component needs to be pre-bound for the variable derived by the local name of the parameter's sh:predicate
. For example, if a non-optional parameter declares sh:predicate ex:lang
then the variable $lang
needs to be pre-bound. The result set of the SELECT query is turned into validation results using the same rules as outlined in the section for SPARQL-based Constraints. In addition to the result properties listed in that section, the property sh:sourceConstraintComponent
MUST point at the IRI of the constraint component that has been evaluated. Furthermore, a sh:SPARQLSelectValidator
may declare additional annotation properties via sh:resultAnnotation
.
Many constraint components are of the form in which all value nodes are tested individually against some boolean condition. Writing SELECT queries for these becomes burdensome, especially if a constraint component can be used in multiple contexts. SHACL provides an alternative, more compact syntax for validators based on ASK queries.
Validators that have the rdf:type
sh:SPARQLAskValidator
must point at exactly one string representation of a SPARQL ASK query via the property sh:ask
. The value of sh:ask
must be a valid SPARQL query using the aforementioned prefix handling rules. The ASK queries are expected to return true
if a given value node (represented by the pre-bound variable ?value
) is valid.
Prior to evaluation, a SHACL validation engine transforms the provided ASK query into a SELECT query using the following templates. The engine drops the ASK keyword, leaving only the fraction between the outermost {...}
pair. This block then substitutes ...
in the template.
Template for sh:NodeConstraint
context:
SELECT $this WHERE { BIND ($this AS ?value) . FILTER NOT EXISTS ... }
Template for sh:PropertyConstraint
context:
SELECT $this ($this AS ?subject) $predicate (?value AS ?object) WHERE { $this $predicate ?value . FILTER NOT EXISTS ... }
Template for sh:InversePropertyConstraint
context:
SELECT $this ($this AS ?object) $predicate (?value AS ?subject) WHERE { ?value $predicate $this . FILTER NOT EXISTS ... }
The templates need to use a different variable than ?value
if the constraint component has a parameter that would cause ?value
to be a pre-bound variable.
Once the corresponding template has been applied, the resulting SELECT query will be evaluated using the same approach as outlined above. Actual SHACL implementations may of course use a different approach internally, as long as the results are equivalent to the described approach.
The following example defines a constraint component using an ASK query. Note that the example represents the validator with an IRI node ex:hasLang
so that it becomes easier to reuse the same validator for both contexts.
ex:LanguageConstraintComponentUsingASK a sh:ConstraintComponent ; rdfs:label "Language constraint component" ; sh:context sh:NodeConstraint, sh:PropertyConstraint ; sh:parameter [ sh:predicate ex:lang ; sh:datatype xsd:string ; sh:minLength 2 ; sh:name "language" ; sh:description "The language tag, e.g. \"de\"." ; ] ; sh:labelTemplate "Values must be literals with language \"{$lang}\"" ; sh:nodeValidator ex:hasLang ; sh:propertyValidator ex:hasLang . ex:hasLang a sh:SPARQLAskValidator ; sh:message "Values must be literals with language \"{$lang}\"" ; sh:ask """ ASK { FILTER (isLiteral($value) && langMatches(lang($value), $lang)) } """ .
Note that the validation condition implemented by an ASK query is "in the inverse direction" from its SELECT counter-part: ASK queries return true
for valid value nodes, while SELECT queries return the invalid value nodes.
TODO: The TopBraid SHACL API uses such ASK constraint declarations to install new SPARQL functions. Time permitting we could standardize that too, so that people can reuse the same business logic in the queries.
SHACL provides facilities to define custom scopes. Similar to constraints, scopes may either be SPARQL-based scopes or
SPARQL-based scope types in a higher-level vocabulary. All subjects of sh:scope
triples must be IRIs.
SPARQL-based scopes must be SHACL instances of sh:SPARQLScope
, which is a SHACL subclass of sh:Scope
. The SPARQL queries linked to a scope via sh:select
must be of the query form SELECT
. The SELECT queries must project to the result variable ?this
. The resulting scope consists of all distinct bindings for the variable ?this
.
The SELECT queries must also be executable when converted to an ASK query and with a pre-bound value for ?this
. The set of bindings for ?this
that return true
for such ASK queries must be identical to the set produced by the SELECT query. This design makes sure that validation engines can validate whether a given shape applies to a given individual focus node.
The following example illustrates a well-formed SPARQL-based scope that produces all persons born in the USA:
ex:USCitizenShape a sh:Shape ; sh:scope [ a sh:SPARQLScope ; sh:select """ SELECT ?this WHERE { ?this a ex:Person . ?this ex:bornIn ex:USA . } """ ; ] ; sh:constraint ...
The class sh:ScopeType
can be used to define high-level vocabularies for scopes. Similar to constraint components, such scopes take parameters that are interpreted when the scope is evaluated. The class sh:SPARQLScopeType
is a SHACL subclass of sh:ScopeType
for scope types that define a SPARQL SELECT query via the property sh:select
. Similar to constraint components, the parameter values become pre-bound variables in such SPARQL queries. The parameter values of such scopes must not be blank nodes. All parameters of scope types are expected to have sh:maxCount 1
. Similar to constraint components, scope types may also have values for the property sh:labelTemplate
.
The following example defines a new SPARQL-based parameterizable scope class that takes one parameter ex:country
that gets mapped into the variable $country
in the corresponding SPARQL query to determine the resulting focus nodes.
ex:PeopleBornInCountryScope a sh:SPARQLScopeType ; rdfs:subClassOf sh:Scope ; sh:labelTemplate "All persons born in {$country}" ; sh:parameter [ sh:predicate ex:country ; sh:name "country" ; sh:description "The country that the focus nodes must be born in." ; sh:class ex:Country ; sh:minCount 1 ; sh:maxCount 1 ; sh:nodeKind sh:IRI ; ] ; sh:select """ SELECT ?this WHERE { ?this a ex:Person . ?this ex:bornIn $country . } """ . ex:USCitizenShape a sh:Shape ; sh:scope [ a ex:BornInCountryScope ; ex:country ex:USA ; ] ; sh:constraint ...
The set of scope nodes produced by such a scope type consists of all bindings of the variable ?this
in the result set, when the SPARQL SELECT query has been executed with the pre-bound parameter values.
It is a common scenario that certain property values are derived from other values. For example, the area of a rectangle must be the product of width and height, or an uncle of a person is a male sibling of a parent. SHACL includes a constraint parameter sh:derivedValues
that can be used with property and inverse property constraints to define such constraints.
Constraint Component: sh:DerivedValuesConstraintComponent
Supported Contexts: sh:PropertyConstraint
, sh:InversePropertyConstraint
.
Property | Value Type | Summary |
---|---|---|
sh:derivedValues |
sh:ValuesDeriver |
An object providing instructions on how to derive the values |
The values of sh:derivedValues
must be SHACL instances of a SHACL subclass of sh:ValuesDeriver
.
sh:SPARQLValuesDeriver
is the only SHACL subclass of sh:ValuesDeriver
defined by SHACL. Each sh:SPARQLValuesDeriver
must have exactly one value for the property sh:select
that can be used to produce the values that the property is expected to have. The values of sh:select
must be SPARQL SELECT queries that project into the variable ?value
only. These queries can access the current focus node via the variable $this
and must produce bindings for the variable ?value
for all derived values.
sh:predicate
that is not in S, and for every member of S that is not a property value. The produced validation result must have the focus node as its sh:subject
, the sh:predicate
as its sh:predicate
, and the missing or extra value as its sh:object
. (The same definition applies in the inverse direction if sh:derivedValues
is used in an inverse property constraint.)
The following example illustrates the use of sh:derivedValues
to define a restriction so that the value of the property ex:area
must be the product of the value of ex:width
and sh:height
.
ex:RectangleShape a sh:Shape ; sh:property [ sh:predicate ex:width ; sh:datatype xsd:integer ; sh:maxCount 1 ; ] ; sh:property [ sh:predicate ex:height ; sh:datatype xsd:integer ; sh:maxCount 1 ; ] ; sh:property [ sh:predicate ex:area ; sh:datatype xsd:integer ; sh:derivedValues [ a sh:SPARQLValuesDeriver ; sh:select """ SELECT ?value WHERE { $this ex:width ?width . $this ex:height ?height . BIND (?width * ?height AS ?value) . } """ ; ] ; ] .
SHACL functions define operations that produce an RDF node based on zero or more parameters and an input RDF graph (or 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 that encapsulate a SPARQL query must be SHACL instances of sh:SPARQLFunction
, which is a SHACL subclass of the more general class sh:Function
. Such functions must provide exactly one value for either sh:ask
or sh:select
, linking to a SPARQL query.
The following example illustrates the definition of a function based on a simple mathematical SPARQL query.
ex:exampleFunction a sh:SPARQLFunction ; rdfs:comment "Computes the sum of its two parameters ?op1 and ?op2." ; sh:parameter [ sh:predicate ex:op1 ; sh:datatype xsd:integer ; sh:description "The first operand" ; ] ; sh:parameter [ sh:predicate ex:op2 ; sh:datatype xsd:integer ; sh:description "The second operand" ; ] ; sh:returnType xsd:integer ; sh:select """ SELECT ($op1 + $op2 AS ?result) WHERE { } """ .
Using the declaration above, SPARQL engines with full SHACL support can install a new SPARQL function based on the SPARQL 1.1 Extensible Value Testing mechanism. Such engines are then able to handle expressions such as ex:exampleFunction(40, 2)
, producing 42
, as illustrated in the following SPARQL query.
SELECT ?subject WHERE { ?subject ex:myProperty ?value . FILTER (ex:exampleFunction(?value, 2) = 42) . }
The following sections introduce the properties that such functions may have.
The parameters of a function are linked to its sh:Function
via the property sh:parameter
. Each parameter must be a SHACL instance of sh:Parameter
, but their rdf:type
triple can be omitted.
Each sh:Parameter
must have exactly one value for the property sh:predicate
. The values of sh:predicate
must be IRIs, and follow the following restrictions:
sh:Parameter
for the same function that has a sh:predicate
with the same local name
Parameters are ordered, corresponding to the notation of function calls in SPARQL such as
ex:exampleFunction(?param1, ?param2)
. The ordering of function parameters is determined as follows:
sh:order
.sh:order
are placed after those that have.sh:order
are ordered by the local names of their declared sh:predicate
s.
Each sh:Parameter
may have its property sh:optional
set to true
to indicate that the parameter is not mandatory.
A function may declare a single return type via sh:returnType
. This information may serve for documentation purposes, only. However, in some execution languages such as JavaScript, the declared sh:returnType
may inform a processor how to cast a native value into an RDF term.
SHACL instances of sh:SPARQLFunction
must have exactly one value for either sh:ask
or sh:select
. The values of this property must be strings that can be parsed into SPARQL queries of type ASK (for sh:ask
) or SELECT (for sh:select
). SELECT queries must project exactly one result variable and SHOULD not use the SELECT *
syntax. In the SPARQL query, the SPARQL processor needs to pre-bind variables based on the provided parameters of the function call. For ASK queries, the function's return value is the result of the ASK query execution, i.e. true
or false
. For SELECT queries, the function's return value is the binding of the (single) result variable of the first row 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. Also note that the result variable may be unbound, making the return value of the function undefined.
Recursive use of functions is undefined: If a SPARQL-based function contains calls to other functions so that the same function with the same combination of parameters would be visited twice then the result of the function call is undefined. An implementation may either return no result (unbound) or terminate the surrounding SPARQL query with an error.
Some processors may ignore the specified SPARQL query and rely on an alternative (possibly native) implementation instead, as long as the functions return the same values as the specified SPARQL query. This can be used to optimize frequently needed functions. Some processors may even use the SPARQL query to rewrite other SPARQL queries via inlining techniques.
By default, SHACL does not assume any entailment regime [sparql11-entailment] to be activated on the data graph. However, the property sh:entailment
can be used to instruct a SHACL validation engine to ensure that a given entailment is activated on the data graph. The values of sh:entailment
must be IRIs, with common use cases covered by [sparql11-entailment].
SHACL validation engines are not required to support any entailment regimes. If an entailment regime is provided in the data graph which is not supported by the engine, the validation must produce a failure.
SHACL implementations with full support of the SHACL SPARQL extension mechanism must implement a function sh:hasShape
, which takes the following parameters:
Parameter | Value Type | Summary |
---|---|---|
focusNode |
rdfs:Resource |
The focus node to validate. |
shape |
rdfs:Resource |
The shape to validate the focus node against. |
shapesGraph |
rdfs:Resource |
The IRI of the current shapes graph. |
An example call of this function is
BIND (sh:hasShape(ex:JohnDoe, ex:PersonShape, $shapesGraph) AS ?hasShape)
None of the parameters can be unbound. The result of the sh:hasShape
function is either true
, false
or undefined:
sh:hasShape
has recursively called sh:hasShape
with exactly the same parameters, i.e. the same node/shape/shapesGraph combination. This result indicates a failure.true
if the validation of the focusNode
against the given shape
produces no validation results with severity sh:Violation
.false
if the validation of the focusNode
against the given shape
produces at least one validation result with severity sh:Violation
.
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 validation process. However, some implementations may add those nested validation results as annotations to the surrounding validation results, via sh:detail
.
The following definition of what pre-binding means has not been approved by the WG yet, and is work in progress.
Some features of the SPARQL-based extension mechanism of SHACL rely on the concept of pre-binding of variables. Although variations of this concept are supported by several existing SPARQL implementations, there is no formal definition of pre-binding in the SPARQL 1.1 specifications. The goal of this section is to illustrate the effect of pre-binding to users and implementers. Note however that the following definition is not meant to serve as recommendation for an actual implementation strategy.
Pre-binding a variable with a value means that the SPARQL processor needs to evaluate all occurrences of variables with that same name (including occurrences in inner scopes and nested SELECT queries) so that they have the provided value. In other words, whenever a SPARQL processor evaluates a pre-bound variable, it must use the given value.
Some SHACL properties such as sh:property
, sh:filterShape
and sh:parameter
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
. 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
. SHACL includes a resource sh:DefaultValueTypeRule
that encapsulates a SPARQL query via sh:construct
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 }) . }
This section is non-normative.
Many people contributed to this specification, including members of the RDF Data Shapes Working Group. We especially thank the following:
Arnaud Le Hors (chair), Jim Amsden, Iovka Boneva, Karen Coyle, Richard Cyganiak, Michel Dumontier, Holger Knublauch, Dimitris Kontokostas, Jose Labra, Peter Patel-Schneider, Eric Prud'hommeaux, Arthur Ryman (who also served as a co-editor until Feb 2016), Harold Solbrig, Simon Steyskal, Ted Thibodeau