Copyright © 2017W3C® (MIT,ERCIM,Keio,Beihang).W3Cliability,trademark anddocument use rules apply.
This document describes advanced features of the Shapes Constraint Language (SHACL) [shacl] including features to define custom targets, annotation properties, user-defined functions, node expressions and rules. While many of these features rely on SPARQL, they also define extension points that can be used by other implementation languages.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of currentW3C publications and the latest revision of this technical report can be found in theW3C technical reports index at https://www.w3.org/TR/.
Future revisions of this document may be produced by a SHACLW3C Community Group.
This document was published by theRDF Data Shapes Working Group as a First Public Working Group Note. Comments regarding this document are welcome. Please send them topublic-rdf-shapes@w3.org (subscribe,archives).
Publication as a Working Group Note does not imply endorsement by theW3C 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 the5 February 2004W3C Patent Policy.W3C maintains apublic 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of theW3C Patent Policy.
This document is governed by the1 March 2017W3C Process Document.
Some examples in this document use Turtle [turtle]. The reader is expected to be familiar with SHACL [shacl] and SPARQL [sparql11-query].
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# |
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 a shapes graph<s> <p> <o> .
// This box contains JavaScript code
# This box represents a data graph.
# This box represents an output results graph
Formal definitions appear in blue boxes:
# This box contains textual definitions.
Grey boxes such as this include syntax rules that apply to the shapes graph.
true denotes the RDF term"true"^^xsd:boolean.false denotes the RDF term"false"^^xsd:boolean.
The terminology used throughout this document is consistent with the definitions in the main SHACL [shacl] specification, which references terms from RDF [rdf11-concepts]. This includes the termsbinding,blank node,conformance,constraint,constraint component,data graph,datatype,failure,focus node,RDF graph,ill-formed,IRI,literal,local name,member,node,node shape,object,parameter,pre-binding,predicate,property path,property shape,RDF term,SHACL instance,SHACL list,SHACL subclass,shape,shapes graph,solution,subject,target,triple,validation,validation report,validation result,validator,value,value node.
The SHACL specification [shacl] is divided into SHACL Core and SHACL-SPARQL:
This document extends the functionality of SHACL by defining RDF vocabularies to cover the following features:
Taken together or individually, these features greatly extend the application scenarios of SHACL, and SHACL-SPARQL in particular.
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 wordsMUST andSHOULD are to be interpreted as described in [RFC2119].
Some of the features presented here (includingnode expressions,expression constraints andtriple rules) do not necessarily require a SPARQL processor and could be used as extensions of pure SHACL Core implementations. Other features (includingcustom target types,SHACL functions, and generalSHACL rules) define extension mechanisms that can also be used with other languages than SPARQL, such as JavaScript (as defined by the SHACL-JS document [shacl-js]).
A SHACL-SPARQL processor that also supports all features defined in this document and is called anAdvanced SHACL-SPARQL processor.
In general,targets define a mechanism that is used by SHACL engines to determine thefocus nodes that should be validated against a givenshape. SHACL Core [shacl] defines a fixed set of Coretargets by means of properties such assh:targetClass. These Core targets were designed to cover a large number of use cases while retaining a simple declarative data model. However, in some use cases, these Core targets are not sufficient. For example it is impossible to state that a shape should apply only to a subset of instances of a class, e.g. persons born in the USA. Neither is it possible to state that a shape should apply to all subjects in a graph, or to nodes selected by completely different, application-specific mechanisms.
This section defines richer mechanisms to definetargets, calledcustom targets. Custom targets are thevalues of the propertysh:target in theshapes graph. The propertysh:target has a similar status as, for example,sh:targetClass, and allsubjects ofsh:targettriples are alsoshapes.
Thevalues ofsh:target at ashape areIRIs orblank nodes.
A SHACL engine that supportscustom targets uses thevalues of thecustom target node to compute the target nodes for the associatedshape. The algorithm that is used for this computation depends on therdf:type of thecustom target. The following sub-sections define two such algorithms:
However, other types of targets can be supported by other extension languages such as JavaScript. The classsh:Target is the recommended base class for such extensions.
The behavior of a SHACL engine that is unable to handle a givencustom target is left undefined. SHACL Core processors do not even need to be aware of the existence of thesh:target property. Engines that are aware of this property and cannot handle a givencustom targetSHOULD at least report a warning.
Custom targets that areSHACL instances ofsh:SPARQLTarget are calledSPARQL-based targets.
SPARQL-based targets have exactly onevalue for the propertysh:select.SPARQL-based targets may havevalues for the propertysh:prefixesand these values areIRIs orblank nodes.Using thevalues ofsh:prefixes as defined by5.2.1 Prefix Declarations for SPARQL Queries,thevalues ofsh:select must be valid SPARQL 1.1 SELECT queries with a single result variablethis.SPARQL-based targets have at most onevalue for the propertysh:ask.
The following example declares a well-formed SPARQL-based target that produces all persons born in the USA:
ex:sh:declare [sh:prefix "ex" ;sh:namespace <http://example.com/ns#> ;] .ex:USCitizenShapea sh:NodeShape ;sh:target [a sh:SPARQLTarget ;sh:prefixes ex: ;sh:select """SELECT ?thisWHERE {?this a ex:Person .?this ex:bornIn ex:USA .}""" ;] ;...Q be the SPARQL SELECT query derived from thevalues ofsh:select andsh:prefixes of theSPARQL-based targetT. Thetarget nodes ofT are thebindings of the variablethis returned byQ against thedata graph. While the SELECT queries can be used to identify allfocus nodes for a givenshape, SHACL processors sometimes also need to compute the inverse direction and find allshapes for which a givennode needs to be validated against. For this reason, the following semantic restriction is recommended for SELECT queries used in SPARQL-based targets. Informally, SHACL Full processors should be able to derive an equivalent ASK query from the SELECT query,pre-bind the potentialfocus node, and check whether the potential focus node needs to be validated against theshape that has the given target. Formally, letA be a SPARQL ASK query that is produced by replacing theSelectClause withASK in the outermost SELECT query. Letrs be the set of RDF terms returned asbindings for the variablethis in thesolutions of the SELECT query. ThenA returnstrue if and only if the variablethis ispre-bound with a value fromrs. If the SELECT query of a SPARQL-based target does not fulfill this requirement, it needs to be accompanied by a SPARQL ASK query as the value forsh:ask. A SHACL engine can then determine whether a givenshape applies to a givennode by executing the ASK query with the variablethispre-bound to thenode. If the ASK query evaluates totrue then thenode is in the target of theshape.
In some cases it would be too repetitive to declare SPARQL-based targets with similar SPARQL queries that only differ in a few aspects. SHACL-SPARQL defines a mechanism for user-definedconstraint components, allowing users to reuse the same SPARQL query in a parameterized form. The SPARQL-based target types introduced in this section follow a similar design.
The classsh:TargetType can be used to declare high-level vocabularies for targets in ashapes graph. The classsh:SPARQLTargetType is declared asrdfs:subClassOf sh:TargetType forSPARQL-based target types. Other extension languages may define alternative execution instructions for target types with the same IRI, making them potentially more platform independent than pureSPARQL-based targets. Instances of the classsh:SPARQLTargetType specify a SPARQL SELECT query via the propertysh:select, and this query has to fulfill the same syntactic and semantic rules asSPARQL-based targets.
Similar to SPARQL-basedconstraint components, such targets takeparameters and the parameter values becomepre-bound variables in the associated SPARQL queries. The parameter values of such targets cannot not be blank nodes, and the same target cannot have more than one value per parameter. A target that lacks avalue for a non-optional parameter is ignored, producing no target nodes. Similar to SPARQL-basedconstraint components, target types may also have values for the propertysh:labelTemplate.
The following example declares a new SPARQL-based target type that takes one parameterex:country that gets mapped into the variablecountry in the corresponding SPARQL query to determine the resulting target nodes.
ex:PeopleBornInCountryTargeta sh:SPARQLTargetType ;rdfs:subClassOf sh:Target ;sh:labelTemplate "All persons born in {$country}" ;sh:parameter [sh:path ex:country ;sh:description "The country that the focus nodes are 'born' in." ;sh:class ex:Country ;sh:nodeKind sh:IRI ;] ;sh:prefixes ex: ;sh:select """SELECT ?thisWHERE {?this a ex:Person .?this ex:bornIn $country .}""" .Once such a target type has been defined in ashapes graph, it can be used by multiple shapes:
ex:GermanCitizenShapea sh:NodeShape ;sh:target [a ex:BornInCountryTarget ;ex:country ex:Germany ;] ;...ex:USCitizenShapea sh:NodeShape ;sh:target [a ex:BornInCountryTarget ;ex:country ex:USA ;] ;...
The set of focus nodes produced by such a target type consists of all bindings of the variablethis in the result set, when the SPARQL SELECT query has been executed with thepre-bound parameter values.
This section extends the generalmechanism from SHACL-SPARQL [shacl] to producevalidation reports as a result of thevalidation.
Implementations that support this feature make it possible to inject so-calledannotation properties into the validation result nodes created for eachsolution produced by the SELECT queries of a SPARQL-basedconstraint orconstraint component. Any such annotation property needs to be declared via avalue ofsh:resultAnnotation at thesubject of thesh:select orsh:asktriple.
Thevalues ofsh:resultAnnotation arecalledresult annotations and are eitherIRIs orblank nodes.
Result annotations have the following properties:
| Property | Summary and Syntax Rules |
|---|---|
sh:annotationProperty | The property that shall be set.Eachresult annotation has exactly onevaluefor the propertysh:annotationProperty and this value is anIRI. |
sh:annotationVarName | The name of the SPARQL variable to take the annotation values from.Eachresult annotation has at most 1valuefor the propertysh:annotationVarName and thisvalue isliteral withdatatypexsd:string. |
sh:annotationValue | ConstantRDF terms that shall be used as default values. |
For eachsolution of a SELECT result set, a SHACL processor that supports annotations walks through the declared result annotations. The mapping from result annotations to SPARQL variables uses the following rules:
sh:annotationVarNamesh:annotationProperty as the variable name If a variable name could be determined, then the SHACL processor copies thebinding for the given variable as a value for the property specified usingsh:annotationProperty into the validation result that is being produced for the currentsolution. If the variable has nobinding in the result setsolution, then thevalues ofsh:annotationValue is used, if present.
Here is an example illustrating the use of result annotations.
ex:AnnotationExamplea sh:NodeShape ;sh:targetNode ex:ExampleResource ;sh:sparql [ # _:b1sh:resultAnnotation [sh:annotationProperty ex:time ;sh:annotationVarName "time" ;] ;sh:select """SELECT $this ?message ?timeWHERE {BIND (CONCAT("The ", "message.") AS ?message) .BIND (NOW() AS ?time) .}""" ;] .Validation produces the following validation report:
[a sh:ValidationReport ;sh:conforms false ;sh:result [a sh:ValidationResult ;sh:focusNode ex:ExampleResource ;sh:resultMessage "The message." ;sh:resultSeverity sh:Violation ;sh:sourceConstraint _:b1 ;sh:sourceConstraintComponent sh:SPARQLConstraintComponent ;sh:sourceShape ex:AnnotationExample ;ex:time "2015-03-27T10:58:00"^^xsd:dateTime ; # Example]] .
SHACL functions declare operations that produce anRDF term based on zero or moreparameters and adata graph. Each SHACL function has anIRI. The actual execution logic (or algorithm) of a SHACL function can be declared in a variety of execution languages. This document defines one specific kind of SHACL functions, theSPARQL-based functions. JavaScript-based Functions are defined in the separate SHACL-JS document [shacl-js]. The same functionIRI can potentially be executed on a multitude of platforms, if it declares execution instructions for these platforms.
SHACL functions can be called within FILTER or BIND clauses and similar features of SPARQL queries. SHACL functions can also be used declaratively in frameworks such as the SHACLnode expressions which are used inSHACL rules. In those scenarios they may be used to perform data transformations such as string concatenation.
The following example illustrates the declaration of a SHACL function based on a simple mathematical SPARQL query.
ex:multiplya sh:SPARQLFunction ;rdfs:comment "Multiplies its two arguments $op1 and $op2." ;sh:parameter [sh:path ex:op1 ;sh:datatype xsd:integer ;sh:description "The first operand" ;] ;sh:parameter [sh:path 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 that support SHACL functions install a new SPARQL function based on the SPARQL 1.1Extensible Value Testing mechanism. Such engines are then able to handle expressions such asex:multiply(7, 8), producing56, as illustrated in the following SPARQL query.
SELECT ?subject ?areaWHERE {?subject ex:width ?width .?subject ex:height ?height .BIND (ex:multiply(?width, ?height) AS ?area) .}The following sections introduce the general properties that such functions may have, before the specific characteristics ofSPARQL-based functions are defined.
The parameters of aSHACL function are declared using the propertysh:parameter. This corresponds closely to theparameterdeclarations of SPARQL-based constraint components, and the same syntax rules apply.
Parameters are ordered, corresponding to the notation of function calls in SPARQL such asex:exampleFunction(?param1, ?param2). The ordering of function parameters is determined as follows:
sh:order then all of them are ordered in ascending order by the parameters' numericvalues ofsh:order, using0 as default value if unspecified.sh:order then all of them are ordered in ascending order of thelocal names of their declaredsh:path values. Each parameter may have its propertysh:optional set totrue to indicate that the parameter is not mandatory. If a function gets invoked without all its mandatory parameters then it returns no result node (an error in SPARQL, producing unbound in a BIND statement).
A function may declare a singlereturn type viash:returnType.
A function has at most onevalue forsh:returnType.The values ofsh:returnType areIRIs.
Thereturn type may serve for documentation purposes only. However, in some execution languages such as JavaScript, the declaredsh:returnType may inform a processor how to cast a native value into anRDF term.
SHACL instances ofsh:SPARQLFunction that areIRIs in ashapes graph are calledSPARQL-based functions.
SPARQL-based functions have exactly onevalue for eithersh:ask orsh:select.Thevalues of these properties are strings that can be parsed into SPARQL queries of type ASK (forsh:ask)or SELECT (forsh:select) using the SHACL-SPARQLprefix declaration mechanism.SELECT queries return exactly one result variable and do not use theSELECT * syntax.
When the function is executed, the SPARQL processor needs topre-bind variables based on the provided arguments of the function call. In theSHACL functions example above, the value for the parameter declared asex:op1 ispre-bound to the SPARQL variable$op1, etc. For ASK queries, the function's return value is the result of the ASK query execution, i.e.true orfalse. For SELECT queries, the function's return value is thebinding of the (single) result variable of the firstsolution in the result set. Since all other bindings will be ignored, such SELECT queries should only return at most onesolution. If the result variable is unbound, then the function generates aSPARQL error.
This section defines a feature callednode expressions. Node expressions are declared as RDF nodes in ashapes graph and instruct a SHACL engine how to compute a set ofnodes for a givenfocus node. Eachnode expression has one of the following types, each of which is defined together with its evaluation semantics in the following sub-sections.
| Node Expression Type | Syntax (Informative) | Summary |
|---|---|---|
| Focus Node Expression | sh:this | The set consisting of the currentfocus node. |
| Constant Term Expression | AnyIRI orliteral exceptsh:this | The set consisting of the giventerm. |
| Function Expression | Blank node with a list-valued triple | The results of evaluating a givenSHACL Function. |
| Path Expression | Blank node withsh:path | Thevalues of a givenproperty path. |
| Filter Shape Expression | Blank node withsh:filterShape andsh:nodes | The sub-set of the input nodes that conform to a givenshape. |
| Intersection Expression | Blank node withsh:intersection | The intersection of two or more input sets. |
| Union Expression | Blank node withsh:union | The union set of two or more input sets. |
The basic idea of these expressions is that they can be used to derive a set of RDF nodes from a givenfocus node, for example the set of all values of a given property of the focus node. Some of these expressions can be nested, i.e. they use the output of another expression as their input, leading to evaluation chains and trees.
The following example declares anode expression that produces the display labels of all values of the propertyex:customer thatconform to a givenshapeex:GoodCustomerShape. The assumption here is that there is aSHACL functionex:displayLabel which declares a single parameter.
[ex:displayLabel ( [sh:filterShape ex:GoodCustomerShape ;sh:nodes [ sh:path ex:customer ] ;] )] .
To evaluate this example, an engine gets allvalues ofex:customer of thefocus node, then filters them according to theshapeex:GoodCustomerShape and repeatedly calls theSHACL functionex:displayLabel with all values that pass the filter shape as arguments.
Important use cases of such expressions areexpression constraints andSHACL rules, yet the basic functionality and vocabulary may find many other application areas.
Each of the following sub-sections defines a node expression type with its syntax rules and evaluation semantics based on a mapping operationEval($expr, $this) where the first argument$expr is the given expression,$this is the currentfocus node and which produces a set of RDF nodes.
Anode expression cannot recursively have itselfas a "nested" node expression, e.g. asvalue ofsh:nodes.
TheIRIsh:this is the (only) node declaring afocus node expression.
Anyliteral orIRI exceptsh:this declares aconstant term expression.
Afilter shape expression is ablank nodewith exactly onevalue forsh:filterShape (which is a well-formedshape)and exactly onevalue forsh:nodes (which is a well-formednode expression).
$expr withS being theshape that is thevalue ofsh:filterShape andN being thenode expression that is thevalue ofsh:nodes,Eval($expr, $this) produces the set of nodes for eachnoden produced by evaluatingN wherenconforms toS.Afunction expression is ablank nodethat does not fulfill any of the syntax rules of the other node expression types and whichis thesubject of exactly onetripleT where theobject is a well-formedSHACL list,and eachmember of that list is a well-formednode expression.
$expr,Eval($expr, $this) produces the set ofnodes returned by evaluating theSHACL function specified aspredicate of the tripleT mentioned above. The arguments of the function call(s) are based on the results of thenode expressions listed in theobject list ofT so that the first listmember is used for the first argument, etc. This is done for all combinations ofnodes produced by thenode expression. If one of thenode expressions produces the empty set and the corresponding functionparameter is non-optional, then the result is the empty set.As illustrated in the following example,function expressions are comparable to SPARQL BIND clauses.
[ ex:concat ( [ sh:path ex:firstName ][ sh:path ex:lastName ] )] . | {$this ex:firstName ?a .$this ex:lastName ?b .BIND (ex:concat(?a, ?b) AS ?result) .} |
Apath expression is ablank nodewith exactly onevalue of the propertysh:path (which are well-formedproperty paths)and at most onevalue forsh:nodes (which is a well-formednode expression).
$expr that has the property pathP as itsvalue forsh:path and thenode expressionN as itsvalue forsh:nodes (defaulting to thefocus node expression if absent),Eval($expr, $this) produces the set ofvalues of all nodes produced byN for theproperty pathP.As illustrated in the following examples,path expressions are comparable to SPARQL basic graph patterns.
[ sh:path ex:firstName ] .[ sh:nodes ex:children ; sh:path rdfs:label ;] . | { $this ex:firstName ?result . }{ $this ex:children ?a . ?a rdfs:label ?result .} |
Anintersection expression is ablank nodewith exactly onevalue for the propertysh:intersection which is a well-formedSHACL listwith at least twomembers (which are well-formed node expressions).
$expr that has the listL as itsvalue forsh:intersection,Eval($expr, $this) produces the set ofnodes that are in all of the result sets produced by themembers ofL.Aunion expression is ablank nodewith exactly onevalue for the propertysh:union which is a well-formedSHACL listwith at least twomembers (which are well-formed node expressions).
$expr that has the listL as itsvalue forsh:union,Eval($expr, $this) produces the set ofnodes that are in any of the result sets produced by all of themembers ofL.As illustrated in the following example,union expressions are comparable to SPARQL UNION clauses.
[ sh:union ([ sh:path ex:firstName ][ sh:path ex:givenName ] )] . | {$this ex:firstName ?result . } UNION {$this ex:givenName ?result . } |
Based onnode expressions, this section introduces aconstraint component calledexpression constraints. Expression constraints can be used in anyshape to declare the condition that thenode expression specified viash:expression hastrue as its (only) result. In the evaluation of these node expressions is repeated for allvalue nodes of theshape as thefocus node.
Constraint Component IRI:sh:ExpressionConstraintComponent
| Property | Summary and Syntax Rules |
|---|---|
sh:expression | Thenode expression that must returntrue.Thevalues ofsh:expression at ashape must be well-formednode expressions. |
v whereEval(v, $expression) returns a node set that is not equal to{ true } there is avalidation result that hasv as itssh:value and$expression as itssh:sourceConstraint. If the$expression hasvalues forsh:message in theshapes graph then thesevalues become the (only) values forsh:resultMessage in thevalidation result.The remainder of this section is informative.
The following example assumes that there areSHACL functionsex:concat,ex:strlen andex:lessThan and uses them to verify that the combined string length ofex:firstName andex:lastName is less than 30.
ex:FilterExampleShapea sh:NodeShape ;sh:expression [ex:lessThan ( [ ex:strlen ( [ ex:concat ( [ sh:path ex:firstName] [ sh:path ex:lastName ] ) ] ) ]30 );] .
SHACL defines an RDF vocabulary to describeshapes - collections ofconstraints that apply to a set of nodes. Shapes can be associated with nodes using a flexibletarget mechanism, e.g. for all instances of a class. One focus area of SHACL is data validation. However, the same principles of describing data patterns in shapes can also be exploited for other purposes.SHACL rules build on SHACL to form a light-weight RDF vocabulary for the exchange ofrules that can be used to deriveinferred RDFtriples from existingassertedtriples.
TheSHACL rules feature defined in this section includes a general framework using the properties such assh:rule andsh:condition, plus an extension mechanism for specificrule types. This document defines two such rule types:Triple rules andSPARQL rules. Other documents, including SHACL JavaScript Extensions [shacl-js], can define additional types of rules.
This section is non-normative.
The following example illustrates the use of atriple rule that adds anrdf:typetriple so that thoseSHACL instances ofex:Rectangle where theex:width equals theex:height are also marked to be instances ofex:Square. The rule applies only to well-formed rectangles thatconform to theex:Rectangleshape, e.g. by having exactly one width and height, both integers.
ex:Rectanglea rdfs:Class, sh:NodeShape ;rdfs:label "Rectangle" ;sh:property [sh:path ex:height ;sh:datatype xsd:integer ;sh:maxCount 1 ;sh:minCount 1 ;sh:name "height" ;] ;sh:property [sh:path ex:width ;sh:datatype xsd:integer ;sh:maxCount 1 ;sh:minCount 1 ;sh:name "width" ;] ;sh:rule [a sh:TripleRule ;sh:subject sh:this ;sh:predicate rdf:type ;sh:object ex:Square ;sh:condition ex:Rectangle ;sh:condition [sh:property [sh:path ex:width ;sh:equals ex:height ;] ;] ;] .
ex:InvalidRectanglea ex:Rectangle .ex:NonSquareRectanglea ex:Rectangle ;ex:height 2 ;ex:width 3 .ex:SquareRectanglea ex:Rectangle ;ex:height 4 ;ex:width 4 .
For thedata graph above, a SHACL rules engine will produce the following inferred triples:
ex:SquareRectangle rdf:type ex:Square .
No inferences will be made forex:NonSquareRectangle because its width is not equal to its height. No inferences will be made forex:InvalidRectangle because although it has equal width and height (namely none), it does not pass thesh:condition of being a well-formed rectangle.
The following example illustrates a simple use case of aSPARQL rule that applies to all instances of the classex:Rectangle and computes the values of theex:area property by multiplying the rectangle's width and height:
ex:RectangleShapea sh:NodeShape ;sh:targetClass ex:Rectangle ;sh:property [sh:path ex:width ;sh:datatype xsd:integer ;sh:minCount 1 ;sh:maxCount 1 ;] ;sh:property [sh:path ex:height ;sh:datatype xsd:integer ;sh:minCount 1 ;sh:maxCount 1 ;] .ex:RectangleRulesShapea sh:NodeShape ;sh:targetClass ex:Rectangle ;sh:rule [a sh:SPARQLRule ;sh:prefixes ex: ;sh:construct """CONSTRUCT {$this ex:area ?area .}WHERE {$this ex:width ?width .$this ex:height ?height .BIND (?width * ?height AS ?area) .}""" ;sh:condition ex:RectangleShape ; # Rule only applies to Rectangles that conform to ex:RectangleShape] ;. An engine that is capable of executing such rules uses thetarget statements associated with theshapes in theshapes graph to determine which rules need to be executed on which target nodes. For those target nodes thatconform to anycondition shapes, it executes the provided CONSTRUCT queries to produce the inferred triples. During the execution of the query, the variablethis has the currentfocus node aspre-bound variable. For the followingdata graph, thetriples below would be produced.
ex:ExampleRectanglea ex:Rectangle ;ex:width 7 ;ex:height 8 .ex:InvalidRectangle # Lacks a value for ex:height, so sh:condition is not meta ex:Rectangle ;ex:width 7 .
Inferred triples:
ex:ExampleRectangle ex:area 56 .
The following variation produces the same results as theSPARQL rule, but uses aTriple rule. While not as expressive as CONSTRUCT-based rules,Triple rules are more declarative and may be executed on platforms that do not support SPARQL.
ex:RectangleRulesShapea sh:NodeShape ;sh:targetClass ex:Rectangle ;sh:rule [a sh:TripleRule ;sh:subject sh:this ;sh:predicate ex:area ; # Computes the values of the ex:area property at the focus nodessh:object [ex:multiply ( [ sh:path ex:width ] [ sh:path ex:height ] ) ;] ;sh:condition ex:RectangleShape ; # Rule only applies to Rectangles that conform to ex:RectangleShape] .
Thevalues of the propertysh:rule at ashape are calledSHACL rules. SHACL has a flexible design in which multiple types of rules can be supported, includingTriple rules andSPARQL rules. Eachrule type is identified by anIRI that is used asrdf:type of rules. Each rule type also definesexecution instructions that can be implemented by rule engines.
EachSHACL rule has at least onerdf:type which is aIRI.
Rules can have multiple types, e.g. to provide instructions that work either in SPARQL or JavaScript, depending on the capabilities of the engine. The creator of such rules needs to make sure that such rules have consistent semantics. RuleR hasrule typeT ifR is aSHACL instance ofT.
All rules may have the properties defined in the rest of this section.
Arule may have values for the propertysh:condition to specifyshapes that thefocus nodes must conform to before the rule gets executed.
Thevalues ofsh:condition at arule must be well-formedshapes.
Rules and shapes may specify its relativeexecution order as defined in this section.
Eachrule orshape may have at most onevalue for thepropertysh:order.The values ofsh:order atrules andshapesareliterals with anumeric datatype such asxsd:decimal.
If unspecified, then the defaultexecution order is0. These values are used by arules engine to determine the order ofrules. When therules associated with ashape are executed,rules with larger values will be executed after those with smaller values.
ex:RuleOrderExampleShapea sh:NodeShape ;sh:targetClass ex:Person ;sh:rule [a sh:SPARQLRule ;rdfs:label "Infer uncles, i.e. male siblings of the parents of $this" ;sh:prefixes ex: ;sh:order 1 ; # Will be evaluated before 2sh:construct """CONSTRUCT {$this ex:uncle ?uncle .}WHERE {$this ex:parent ?parent .?parent ex:sibling ?uncle .?uncle ex:gender ex:male .}"""] ;sh:rule [a sh:SPARQLRule ;rdfs:label "Infer cousins, i.e. the children of the uncles" ;sh:prefixes ex: ;sh:order 2 ;sh:construct """CONSTRUCT {$this ex:cousin ?cousin .}WHERE {$this ex:uncle ?uncle .?cousin ex:parent ?uncle .}"""] . Rules may bedeactivated by settingsh:deactivated totrue. Deactivated rules are ignored by the rules engine.
Eachrule may have at most onevalue for thepropertysh:deactivated.Thevalues ofsh:deactivated are eitherof thexsd:boolean literalstrue orfalse.
SHACL defines the propertysh:entailment to link ashapes graph withentailment regimes. TheIRIsh:Rules represents theSHACL rules entailment regime. In the following example, the shapes graph indicates to a SHACL validation engine that the SHACL rules inside of theshapes graph need to be executed prior to starting the validation.
<http://example.org/my-shapes>a owl:Ontology ;sh:entailment sh:Rules .
Following the general policy for SHACL, validation engines that donot support theSHACL rules entailment regimeMUST signal afailure if thistriple is present. Validation engines that do support theSHACL rules entailment regime execute the rules following therules execution instructions prior to performing the actual validation.
ASHACL rules engine is a computer procedure that takes as input adata graph and ashapes graph and is capable of addingtriples to thedata graph. The newtriples that are produced by a rules engine are called theinferred triples.
Note that, from a logical perspective, thedata graph will bemodified iftriples get inferred. This means that rules can trigger after other triples have been inferred. However, in cases where the original data should not be modified, implementations may construct a logicaldata graph that has the original data as one subgraph and a dedicated inferences graph as another subgraph, and where the inferred triples get added to the inferences graph only.
In order to count as a SHACL rules engine, an implementation must be capable ofinferringtriples according to the following procedure (given in pseudo-code), or a different algorithm as long as the result is the same as specified. Note that this algorithm only covers a single "iteration" over all rules, without prescribing the behavior if the same rule needs to be applied multiple times after other rules have fired. The latter is left to future work.
for eachshapeSin theshapes graph, ordered byexecution order {for each non-deactivatedruleRin theshape, ordered byexecution order {for eachtarget nodeTofSthatconforms to allconditions ofR{executeRusingTasfocus node following theexecution instructions of itsrule types}}}
Thetriples that are inferred by arule do notimmediately become part of thedata graph, i.e. thetriples produced by onerule can not always be queried by otherrules. These policies reduce the likelihood of race conditions and better support parallel execution.
If arules engine is not able to execute a givenrule because it does not support any of therule types of therule, then it reports afailure.
At no time are inferred triples visible to theshapes graph, i.e. it is impossible for rules to modify the definitions of rules or shapes.
This section defines arule type calledtriple rules, identified by theIRIsh:TripleRule.Triple rules have the following properties:
| Property | Summary and Syntax Rules |
|---|---|
sh:subject | Thenode expression used to compute thesubjects of thetriples.Eachtriple rule must have exactly onevalue of the propertysh:subject (which must be a well-formednode expression). |
sh:predicate | Thenode expression used to compute thepredicates of thetriples.Eachtriple rule must have exactly onevalue of the propertysh:predicate (which must be a well-formednode expression). |
sh:object | Thenode expression used to compute theobjects of thetriples.Eachtriple rule must have exactly onevalue of the propertysh:object (which must be a well-formednode expression). |
S,P andO be the sets ofnodes produced by evaluating thenode expressions that are the values ofsh:subject,sh:predicate andsh:object respectively at thetriple rule. For each combination of memberss ofS,p ofP ando ofO,infer atriple withsubjects,predicatep andobjecto. This section defines arule type calledSPARQL rules, identified by theIRIsh:SPARQLRule.SPARQL rules have the following properties:
| Property | Summary and Syntax Rules |
|---|---|
sh:construct | The SPARQL CONSTRUCT query.SPARQL rules must have exactly onevalue for the propertysh:construct.The values ofsh:constructareliterals with datatypexsd:string. |
sh:prefixes | The prefixes to use to turn thesh:construct into a SPARQL query.SPARQL rules may use the propertysh:prefixes to declare a dependency on prefixes based on the mechanism defined inPrefix Declarations for SPARQL Queries from the SHACL specification [shacl]. This mechanism allows users to abbreviate URIs in thesh:construct strings. |
Q be the SPARQL CONSTRUCT query derived from the values of the propertiessh:construct andsh:prefixes of theSPARQL rule in theshapes graph. For eachfocus node, execute the queryQpre-binding the variablethis to thefocus node, andinfer the constructedtriples.This section enumerates all normative syntax rules from this document. This section is automatically generated from other parts of this spec and hyperlinks are provided back into the prose if the context of the rule in unclear. Nodes that violate these rules in a shapes graph are ill-formed.
| Syntax Rule Id | Syntax Rule Text |
|---|---|
| target-nodeKind | Thevalues ofsh:target at ashape areIRIs orblank nodes. |
| SPARQLTarget-select-count | SPARQL-based targets have exactly onevalue for the propertysh:select. |
| SPARQLTarget-prefixes-nodeKind | SPARQL-based targets may havevalues for the propertysh:prefixes and these values areIRIs orblank nodes. |
| SPARQLTarget-select-sparql | Using thevalues ofsh:prefixes as defined by5.2.1 Prefix Declarations for SPARQL Queries, thevalues ofsh:select must be valid SPARQL 1.1 SELECT queries with a single result variablethis. |
| SPARQLTarget-ask-count | SPARQL-based targets have at most onevalue for the propertysh:ask. |
| resultAnnotation-nodeKind | Thevalues ofsh:resultAnnotation are calledresult annotations and are eitherIRIs orblank nodes |
| annotationProperty | Eachresult annotation has exactly onevalue for the propertysh:annotationProperty and this value is anIRI. |
| annotationVarName | Eachresult annotation has at most 1value for the propertysh:annotationVarName and thisvalue isliteral withdatatypexsd:string. |
| returnType-maxCount | A function has at most onevalue forsh:returnType. |
| returnType-nodeKind | The values ofsh:returnType areIRIs. |
| SPARQLFunction-query | SPARQL-based functions have exactly onevalue for eithersh:ask orsh:select. Thevalues of these properties are strings that can be parsed into SPARQL queries of type ASK (forsh:ask) or SELECT (forsh:select) using the SHACL-SPARQLprefix declaration mechanism. SELECT queries return exactly one result variable and do not use theSELECT * syntax. |
| node-expressions-recursion | Anode expression cannot recursively have itself as a "nested" node expression, e.g. asvalue ofsh:nodes. |
| FilterShapeExpression | Afilter shape expression is ablank node with exactly onevalue forsh:filterShape (which is a well-formedshape) and exactly onevalue forsh:nodes (which is a well-formednode expression). |
| FunctionExpression | Afunction expression is ablank node that does not fulfill any of the syntax rules of the other node expression types and which is thesubject of exactly onetripleT where theobject is a well-formedSHACL list, and eachmember of that list is a well-formednode expression. |
| PathExpression | Apath expression is ablank node with exactly onevalue of the propertysh:path (which are well-formedproperty paths) and at most onevalue forsh:nodes (which is a well-formednode expression). |
| intersection | Anintersection expression is ablank node with exactly onevalue for the propertysh:intersection which is a well-formedSHACL list with at least twomembers (which are well-formed node expressions). |
| union | Aunion expression is ablank node with exactly onevalue for the propertysh:union which is a well-formedSHACL list with at least twomembers (which are well-formed node expressions). |
| expression-scope | Thevalues ofsh:expression at ashape must be well-formednode expressions. |
| rule-type | EachSHACL rule has at least onerdf:type which is aIRI. |
| condition-node | Thevalues ofsh:condition at arule must be well-formedshapes. |
| rule-order-maxCount | Eachrule orshape may have at most onevalue for the propertysh:order. |
| rule-order-datatype | The values ofsh:order atrules andshapes areliterals with anumeric datatype such asxsd:decimal. |
| deactivated-maxCount | Eachrule may have at most onevalue for the propertysh:deactivated. |
| deactivated-in | Thevalues ofsh:deactivated are either of thexsd:boolean literalstrue orfalse. |
| TripleRule-subject | Eachtriple rule must have exactly onevalue of the propertysh:subject (which must be a well-formednode expression). |
| TripleRule-predicate | Eachtriple rule must have exactly onevalue of the propertysh:predicate (which must be a well-formednode expression). |
| TripleRule-object | Eachtriple rule must have exactly onevalue of the propertysh:object (which must be a well-formednode expression). |
| construct-count | SPARQL rules must have exactly onevalue for the propertysh:construct. |
| construct-datatype | The values ofsh:construct areliterals with datatypexsd:string. |
This section is non-normative.
The features defined in this document share certain security and privacy considerations with thosementioned in [shacl]. The general advice is for users to only use trusted and controlled shape graphs.
This section is non-normative.
Many people contributed to this document, including members of the RDF Data Shapes Working Group. The sections3.Custom Targets,4.Annotation Properties and5.SHACL Functions had been part of earlier drafts of the main SHACL specification [shacl] but were moved out in part due to time constraints in the Working Group. Dimitris Kontokostas was the main contributor to the4.Annotation Properties section.