Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document defines the SHACL Shapes Constraint Language, a language for validating RDF graphs against a set of conditions. These conditions are provided as shapes and other constructs expressed in the form of an RDF graph. RDF graphs that are used in this manner are called "shapes graphs" in SHACL and the RDF graphs that are validated against a shapes graph are called "data graphs". As SHACL shape graphs are used to validate that data graphs satisfy a set of conditions they can also be viewed as a description of the data graphs that do satisfy these conditions. Such descriptions may be used for a variety of purposed beside validation, including user interface building, code generation and data integration.
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 https://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:Violationsh: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 language 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, targets 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 validating 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. A property path is a possible route in a graph between two graph nodes. SHACL supports a subset of the property path syntax from SPARQL 1.1, including inverse paths and sequences.
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: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.
sh:Shape. A shape provides a collection of targets, filters, constraints and parameters of constraint components that specify how a data graph is validated against the shape. Shapes can also provide non-validating information, such as labels and comments.
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 omitted 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 target 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 eight total nodes, out of which three nodes 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 .
SHACL can be used to define the following example 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:targetClass ex:Person ; # Applies to all persons
sh:property [
sh:predicate ex:ssn ; # Constrains the values of the ex:ssn property
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:property [
rdfs:comment "A person's parents are represented via ex:child used in the inverse direction." ;
sh:path [ sh:inversePath ex:child ] ;
sh:name "parent" ;
sh:maxCount 2 ;
] ;
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 targets of the shape and are defined using the property sh:targetClass. The shape has three property constraints, linked to the shape using the property sh:property, one of which uses a path expression. The shape furthermore defines a constraint on the focus nodes themselves using the parameters sh:closed and sh:ignoredProperties.
Some of the property 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 the 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:sourceShape ex:PersonShape ; sh:focusNode ex:Alice ; sh:path ex:ssn ; sh:value "987-65-432A" ; sh:severity sh:Violation ; ] ; [ a sh:ValidationResult ; sh:sourceConstraintComponent sh:MaxCountConstraintComponent ; sh:sourceShape ex:PersonShape ; sh:focusNode ex:Bob ; sh:path ex:ssn ; sh:severity sh:Violation ; ] ; [ a sh:ValidationResult ; sh:sourceConstraintComponent sh:ClosedConstraintComponent ; sh:sourceShape ex:PersonShape ; sh:focusNode ex:Calvin ; sh:path ex:school ; sh:value 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 the the property sh:closed set to true 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 targets. However, SPARQL is not required for the implementation of the SHACL Core language.
SPARQL variables using the $ marker represent external values that must be pre-bound or substituted 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, targets, derived values 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 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 targets 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 targeting and filtering process. SHACL validation engines MAY alter the order of the depicted steps as long as the returned validation results are correct.
Targets specify which nodes in the data graph are validated against a shape. While targets define the starting points of the validation process, some shapes may validate a) less target nodes when a shapes defines filters or b) additional nodes against different shapes, for example referenced via sh:shape and sh:or.
The Core of SHACL includes four Core target types: node targets, class-based targets, subjects-of targets, and objects-of targets.
The SHACL language additionally defines an advanced general target mechanism based on SPARQL.
When multiple targets are provided in a shape, the target of a shape is the union of all nodes produced by these individual targets. Nodes specified by targets are not required to exist in the data graph.
A node target is defined with the sh:targetNode predicate. The values of sh:targetNode can be IRIs or literals. Each value of a node target defines a node to validate in the data graph.
With the example data below, only ex:Alice is the target of the provided shape:
ex:PersonShape a sh:Shape ; sh:targetNode ex:Alice .
ex:Alice a ex:Person .
ex:Bob a ex:Person .
The following SPARQL query specifies the semantics of node targets. The variable $targetNode is assumed to be pre-bound to the given value of sh:targetNode.
SELECT DISTINCT ?this
WHERE {
BIND ($targetNode AS ?this)
}
A class target is defined with the sh:targetClass predicate. Each value of sh:targetClass must be an IRI that is expected to be a SHACL class. For every value c of a class target, all SHACL instances of c in the data graph are validated against the subject of the sh:targetClass triple.
ex:PersonShape a sh:Shape ; sh:targetClass 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 validated. Note that, according to the SHACL instance definition, all the rdfs:subClassOf declarations needed to walk the class hierarchy 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 target node is only ex:Who.
ex:Doctor rdfs:subClassOf ex:Person .
ex:Who a ex:Doctor .
ex:House a ex:Nephrologist .
The following SPARQL query specifies the semantics of class targets. The variable $targetClass is assumed to be pre-bound to the given value of sh:targetClass.
SELECT DISTINCT ?this
WHERE {
?this rdf:type/rdfs:subClassOf* $targetClass
}
When, in the shapes graph, a shape is a SHACL instance of both sh:Shape and rdfs:Class then the shape is a class target of itself.
ex:Person a rdfs:Class, sh:Shape .
ex:Alice a ex:Person .
In this example, only ex:Alice is validated, because it is a SHACL instance of
ex:Person which is both a class and a shape in the shapes graph.
A subjects-of target is defined with the predicate sh:targetSubjectsOf, the values of which must be IRIs. For every value p of such a target, the validated nodes are defined as the set of subjects in the data graph that appear in a triple with p as a predicate.
In other words, this type of target can be used to state that a shape applies to all nodes in the data graph that have at least one value of the given property.
ex:TargetSubjectsOfExampleShape a sh:Shape ; sh:targetSubjectsOf ex:knows .
ex:Alice ex:knows ex:Bob .
ex:Bob ex:livesIn ex:NewYork .
In the example above, only ex:Alice is validated against the given shape, because it is the subject of a triple that has ex:knows as its predicate.
The following SPARQL query specifies the semantics of subjects-of targets. The variable $targetSubjectsOf is assumed to be pre-bound to the given value of sh:targetSubjectsOf.
SELECT DISTINCT ?this
WHERE {
?this $targetSubjectsOf ?any .
}
An objects-of target is defined with the predicate sh:targetObjectsOf, the values of which must be IRIs. For every value p of such a target, the validated nodes are defined as the set of objects in the data graph that appear in a triple with p as a predicate.
ex:TargetObjectsOfExampleShape a sh:Shape ; sh:targetObjectsOf ex:knows .
ex:Alice ex:knows ex:Bob .
ex:Bob ex:livesIn ex:NewYork .
In the example above, only ex:Bob is validated against the given shape, because it is the object of a triple that has ex:knows as its predicate.
The following SPARQL query specifies the semantics of objects-of targets. The variable $targetObjectsOf is assumed to be pre-bound to the given value of sh:targetObjectsOf.
SELECT DISTINCT ?this
WHERE {
?any $targetObjectsOf ?this .
}
A filter is a shape in a shapes graph that can be used to limit the nodes that are validated against a given constraint or shape. Only those nodes that validate against all the filters are validated. A filter is specified with the sh:filterShape predicate.
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:members of ex:W3c.
ex:ExampleFilteredShape
a sh:Shape ;
sh:targetClass 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:path ex:email ; sh:message "sh:minCount for ex:email is '1'." ; sh:sourceConstraintComponent sh:MinCountConstraintComponent ; sh:sourceShape ex:ExampleFilteredShape ; ] .
The following example shows a sh:filterShape that is defined on a specific property constraint, instead of the whole shape. In this scenario, the sh:minCount constraint is only applied to persons that are also member of ex:W3c.
ex:FilteredExampleShape a sh:Shape ; sh:targetClass ex:Person ; sh:property [ sh:predicate ex:email ; sh:minCount 1 ; sh:filterShape [ sh:property [ sh:predicate ex:member ; sh:hasValue ex:W3c ; ] ] ; ] .
Filter shapes MUST be evaluated before validating the associated shapes or constraints. 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 targets of these shapes are not used to limit the set of focus nodes.
Constraints are defined within a shape and sh:Constraint is the SHACL superclass of all constraint types. The SHACL Core language defines two types of constraints: a) constraints about a particular property or path and its values for the focus node (property constraints) and b) constraints about the focus node itself (focus node constraints).
Additional types of constraints can be added using the extension mechanism, as SPARQL-based constraints or SPARQL-based constraint components.
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 catalog of constraint components in the Core of SHACL is defined in section 4.
Property constraints specify conditions that must be met with respect to nodes that can be reached from the
focus node either by directly following a given property (specified using sh:predicate) or a given property path (specified using sh:path).
Property constraints are linked from a shape with the property sh:property. The values of sh:property must be IRIs or blank nodes that are the subject of precisely one triple with either predicate sh:predicate or sh:path. The values of sh:predicate must be IRIs. The values of sh:path must be well-formed property paths following the SHACL property path syntax rules.
The following example illustrates the two syntax variations of property constraints.
ex:ExampleShapeWithPropertyConstraints
a sh:Shape ;
sh:property [
sh:predicate ex:email ;
sh:name "e-mail" ;
sh:description "We need at least one email value" ;
sh:minCount 1 ;
] ;
sh:property [
sh:path (ex:knows ex:email) ;
sh:name "Friend's e-mail" ;
sh:description "We need at least one email for everyone you know" ;
sh:minCount 1 ;
] .
sh:PropertyConstraint is the class of property constraints. A SHACL validation engine treats all values of sh:property as property constraints. Thus, the values of sh:property do not require the rdf:type sh:PropertyConstraint triple.
Focus node constraints define constraints about the focus node itself. Since focus node constraints operate directly on the input focus nodes they impose some limitations in comparison to property constraints. In particular, constraints that operate on value sets, such as sh:hasValue and sh:equals, are not applicable to focus node constraints. Focus node constraints are attached directly to Shapes and sh:shape can be used to group focus node constraints.
ex:ExampleFocusNodeConstraint a sh:Shape ; sh:targetClass ex:Person ; sh:stem "https://www.w3.org/People/" .
sh:Shape is defined as rdfs:subClassOf sh:Constraint.
Parameters of constraint components that only declare one parameter, such as sh:class, may be used multiple times within the same constraint node. The interpretation of such declarations is conjunction, i.e. all constraints must validate. Constraints that declare more than one parameters, such as sh:pattern, are not allowed to be declared more than once in the same constraint. 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 ; ] .
SHACL includes an RDF vocabulary to represent property paths that can be mapped into a subset of SPARQL 1.1 property paths. In particular, SHACL supports the following SPARQL 1.1 property path constructs:
PredicatePath, InversePath, SequencePath, AlternativePath,
ZeroOrMorePath, OneOrMorePath and ZeroOrOnePath. A valid SHACL property path p is represented by an IRI or a blank node that can be correctly traversed recursively using the following rules.
p sh:inversePath elt then the path becomes an InversePath element of elt and elt must be a valid SHACL property path. Corresponding rules apply for
sh:zeroOrMorePath (ZeroOrMorePath),
sh:zeroOrOnePath (ZeroOrOnePath) and
sh:oneOrMorePath (OneOrMorePath).
p rdf:first elt, the path must be a well-formed RDF list with a at least two members. Each member must be valid SHACL property path that is converted into a sequence of either SequencePath or AlternativePath elements.
p sh:alternativePath elt, the value of path must be a well-formed RDF list with a at least two members. All members must be valid SHACL property paths that become a series of AlternativePath elements.
p is an IRI then it is turned into a PredicatePath with value p.
A SHACL property path is invalid if:
p is a blank node that is not handled by any of the above rules.p with a predicate different from:
sh:inversePath, sh:alternativePath, sh:zeroOrMorePath,
sh:zeroOrOnePath, sh:oneOrMorePath or rdf:first.p as a subject.The following example illustrates some valid SHACL property paths, together with their SPARQL 1.1 equivalents.
# ^ex:parent [ sh:inversePath ex:parent ] . # ex:parent/ex:firstName ( ex:parent ex:firstName ) . # rdf:type/rdfs:subClassOf* ( rdf:type [ sh:zeroOrMorePath rdfs:subClassOf ] ) . # ex:father|ex:mother [ sh:alternativePath ( ex:father ex:mother ) ] .
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 or a failure 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 targets and validate Core SHACL constraints.
A data graph or a shapes 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.
<http://example.com/myDataGraph> sh:shapesGraph ex:graph-shapes1 ; sh:shapesGraph ex:graph-shapes2 .
The same mechanism applies for ontologies or vocabularies included in the shapes graph. The ontology or the vocabulary IRI can point to one or more shapes graphs with the predicate sh:shapesGraph. A SHACL validation engine MAY take this information into account to determine which shapes graph to use for validating a data graph that uses that ontology or vocabulary.
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. Note that the produced values of sh:message are implementation-specific and not prescribed by the SHACL language.
ex:ExampleConstraintViolation a sh:ValidationResult ; sh:severity sh:Violation ; sh:focusNode ex:Bob ; sh:path ex:age ; sh:value "twenty two" ; sh:message "ex:age expects a literal of datatype xsd:integer." ; sh:sourceConstraintComponent sh:DatatypeConstraintComponent ; sh:sourceShape ex:PersonShape .
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 must have a single value for the property sh:focusNode to point to a
node that has caused the result. This represents the focus node that was validated when the validation result was produced.
Validation results can have one value for the property sh:path pointing at a well-formed property path starting with the given sh:focusNode. For results produced by a property constraint, this path is always identical to either the sh:predicate or sh:path of the constraint.
Validation results can have one value for the property sh:value pointing at a specific node that has caused the result.
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 ; ] .
This sections defines the built-in SHACL constraint components that MUST be supported by all SHACL validation engines. Each constraint component is identified by an IRI that is referenced in the validation results via sh:sourceConstraintComponent.
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 language alone. Instead, SHACL provides an extension mechanism, described in the second part of this specification. It is expected that additional reusable libraries of constraint components will be maintained by third parties.
All constraint components can be used both in property constraints and focus node constraints. However, some components might always fail in a particular constraint type. For example, sh:closed does not make sense in property constraints or sh:hasValue in focus node constraints.
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:predicate the value nodes are the objects of the triples that have the focus node as subject and the given property as predicate. Each produced validation result must have the focus node as its sh:focusNode, the sh:predicate as its sh:path and, if applicable, the respective violating value node as its sh:value.
sh:path the value nodes are the objects in the data graph that can be reached by following the given property path starting with the
focus node as subject based on the evaluation rules defined by SPARQL 1.1. Each produced validation result must have the focus node as its sh:focusNode, a deep copy of sh:path as its sh:path and, if applicable, the respective violating value node as its sh:value.
The SPARQL definitions in this section represent potential validators. Many constraint components are represented by a SPARQL ASK query. These queries are interpreted against each value node, bound to the variable $value. If a value node fails the ASK query, a validation result is produced based on the rules outlined in the section on ASK-based validators. Constraint components that are described using a SELECT query are interpreted based on the rules outlined in the section on SELECT-based validators. In particular, for sh:PropertyConstraints, the variable $PATH is substituted with a path expression based on the values of either sh:predicate or sh:path in the constraint. All SPARQL queries 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.
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.
Some SPARQL definitions in this section also assume the existence of a built-in SPARQL function sh:hasShape.
The constraint components in this section have in common that they define restrictions on the type of the nodes. Note that it is possible to represent multiple value type options using sh:or.
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
| Property | Value Type | Summary |
|---|---|---|
sh:class |
rdfs:Resource |
Type of all values |
ASK {
$value rdf:type/rdfs:subClassOf* $class .
}
ex:ClassExampleShape a sh:Shape ; sh:targetNode 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: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
| Property | Value Type | Summary |
|---|---|---|
sh:datatype |
rdfs:Resource |
Datatype of all value nodes (e.g., xsd:integer) |
ASK {
FILTER (datatype($value) = $datatype) .
}
ex:DatatypeExampleShape a sh:Shape ; sh:targetNode 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:nodeKind is used to restrict the RDF node kind of each value node.
Constraint Component: sh:NodeKindConstraintComponent
| 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 one of the following six instances of the class sh:NodeKind:
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.
ASK {
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:targetNode 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 a property constraint, to represent restrictions on the number of values that the focus node may have for the given property or property path.
The property sh:minCount restricts the number of value nodes.
Constraint Component: sh:MinCountConstraintComponent
| 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
WHERE {
OPTIONAL {
$this $PATH ?value .
}
}
GROUP BY $this
HAVING (COUNT(?value) < $minCount)
ex:MinCountExampleShape a sh:Shape ; sh:targetNode 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 value nodes.
Constraint Component: sh:MaxCountConstraintComponent
| 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
WHERE {
$this $PATH ?value .
}
GROUP BY $this
HAVING (COUNT(?value) > $maxCount)
ex:MaxCountExampleShape a sh:Shape ; sh:targetNode 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 value nodes. The supported datatypes of these nodes 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
| 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.
ASK {
FILTER ($minExclusive < $value)
}
ex:NumericRangeExampleShape a sh:Shape ; sh:targetNode 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
| 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. |
ASK {
FILTER (STRLEN(str($value)) >= $minLength) .
}
The property sh:maxLength restricts the string length of value nodes This can be applied to any literals and IRIs, but not to blank nodes.
Constraint Component: sh:MaxLengthConstraintComponent
| 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. |
ASK {
FILTER (STRLEN(str($value)) <= $maxLength) .
}
ex:PasswordExampleShape a sh:Shape ; sh:targetNode 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
| 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 third argument of the SPARQL REGEX function.
ASK {
FILTER (!isBlank($value) && IF(bound($flags), regex(str($value), $pattern, $flags), regex(str($value), $pattern)))
}
ex:PatternExampleShape a sh:Shape ; sh:targetNode 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
| Property | Value Type | Summary |
|---|---|---|
sh:stem |
xsd:string |
String value that an IRI must start with |
ASK {
FILTER (isIRI($value) && STRSTARTS(str($value), $stem))
}
ex:StemExampleShape a sh:Shape ; sh:targetNode 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:booleans.
Constraint Component: sh:UniqueLangConstraintComponent
| 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 ?lang
WHERE {
{
FILTER ($uniqueLang) .
}
$this $PATH ?value .
BIND (lang(?value) AS ?lang) .
FILTER (bound(?lang) && ?lang != "") .
FILTER EXISTS {
$this $PATH ?otherValue .
FILTER (?otherValue != ?value && ?lang = lang(?otherValue)) .
}
}
ex:UniqueLangExampleShape a sh:Shape ; sh:targetNode 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
| Property | Value Type | Summary |
|---|---|---|
sh:equals |
rdfs:Resource |
Property to compare with |
sh:equals and for each value of the property specified using sh:equals that does not exist as value node.
SELECT $this ?value
WHERE {
{
$this $PATH ?value .
MINUS {
$this $equals ?value .
}
}
UNION
{
$this $equals ?value .
MINUS {
$this $PATH ?value .
}
}
}
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:targetNode 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
| Property | Value Type | Summary |
|---|---|---|
sh:disjoint |
rdfs:Resource |
The property to compare the values with |
sh:disjoint at the given focus node.
SELECT $this ?value
WHERE {
$this $PATH ?value .
$this $disjoint ?value .
}
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:targetNode 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
| Property | Value Type | Summary |
|---|---|---|
sh:lessThan |
rdfs:Resource |
The property to compare the values with |
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.
SELECT $this ?value
WHERE {
$this $PATH ?value .
$this $lessThan ?otherValue .
FILTER (!(?value < ?otherValue)) .
}
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
| Property | Value Type | Summary |
|---|---|---|
sh:lessThanOrEquals |
rdfs:Resource |
The property to compare the values with |
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.
SELECT $this ?value
WHERE {
$this $PATH ?value .
$this $lessThan ?otherValue .
FILTER (!(?value <= ?otherValue)) .
}
The constraint components in this section implement the common logical operators and, or and not.
SHACL supports a negation constraint component 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
| 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) .
}
SELECT $this ?value ?failure
WHERE {
$this $PATH ?value .
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:targetNode ex:InvalidInstance1 ; sh:not [ a sh:Shape ; sh:property [ sh:predicate ex:property ; sh:minCount 1 ; ] ; ] .
ex:InvalidInstance1 ex:property "Some value" .
SHACL supports a conjunctive constraint component 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
| 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.
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:targetNode ex:ValidInstance, ex:InvalidInstance ; 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
| 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.
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:targetNode ex:Bob ; 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 next example shows how sh:or can be used in a property constraint to state that the values of the given property ex:address may be either literals with datatype xsd:string or SHACL instances of the class ex:Address.
ex:PersonAddressShape a sh:Shape ; sh:targetClass ex:Person ; sh:property [ sh:predicate ex:address ; sh:or ( [ sh:datatype xsd:string ; ] [ sh:class ex:Address ; ] ) ] .
ex:Bob ex:address "123 Prinzengasse, Vaduz, Liechtenstein" .
The constraint components in this section can be used to represent complex restrictions based on applying shape definitions on value nodes.
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
| 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 ?failure
WHERE {
BIND (sh:hasShape($this, $shape, $shapesGraph) AS ?hasShape) .
BIND (!bound(?hasShape) AS ?failure) .
FILTER (?failure || !?hasShape) .
}
SELECT $this ?value ?failure
WHERE {
$this $PATH ?value .
BIND (sh:hasShape(?value, $shape, $shapesGraph) AS ?hasShape) .
BIND (!bound(?hasShape) AS ?failure) .
FILTER (?failure || !?hasShape) .
}
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. The handling of recursive shapes in SHACL is left to implementations. Some implementations MAY reject shapes graphs containing recursive shape definitions. Some implementations MAY report a failure if a recursion has been detected at validation time.
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
| 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 (SUM(?failed)>0 AS ?failure)
WHERE {
{
$this $PATH ?value .
BIND (sh:hasShape(?value, $qualifiedValueShape, $shapesGraph) AS ?hasShape) .
FILTER (!bound(?hasShape) || ?hasShape) .
}
BIND (IF(!bound(?hasShape), 1, 0) AS ?failed) .
}
GROUP BY $this
HAVING ((COUNT(?value) < $qualifiedMinCount) || (SUM(?failed) > 0))
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 (SUM(?failed)>0 AS ?failure)
WHERE {
{
$this $PATH ?value .
BIND (sh:hasShape(?value, $qualifiedValueShape, $shapesGraph) AS ?hasShape) .
FILTER (!bound(?hasShape) || ?hasShape) .
}
BIND (IF(!bound(?hasShape), 1, 0) AS ?failed) .
}
GROUP BY $this
HAVING ((COUNT(?value) > $qualifiedMaxCount) || (SUM(?failed) > 0))
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:targetNode 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 value nodes matched by each from further consideration. If every value node gets matched in this process, then the sh:partition constraint reports no violations. Otherwise, any value 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 value 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 value 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 value 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 value 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.
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 value 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
| 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 predicate of the triple as its sh:path, and the object of the triple as its sh:value.
SELECT $this (?predicate AS ?path) ?value
WHERE {
{
FILTER ($closed) .
}
$this ?predicate ?value .
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:targetNode ex:Alice, ex:Bob ; 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 property sh:hasValue can be used to verify that one of the value nodes is a given RDF node.
Constraint Component: sh:HasValueConstraintComponent
| Property | Value Type | Summary |
|---|---|---|
sh:hasValue |
any | A specific required value |
sh:hasValue is not among the value nodes.
SELECT $this
WHERE {
FILTER NOT EXISTS { $this $PATH $hasValue }
}
ex:StanfordGraduate a sh:Shape ; sh:targetNode 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
| Property | Value Type | Summary |
|---|---|---|
sh:in |
rdf:List |
Enumeration of allowed values |
sh:in must be well-formed rdf:Lists. 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.
ASK {
GRAPH $shapesGraph {
$in (rdf:rest*)/rdf:first $value .
}
}
ex:InExampleShape a sh:Shape ; sh:targetNode 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 target 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 target 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 targets 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 an rdfs:subClassOf 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 a 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:targetClass ex:Country ;
sh:sparql [
a sh:SPARQLConstraint ; # This triple is optional
sh:message "Values must be literals with German language tag." ;
sh:select """
SELECT $this (ex:germanLabel AS ?path) ?value
WHERE {
$this ex:germanLabel ?value .
FILTER (!isLiteral(?value) || !langMatches(lang(?value), "de"))
}
""" ;
] .
The target of the shape above includes all SHACL instances of ex:Country. For those 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:path ex:germanLabel ; sh:value "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,
ex:germanLabel as sh:path and the violating value as sh:value.
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 a failure 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 a failure.
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:path |
|
sh:value |
|
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:annotationVarNamesh: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:targetNode ex:ExampleRootResource ;
sh:sparql [
sh:resultAnnotation [
sh:annotationProperty ex:time ;
sh:annotationVarName "time"
] ;
sh:select """
SELECT $this (ex:property1 AS ?path) (?first AS ?value) ?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:path ex:property1 ; sh:value ex:ExampleIntermediateResource ; sh:message "The message." ; sh:sourceConstraint [ the blank node of the sh:sparql 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:parameter [
sh:predicate sh:pattern ;
sh:order 0 ;
] ;
sh:parameter [
sh:predicate sh:flags ;
sh:optional true ;
sh:order 1 ;
] ;
sh:validator shimpl:hasPattern .
shimpl:hasPattern
a sh:SPARQLAskValidator ;
sh:message "Value does not match pattern {$pattern}" ;
sh:ask "ASK { FILTER (!isBlank($value) && IF(bound($flags), regex(str($value), $pattern, $flags), regex(str($value), $pattern))) }" .
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.focusNode, path or value.
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.
For every supported context (i.e., property constraint or shape) the constraint component must declare a suitable validator. For a given constraint, a validator is selected from the constraint component using the following rules:
sh:shapeValidator, if present.sh:propertyValidator, if present.sh:validator.
If no suitable validator can be found, a SHACL processor ignores the constraint. The SHACL WG is seeking practical feedback on what the default behavior should be, and whether we should report violations in those cases.
SHACL includes two types of validators, based on SPARQL SELECT (for sh:shapeValidator and sh:propertyValidator) or SPARQL ASK queries (for sh:validator).
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. This type of validator can be used as values of sh:shapeValidator or sh:propertyValidator.
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: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 ?value
WHERE {
$this $PATH ?value .
FILTER (!isLiteral(?value) || !langMatches(lang(?value), $lang))
}
"""
] .
Once a constraint component has been defined, its parameters can be used as illustrated in the following example.
ex:LanguageExampleShape a sh:Shape ; sh:targetClass 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.
SELECT queries used in the context of property constraints must use a special variable named $PATH as a placeholder for the predicate or path used by the constraint. The only legal use of this variable is in the predicate position of a triple pattern. A query that uses the variable $PATH in any other position is invalid. Furthermore, any query that uses the variable $this in an aggregation is invalid.
A SPARQL-based SHACL validation engine executes the provided SPARQL query to produce validation results. In the context of property constraints, the engine will first substitute all occurrences of the variable $PATH with the provided property path derived from the value of either sh:predicate or sh:path in the constraint. The resulting SPARQL query is then evaluated 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 for both property constraints and shapes. SHACL provides an alternative, more compact syntax for validators based on ASK queries. This type of validators can be used as values of the property sh:validator.
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 resulting SELECT query can then be evaluated using the same algorithm as for SELECT-based validators. The engine drops the ASK keyword, leaving only the fraction between the outermost {...} pair. This block then substitutes ... in the template.
Template for sh:Shape context:
SELECT $this ?value
WHERE {
BIND ($this AS ?value) .
FILTER NOT EXISTS ...
}
Template for sh:PropertyConstraint context:
SELECT $this ?value
WHERE {
$this $PATH ?value .
FILTER NOT EXISTS ...
}
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.
ex:LanguageConstraintComponentUsingASK
a sh:ConstraintComponent ;
rdfs:label "Language constraint component" ;
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:validator 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 counterpart: 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.
A constraint component is triggered for every SHACL instance of a context that defines all non-optional parameters. TODO: This is unclear.
SHACL provides facilities to define custom targets. Similar to constraints, targets may either be SPARQL-based targets or
SPARQL-based target types in a higher-level vocabulary. All subjects of sh:target triples must be IRIs.
SPARQL-based targets must be SHACL instances of sh:SPARQLTarget, which is a SHACL subclass of sh:Target. The SPARQL queries linked to a target via sh:select must be of the query form SELECT. The SELECT queries must project to the result variable ?this. The resulting target 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 target that produces all persons born in the USA:
ex:USCitizenShape
a sh:Shape ;
sh:target [
a sh:SPARQLTarget ;
sh:select """
SELECT ?this
WHERE {
?this a ex:Person .
?this ex:bornIn ex:USA .
}
""" ;
] ;
...
The class sh:TargetType can be used to define high-level vocabularies for targets. Similar to constraint components, such targets take parameters that are interpreted when the target is evaluated. The class sh:SPARQLTargetType is an rdfs:subClassOf sh:TargetType for target 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 targets must not be blank nodes. All parameters of target types are expected to have sh:maxCount 1. Similar to constraint components, target types may also have values for the property sh:labelTemplate.
The following example defines a new SPARQL-based parameterizable target 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:PeopleBornInCountryTarget
a sh:SPARQLTargetType ;
rdfs:subClassOf sh:Target ;
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:target [
a ex:BornInCountryTarget ;
ex:country ex:USA ;
] ;
...
The set of target nodes produced by such a target 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 constraints to define such constraints.
Constraint Component: sh:DerivedValuesConstraintComponent
| 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:focusNode, the sh:predicate or sh:path as its sh:path, and the missing or extra value as its sh:value.
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:predicates.
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:
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. The WG is also awaiting input from the SPARQL Maintenance (EXISTS) Community Group.
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 targets 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.
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