From efb154b93966efe8339ec0efca10b5b63f6aa665 Mon Sep 17 00:00:00 2001 From: Simon Steyskal Date: Fri, 15 Aug 2025 08:22:28 +0200 Subject: [PATCH 1/9] feat: :sparkles: automatically fetch sparql functions and create sections dynamically --- shacl12-node-expr/index.html | 4977 ++++++++++++++++++---------------- 1 file changed, 2703 insertions(+), 2274 deletions(-) diff --git a/shacl12-node-expr/index.html b/shacl12-node-expr/index.html index 0200737a..1c48ef39 100644 --- a/shacl12-node-expr/index.html +++ b/shacl12-node-expr/index.html @@ -1,2335 +1,2762 @@ - - - SHACL 1.2 Node Expressions - - + - - + } + + /* example tab selection */ + .ds-selector-tabs .selectors { + padding: 0; + border-bottom: 1px solid #ccc; + height: 28px; + } + + .ds-selector-tabs .selectors button { + display: inline-block; + min-width: 54px; + text-align: center; + font-size: 11px; + font-weight: bold; + height: 27px; + padding: 0 8px; + line-height: 27px; + transition: all, 0.218s; + border-top-right-radius: 2px; + border-top-left-radius: 2px; + color: #666; + border: 1px solid transparent; + } + + .ds-selector-tabs .selectors button:first-child { + margin-left: 2px; + } + + .ds-selector-tabs .selectors button.selected { + color: #202020 !important; + border: 1px solid #ccc; + border-bottom: 1px solid #fff !important; + } + + .ds-selector-tabs .selectors button:hover { + background-color: transparent; + color: #202020; + cursor: pointer; + } - -
-

This document describes Shapes Constraint Language (SHACL) Node Expressions.

+ .ds-selector-tabs .tab { + display: none; + } + + .ds-selector-tabs .selected { + display: block; + } + + + + +
+

This document describes Shapes Constraint Language (SHACL) Node Expressions.

+

+ This specification is published by the + Data Shapes Working Group + . +

+
+ +
+ +
+

Introduction

+

Node expressions

+ +
+

Terminology

+
+
Basic RDF Terminology
+
+ This document uses the terms + RDF graph, + RDF triple, + IRI, + literal, + blank node, + node of an RDF graph, + datatype, + RDF term, and + term equality, + and + subject, + predicate, and + object of RDF triples + as defined in RDF 1.2 Concepts and Abstract Syntax [[!rdf12-concepts]]. +
+
+
+
Basic SHACL Terminology
+
+ This document uses the terms + focus node, + value, + value node, + constraint, + constraint component, + parameter, + mandatory parameter, + optional parameter, + parameter value, + shape, + node shape, + property + shape, + SHACL property path, + SPARQL property path, + data graph, + shapes graph, + target, + validator, + validation + result, + node + expression, + node expression function, + function + name, + output nodes, + focus graph, + evaluation, + evaluation failure, + conform, + conformance + check, + failure, + SHACL instance, + SHACL subclass, + SHACL type, + SHACL list, + members, + well-formed, + deep copy, + as defined in the SHACL 1.2 Core specification [[!shacl12-core]]. +
+
+
+
+

Document Conventions

- This specification is published by the - Data Shapes Working Group + Some examples in this document use Turtle [[rdf12-turtle]]. + The reader is expected to be familiar with SHACL [[shacl12-core]] and SPARQL + [[sparql12-query]]. +

+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrefixNamespace
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#
shnex:http://www.w3.org/ns/shnex#
skos:http://www.w3.org/2004/02/skos/core#
sparql:http://www.w3.org/ns/sparql#
xsd:http://www.w3.org/2001/XMLSchema#
ex:http://example.com/ns#
+ +

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 .

- -
- -
-

Introduction

-

Node expressions

- -
-

Terminology

-
-
Basic RDF Terminology
-
- This document uses the terms - RDF graph, - RDF triple, - IRI, - literal, - blank node, - node of an RDF graph, - datatype, - RDF term, and - term equality, and - subject, - predicate, and - object of RDF triples - as defined in RDF 1.2 Concepts and Abstract Syntax [[!rdf12-concepts]]. -
+
+

TODO

+
+
+ +
+

Getting started with Node Expressions

+

This section is informative.

+

+ A SHACL shapes graph can declare node expressions as values of various properties where dynamic + computation is useful, + such as sh:targetNode, sh:values and sh:deactivated. + A node expression is represented by an RDF node and can be evaluated to produce a list of output + nodes. + For example, when used at sh:targetNode, a node expression produces the list + of target nodes of a shape. + When used at sh:values, a node expression produces the derived values for the property + specified by sh:path. +

+

+ The following example contains a node expression that states that the target nodes of + the shape ex:EstonianCompanyShape are the instances of ex:Company where + the ex:headQuarterCountry is ex:Estonia. +

+

+

-
-

Document Conventions

+ + +

+

+ The following diagram illustrates how this node expression is interpreted, from a logical point of view. + During validation, a SHACL processor will determine the target nodes of the shape + by evaluating the filterShape expression. + However, the filterShape expression first evaluates its input expression, which is specified via + sh:nodes + and is an instancesOf expression. + This will produce all instances of the given class, ex:Company. + The shnex:filterShape is then applied to all of these instances, to keep only the companies + that conform to the provided shape, by having their headquarters in Estonia. +

+
+ Illustration of the data flow between node expressions +
+

+ The scenario above can also be expressed using SPARQL select + expressions. + For performance reasons, for example, specific implementations of SHACL node expressions might + internally convert node expressions such as the shnex:filterShape above to SPARQL. +

+

+

+

+

+ The next example uses a node expression to compute the values of the property ex:employeeCount + as the number of values of the property ex:employee at each instance of + ex:Company. +

+

+

+

+
+ Illustration of the data flow between node expressions computing the employee count +
+

+ One difference between this example and the previous examples about sh:targetNode + is that these node expressions are evaluated against a given focus node. + This means that when a data visualization needs to render an instance of ex:Company, + the currently displayed company is the focus node, for which the number of employees + will be fetched. +

+

Clarify when these derived properties can be used (e.g. in sh:path expressions but not as + triples elsewhere)

+
+ +
+

Node Expression Syntax

+

+ This section introduces the general syntax of SHACL node expressions. +

+

+ The term node expression function refers to the kind or type + of a node expression. + For example, sh:FilterShapeExpression is a node expression function, + while a specific instance of this function in the graph is the node expression itself. +

+

+ The most basic node expression functions are constant node expressions, which are either + literals or IRIs, and simply evaluate to these constants. + All other node expressions are represented by blank nodes, and come in the following two variations: +

+ + +
+

Constant Node Expressions

+

+ The node expression functions in this section are called constant node expressions. + They were introduced in the SHACL Core specification and are repeated here to keep this document + self-contained. +

+ +
+

IRI Expressions

- Some examples in this document use Turtle [[rdf12-turtle]]. - The reader is expected to be familiar with SHACL [[shacl12-core]] and SPARQL - [[sparql12-query]]. + A node expression that is an IRI is called an IRI expression with the + function name + sh:IRIExpression.

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PrefixNamespace
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#
shnex:http://www.w3.org/ns/shnex#
skos:http://www.w3.org/2004/02/skos/core#
sparql:http://www.w3.org/ns/sparql#
xsd:http://www.w3.org/2001/XMLSchema#
ex:http://example.com/ns#
- -

Grey boxes such as this include syntax rules that apply to the shapes graph.

+

+ A node in an RDF graph is a well-formed IRI + expression if it is an IRI. +

+
+
EVALUATION OF IRI EXPRESSIONS
+

+ The output nodes of an IRI expression are the list consisting of exactly the + node expression itself: +
+
+ evalExpr(expr, focusGraph, focusNode, scope) -> [expr] +

+
+
+
+

Literal Expressions

- true - denotes the RDF term - "true"^^xsd:boolean - . - false - denotes the RDF term - "false"^^xsd:boolean - . + A node expression that is a literal is called a literal expression with the + function name + sh:LiteralExpression.

+

+ A node in an RDF graph is a well-formed + literal expression if it is a literal. +

+
+
EVALUATION OF LITERAL EXPRESSIONS
+

+ The output nodes of a literal expression are the list consisting of exactly the + node expression itself: +
+
+ evalExpr(expr, focusGraph, focusNode, scope) -> [expr] +

+
-
-

TODO

-
+
-
-

Getting started with Node Expressions

-

This section is informative.

-

- A SHACL shapes graph can declare node expressions as values of various properties where dynamic computation is useful, - such as sh:targetNode, sh:values and sh:deactivated. - A node expression is represented by an RDF node and can be evaluated to produce a list of output nodes. - For example, when used at sh:targetNode, a node expression produces the list - of target nodes of a shape. - When used at sh:values, a node expression produces the derived values for the property specified by sh:path. -

-

- The following example contains a node expression that states that the target nodes of - the shape ex:EstonianCompanyShape are the instances of ex:Company where - the ex:headQuarterCountry is ex:Estonia. -

-

-

+ +
+

Node Expressions Library

+

+ This section defines all node expression functions that are built into SHACL engines + that implement this specification. +

+

+ The syntax definitions of node expression functions that are based on blank nodes + typically use a table of properties that these blank nodes can or must have. + Such blank nodes are only well-formed when they are not the subject of any other + triples, and when none of these properties is used more than once. + The tables may also list SHACL constraints with which the property values are required to conform. + In the tables, mandatory properties are rendered in bold face. +

+ +
+

Basic Node Expressions

+ +
+

Var Expressions

+

+ + A blank node that is the subject of the following properties + is called a var expression with the function name + shnex:VarExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:var + sh:datatype xsd:string
+ sh:minLength 1 + 		+ The variable name, e.g. "focusNode". +
+ +

+
+
EVALUATION OF VAR EXPRESSIONS
+

+ Let var be the value of shnex:var in the var expression. + The output nodes of the var expression are computed as follows, in order: +

+
    +
  1. if var is "focusNode" then + evalExpr(expr, focusGraph, focusNode, scope) -> [focusNode] +
    2. +
  2. if var is in the scope then + evalExpr(expr, focusGraph, focusNode, scope) -> [ scope[var] ] +
    3. +
  3. otherwise evalExpr(expr, focusGraph, focusNode, scope) -> []
    4. +
+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of a var expression pointing at the current + focus node + to state that the default value of the ex:loves relationship is the current instance of + ex:Person, + creating a self-reference. +

+

+

-

-

- The next example uses a node expression to compute the values of the property ex:employeeCount - as the number of values of the property ex:employee at each instance of ex:Company. -

-

-

+ +
+

List Expressions

+

+ + A blank node that is the subject of the following properties + is called a list expression with the function name + shnex:ListExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
rdf:first + + The first member of the list. +
rdf:rest + Must be a well-formed SHACL list. + + The rest of the list, e.g. rdf:nil. +
+ +

+
+
EVALUATION OF LIST EXPRESSIONS
+

+ The output nodes of a list expression are the members of the SHACL + list. +

+
+

The remainder of this section is informative.

+

+ Note that rdf:nil itself is not a list expression because it will be interpreted + as a IRI expression. + As a result, all well-formed list expressions have at least one member. +

+

+ The following example declares a property for instances of rdfs:Class + where the values are derived from the values of the path rdfs:subClassOf* + but with the constants from the list ( owl:Thing rdfs:Resource ) removed using + shnex:minus. +

+

+

-

-
- Illustration of the data flow between node expressions computing the employee count -
-

- One difference between this example and the previous examples about sh:targetNode - is that these node expressions are evaluated against a given focus node. - This means that when a data visualization needs to render an instance of ex:Company, - the currently displayed company is the focus node, for which the number of employees - will be fetched. -

-

Clarify when these derived properties can be used (e.g. in sh:path expressions but not as triples elsewhere)

-
- -
-

Node Expression Syntax

-

- This section introduces the general syntax of SHACL node expressions. -

-

- The term node expression function refers to the kind or type - of a node expression. - For example, sh:FilterShapeExpression is a node expression function, - while a specific instance of this function in the graph is the node expression itself. -

-

- The most basic node expression functions are constant node expressions, which are either - literals or IRIs, and simply evaluate to these constants. - All other node expressions are represented by blank nodes, and come in the following two variations: -

- +

+
-
-

Constant Node Expressions

-

- The node expression functions in this section are called constant node expressions. - They were introduced in the SHACL Core specification and are repeated here to keep this document self-contained. +

+

Path Expressions

+

+ + A blank node that is the subject of the following properties + is called a path expression with the function name + shnex:PathExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:path + Must be a well-formed SHACL property path. + + The path to get the values from. +
shnex:nodes + Optional, must be a well-formed node expression. + + A node expression producing the focus nodes, defaulting + to the current focus node from the evaluation context. +
+

- -
-

IRI Expressions

-

- A node expression that is an IRI is called an IRI expression with the function name - sh:IRIExpression. -

-

- A node in an RDF graph is a well-formed IRI expression if it is an IRI. -

-
-
EVALUATION OF IRI EXPRESSIONS
-

- The output nodes of an IRI expression are the list consisting of exactly the node expression itself: -
-
- evalExpr(expr, focusGraph, focusNode, scope) -> [expr] -

-
-
- -
-

Literal Expressions

+
+
EVALUATION OF PATH EXPRESSIONS

- A node expression that is a literal is called a literal expression with the function name - sh:LiteralExpression. -

-

- A node in an RDF graph is a well-formed literal expression if it is a literal. + Let path be the value of shnex:path, + and nodes be the value of shnex:nodes in the path + expression. + If shnex:nodes is not given, nodes is the list consistent of exactly + the focus node. + Let N be the nodes produced by + evalExpr(nodes, focusGraph, focusNode, scope). + The output nodes of the path expression are the list of nodes produced by + concatenating + the value nodes of the path at each node in N. + TODO: Clarify if those can contain duplicates.

-
-
EVALUATION OF LITERAL EXPRESSIONS
-

- The output nodes of a literal expression are the list consisting of exactly the node expression itself: -
-
- evalExpr(expr, focusGraph, focusNode, scope) -> [expr] -

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of a path expression to compute the value + of the property ex:topConceptCount. + The path expression returns the values of skos:hasTopConcept at each + skos:ConceptScheme + and these are processed by the shnex:count to return the + number of top concepts. +

+

+

- + +

+

TODO: Add second example that uses shnex:nodes

-
-

Node Expressions based on Blank Nodes

-
-

Named Parameter Functions

-

- A named parameter function is a node expression function - that is represented by a blank node that is the subject of at least - one triple where the predicate can be used to uniquely identify the function, - which is known as the key parameter. -

- The evaluation of a named parameter function can produce any of the following: -

- -

- For example, the named parameter function - shnex:FilterShapeExpression - has shnex:filterShape as its key parameter. - In this document, key parameters are marked in bold face. -

-

- Expressions based on named parameter functions often - take other node expressions as arguments, - evaluate those input node expressions, - and then produce a different list of nodes - as output nodes. -

-

The remainder of this section is informative.

-

- This document includes many examples of named parameter functions, such as - the Estonian Company Shape example. -

-
-
-

List Parameter Functions

-

- A list parameter function is a node expression function - that is represented by a blank node that is the subject of a single - triple where the object is a SHACL list. - The predicate of this triple is called the list parameter property. -

-

- The evaluation of a list parameter function can produce any of the following: -

- -

- Furthermore, each argument of a list parameter function must evaluate to an individual, single node, - not to a list of nodes. - If an argument is a node expression, then this node expression must evaluate to - a maximum of one output node. - An evaluation failure must be produced if there is more than one output node. - This is different from named parameter functions, where arguments may produce lists of multiple nodes. -

-

The remainder of this section is informative.

-

- Note that some named parameter functions — such as shnex:IntersectionExpression — - also use a SHACL list as an object of the key parameter, similar to list parameter functions which always have a SHACL list as the object of their list parameter property. - However, these may produce more than one output nodes, and also accept lists as input nodes. -

-

- The following example uses multiple (imaginary) list parameter functions — - ex:coalesce and ex:concat — to compute the ex:displayName - of a person as either the value of ex:fullName or (if that doesn't exist) - as a concatenation of ex:firstName, a space, and ex:lastName. -

+
+

Exists Expressions

+

+ + A blank node that is the subject of the following properties + is called an exists expression with the function name + shnex:ExistsExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:exists + A well-formed node expression. + + A node expression. If this evaluates to a list with at least one member + then the output nodes are ( true ); otherwise, the output nodes are + ( false ). +
+ +

+
+
EVALUATION OF EXISTS EXPRESSIONS

-

+ Let exists be the value of shnex:exists in the exists + expression. + Let N be the list of nodes produced by + evalExpr(exists, focusGraph, focusNode, scope). + The output nodes of the exists expression are ( true ) if and only if + N has at least one member; otherwise, the output nodes are ( false ).

-
-
- -
-

Handling of Failures

-

- Node expressions may produce a failure instead of a list of output nodes. - Some node expressions evaluate other, nested node expressions. - For example, If Expressions evaluate nested expressions for - shnex:if, shnex:then and shnex:else. - In general, if any such nested expressions produce a failure then the surrounding - expression also produces the same failure. -

+

The remainder of this section is informative.

- Note that this policy impacts the evaluation order of node expressions. - For example, shnex:if expressions are evaluated first and shnex:then - will be evaluated only if the shnex:if has returned ( true ). - Even if the shnex:else branch would produce a failure, the output would - still only be the output nodes of the shnex:then branch. + The Example for shnex:if uses + shnex:exists.

-
- -
-

Node Expressions Library

-

- This section defines all node expression functions that are built into SHACL engines - that implement this specification. -

-

- The syntax definitions of node expression functions that are based on blank nodes - typically use a table of properties that these blank nodes can or must have. - Such blank nodes are only well-formed when they are not the subject of any other - triples, and when none of these properties is used more than once. - The tables may also list SHACL constraints with which the property values are required to conform. - In the tables, mandatory properties are rendered in bold face. -

- -
-

Basic Node Expressions

- -
-

Var Expressions

-

- - A blank node that is the subject of the following properties - is called a var expression with the function name shnex:VarExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:var - sh:datatype xsd:string
- sh:minLength 1 - 		- The variable name, e.g. "focusNode". -
- -

-
-
EVALUATION OF VAR EXPRESSIONS
-

- Let var be the value of shnex:var in the var expression. - The output nodes of the var expression are computed as follows, in order: -

-
    -
  1. if var is "focusNode" then evalExpr(expr, focusGraph, focusNode, scope) -> [focusNode]
    2. -
  2. if var is in the scope then evalExpr(expr, focusGraph, focusNode, scope) -> [ scope[var] ]
    3. -
  3. otherwise evalExpr(expr, focusGraph, focusNode, scope) -> []
    4. -
-
-

The remainder of this section is informative.

-

- The following example illustrates the use of a var expression pointing at the current focus node - to state that the default value of the ex:loves relationship is the current instance of ex:Person, - creating a self-reference. -

-

-

-

-
- -
-

List Expressions

-

- - A blank node that is the subject of the following properties - is called a list expression with the function name shnex:ListExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
rdf:first - - The first member of the list. -
rdf:rest - Must be a well-formed SHACL list. - - The rest of the list, e.g. rdf:nil. -
- -

-
-
EVALUATION OF LIST EXPRESSIONS
-

- The output nodes of a list expression are the members of the SHACL list. -

-
-

The remainder of this section is informative.

-

- Note that rdf:nil itself is not a list expression because it will be interpreted - as a IRI expression. - As a result, all well-formed list expressions have at least one member. -

-

- The following example declares a property for instances of rdfs:Class - where the values are derived from the values of the path rdfs:subClassOf* - but with the constants from the list ( owl:Thing rdfs:Resource ) removed using - shnex:minus. -

-

-

-

-
- -
-

Path Expressions

-

- - A blank node that is the subject of the following properties - is called a path expression with the function name shnex:PathExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:path - Must be a well-formed SHACL property path. - - The path to get the values from. -
shnex:nodes - Optional, must be a well-formed node expression. - - A node expression producing the focus nodes, defaulting - to the current focus node from the evaluation context. -
- -

-
-
EVALUATION OF PATH EXPRESSIONS
-

- Let path be the value of shnex:path, - and nodes be the value of shnex:nodes in the path expression. - If shnex:nodes is not given, nodes is the list consistent of exactly the focus node. - Let N be the nodes produced by evalExpr(nodes, focusGraph, focusNode, scope). - The output nodes of the path expression are the list of nodes produced by concatenating - the value nodes of the path at each node in N. - TODO: Clarify if those can contain duplicates. -

-
-

The remainder of this section is informative.

-

- The following example illustrates the use of a path expression to compute the value - of the property ex:topConceptCount. - The path expression returns the values of skos:hasTopConcept at each skos:ConceptScheme - and these are processed by the shnex:count to return the - number of top concepts. -

-

-

-

-

TODO: Add second example that uses shnex:nodes

-
- -
-

Exists Expressions

-

- - A blank node that is the subject of the following properties - is called an exists expression with the function name shnex:ExistsExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:exists - A well-formed node expression. - - A node expression. If this evaluates to a list with at least one member - then the output nodes are ( true ); otherwise, the output nodes are ( false ). -
- -

-
-
EVALUATION OF EXISTS EXPRESSIONS
-

- Let exists be the value of shnex:exists in the exists expression. - Let N be the list of nodes produced by evalExpr(exists, focusGraph, focusNode, scope). - The output nodes of the exists expression are ( true ) if and only if - N has at least one member; otherwise, the output nodes are ( false ). -

-
-

The remainder of this section is informative.

+
+

If Expressions

+

+ + A blank node that is the subject of the following properties + is called an if expression with the function name + shnex:IfExpression: + + + + + + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:if + A well-formed node expression. + + A node expression. The shnex:then branch is returned when the + shnex:if expression + returns true as its only output node, in all other cases + shnex:else. +
shnex:then + A well-formed node expression. + Optional but at least one of shnex:then or shnex:else + is required. + + The node expression that is returned when the shnex:if + evaluated to [true]. +
shnex:else + A well-formed node expression. + Optional but at least one of shnex:then or shnex:else + is required. + + The node expression that is returned when the shnex:if did + not evaluate to [true]. +
+ +

+
+
EVALUATION OF IF EXPRESSIONS

- The Example for shnex:if uses shnex:exists. + Let if be the value of shnex:if, + then be the value of shnex:then, and + else be the value of shnex:else for the if expression. + Let IFs be the nodes produced by + evalExpr(if, focusGraph, focusNode, scope). + If IFs is the list ( true ), then the output nodes of the if + expression + are the nodes produced by evalExpr(then, focusGraph, focusNode, scope), or the + empty list if then has no value. + Otherwise, the output nodes are the nodes produced by + evalExpr(else, focusGraph, focusNode, scope), or the empty list if + else has no value. + Implementations MUST apply lazy evaluation techniques, so the shnex:then or + shnex:else branches are only evaluated when necessary.

-
- -
-

If Expressions

-

- - A blank node that is the subject of the following properties - is called an if expression with the function name shnex:IfExpression: - - - - - - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:if - A well-formed node expression. - - A node expression. The shnex:then branch is returned when the shnex:if expression - returns true as its only output node, in all other cases shnex:else. -
shnex:then - A well-formed node expression. - Optional but at least one of shnex:then or shnex:else is required. - - The node expression that is returned when the shnex:if evaluated to [true]. -
shnex:else - A well-formed node expression. - Optional but at least one of shnex:then or shnex:else is required. - - The node expression that is returned when the shnex:if did not evaluate to [true]. -
- -

-
-
EVALUATION OF IF EXPRESSIONS
-

- Let if be the value of shnex:if, - then be the value of shnex:then, and - else be the value of shnex:else for the if expression. - Let IFs be the nodes produced by evalExpr(if, focusGraph, focusNode, scope). - If IFs is the list ( true ), then the output nodes of the if expression - are the nodes produced by evalExpr(then, focusGraph, focusNode, scope), or the empty list if then has no value. - Otherwise, the output nodes are the nodes produced by evalExpr(else, focusGraph, focusNode, scope), or the empty list if else has no value. - Implementations MUST apply lazy evaluation techniques, so the shnex:then or - shnex:else branches are only evaluated when necessary. -

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:if to compute the + values of a derived property ex:fillColor that may be queried to + compute the colors of cities on a map. + In the example, instances of ex:City that have a value for ex:capitalOf + will be displayed in "blue", while the others will be "red". +

+

+

- + +

-
-

List Operator Expressions

- -
-

Distinct Expressions

-

- - A blank node that is the subject of the following properties - is called a distinct expression with the function name shnex:DistinctExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:distinct - A well-formed node expression. - - The node expression that shall be reduced to its distinct members. -
- -

-
-
EVALUATION OF DISTINCT EXPRESSIONS
-

- Let distinct be the value of shnex:distinct in the distinct expression. - Let input be the output nodes of evalExpr(distinct, focusGraph, focusNode, scope). - The output nodes of the distinct expression are the list of nodes in input - in the same order but with duplicates eliminated (the first occurences of each node shall be kept, the others removed). - Nodes are compared using term equality, i.e. "01"^^xsd:integer is distinct from "1"^^xsd:integer. -

-
-

The remainder of this section is informative.

-

- The following example declares a derived property ex:superClassesIncludingRoot - that is computed as the union of the (transitive) values of rdfs:subClassOf - and the list expression ( rdfs:Resource ). - Since the asserted values of rdfs:subClassOf may already include rdfs:Resource - (for example, due to an active inference engine on the data graph), shnex:distinct will make - sure that the output nodes do not include rdfs:Resource twice. -

-

-

-

-
- -
-

Intersection Expressions

-

- - A blank node that is the subject of the following properties - is called an intersection expression with the function name shnex:IntersectionExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:intersection - A well-formed SHACL list where each member is a well-formed node expression. - - The node expressions that shall be intersected. -
- -

-
-
EVALUATION OF INTERSECTION EXPRESSIONS
-

- Let members be the members of the value of shnex:intersection in the intersection expression. - The output nodes of the intersection expression are the nodes that form the intersection of the output nodes - produced by each node expression NE in members, using evalExpr(NE, focusGraph, focusNode, scope). - Nodes must be equal using term equality, i.e. "01"^^xsd:integer is distinct from "1"^^xsd:integer. -

-
-

The remainder of this section is informative.

-

- The following example uses shnex:intersection as a sh:targetNode node expression. - This shape will target all nodes that are SHACL instances of ex:Australian and - ex:German at the same time. -

-

-

-

-
- -
-

Union Expressions

-

- - A blank node that is the subject of the following properties - is called a union expression with the function name shnex:UnionExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:union - A well-formed SHACL list where each member is a well-formed node expression. - - The node expressions that shall be unioned. -
- -

-
-
EVALUATION OF UNION EXPRESSIONS
-

- Let members be the members of the value of shnex:union in the union expression. - The output nodes of the union expression are the concatenation of all output nodes - for each node expression NE in members, using evalExpr(NE, focusGraph, focusNode, scope). - The order is preserved, evaluating the members from left to right and keeping the order of each list of output nodes. -

-
-

The remainder of this section is informative.

-

- Note that a union expression may produce duplicate output nodes if the individual output nodes overlap. - Use shnex:distinct to eliminate duplicates. -

-

- The Example for shnex:distinct uses shnex:union. -

-
- -
-

Minus Expressions

-

- - A blank node that is the subject of the following properties - is called a minus expression with the function name shnex:MinusExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:minus - A well-formed node expression. - - The nodes that shall be removed from the shnex:nodes. -
shnex:nodes - A well-formed node expression. - - The input nodes. -
- -

-
-
EVALUATION OF MINUS EXPRESSIONS
-

- Let minus be the value of shnex:minus - and nodes be the value of shnex:nodes in the minus expression. - Let M be the output nodes of evalExpr(minus, focusGraph, focusNode, scope). - Let N be the output nodes of evalExpr(nodes, focusGraph, focusNode, scope). - The output nodes of the minus expression are the nodes in N - except those that are also in M, preserving the order of N. - Nodes must be equal using term equality, i.e. "01"^^xsd:integer is distinct from "1"^^xsd:integer. -

-
-

The remainder of this section is informative.

-

- The List Expression example uses shnex:minus. -

-
- -
-

FilterShape Expressions

-

- - A blank node that is the subject of the following properties - is called a filterShape expression with the function name shnex:FilterShapeExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:filterShape - A well-formed shape. - - The shape that all input nodes need to conform to. -
shnex:nodes - A well-formed node expression. - - A node expression producing the nodes that are validated. -
- -

-
-
EVALUATION OF FILTERSHAPE EXPRESSIONS
-

- Let filterShape be the value of shnex:filterShape, - and nodes be the value of shnex:nodes in a filterShape expression. - The output nodes of the filterShape expression are the output nodes of - evalExpr(nodes, focusGraph, focusNode, scope) except those that do not conform to - the shape filterShape, preserving the order in the list. -

-
-

The remainder of this section is informative.

-

- The following example illustrates the use of shnex:filterShape to return a subset - of values of the ex:child property where the ex:gender property - has the value "male". -

-

-

-

-
- -
-

Limit Expressions

-

- - A blank node that is the subject of the following properties - is called a limit expression with the function name shnex:LimitExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:limit - sh:datatype xsd:integer
- sh:minInclusive 0 - 		- The maximum number of nodes that shall be returned. -
shnex:nodes - A well-formed node expression. - - The input nodes. -
- -

-
-
EVALUATION OF LIMIT EXPRESSIONS
-

- Let limit be the value of shnex:limit - and nodes be the value of shnex:nodes in the limit expression. - Let N be the output nodes of evalExpr(nodes, focusGraph, focusNode, scope). - The output nodes of the limit expression are the first limit nodes in N - from left to right, in the same order. -

-
-

The remainder of this section is informative.

-

- The following example illustrates the use of shnex:limit to compute the - values of a derived property ex:oldestChildren to be a sub-list of - values of ex:child at the current focus node (which is an instance of - the class ex:Person). - The values are computed by first fetching the values of ex:child, then - ordering them by their ex:dateOfBirth, and finally getting only - 2 of these children at most. -

+
+ +
+

List Operator Expressions

+ +
+

Distinct Expressions

+

+ + A blank node that is the subject of the following properties + is called a distinct expression with the function name + shnex:DistinctExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:distinct + A well-formed node expression. + + The node expression that shall be reduced to its distinct members. +
+ +

+
+
EVALUATION OF DISTINCT EXPRESSIONS

-

-

-
- -
-

Offset Expressions

-

- - A blank node that is the subject of the following properties - is called an offset expression with the function name shnex:OffsetExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:offset - sh:datatype xsd:integer
- sh:minInclusive 0 - 		- The number of nodes that shall be skipped from the shnex:nodes. -
shnex:nodes - A well-formed node expression. - - The input nodes. -
- + Let distinct be the value of shnex:distinct in the distinct + expression. + Let input be the output nodes of + evalExpr(distinct, focusGraph, focusNode, scope). + The output nodes of the distinct expression are the list of nodes in + input + in the same order but with duplicates eliminated (the first occurences of each node shall be + kept, the others removed). + Nodes are compared using term equality, i.e. "01"^^xsd:integer is distinct + from "1"^^xsd:integer.

-
-
EVALUATION OF OFFSET EXPRESSIONS
-

- Let offset be the value of shnex:offset - and nodes be the value of shnex:nodes in the offset expression. - Let N be the output nodes of evalExpr(nodes, focusGraph, focusNode, scope). - The output nodes of the offset expression are the nodes in N - except for the first offset nodes from left to right, in the same order. -

+
+

The remainder of this section is informative.

+

+ The following example declares a derived property ex:superClassesIncludingRoot + that is computed as the union of the (transitive) values of + rdfs:subClassOf + and the list expression ( rdfs:Resource ). + Since the asserted values of rdfs:subClassOf may already include + rdfs:Resource + (for example, due to an active inference engine on the data graph), shnex:distinct will + make + sure that the output nodes do not include rdfs:Resource twice. +

+

+

+

+
+ +
+

Intersection Expressions

+

+ + A blank node that is the subject of the following properties + is called an intersection expression with the function name + shnex:IntersectionExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:intersection + A well-formed SHACL list where each member is a + well-formed node expression. + + The node expressions that shall be intersected. +
+ +

+
+
EVALUATION OF INTERSECTION EXPRESSIONS

-

+ Let members be the members of the value of + shnex:intersection in the intersection expression. + The output nodes of the intersection expression are the nodes that form the + intersection of the output nodes + produced by each node expression NE in members, using + evalExpr(NE, focusGraph, focusNode, scope). + Nodes must be equal using term equality, i.e. "01"^^xsd:integer is distinct + from "1"^^xsd:integer.

-
+ +

The remainder of this section is informative.

+

+ The following example uses shnex:intersection as a sh:targetNode node + expression. + This shape will target all nodes that are SHACL instances of ex:Australian and + ex:German at the same time. +

+

+

+

+
-
-

OrderBy Expressions

-

TODO: This should be cleaned up from the SHACL-AF definition and requires thought

+
+

Union Expressions

+

+ + A blank node that is the subject of the following properties + is called a union expression with the function name + shnex:UnionExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:union + A well-formed SHACL list where each member is a + well-formed node expression. + + The node expressions that shall be unioned. +
+ +

+
+
EVALUATION OF UNION EXPRESSIONS

- The Example of shnex:limit also illustrates shnex:orderBy. + Let members be the members of the value of shnex:union + in the union expression. + The output nodes of the union expression are the concatenation of all output + nodes + for each node expression NE in members, using + evalExpr(NE, focusGraph, focusNode, scope). + The order is preserved, evaluating the members from left to right and keeping the + order of each list of output nodes.

-
- + +

The remainder of this section is informative.

+

+ Note that a union expression may produce duplicate output nodes if the individual + output nodes overlap. + Use shnex:distinct to eliminate duplicates. +

+

+ The Example for shnex:distinct uses + shnex:union. +

-
-

Aggregation Expressions

- -
-

Count Expressions

-

- - A blank node that is the subject of the following properties - is called a count expression with the function name shnex:CountExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:count - A well-formed node expression. - - The input nodes that shall be counted. -
- -

-
-
EVALUATION OF COUNT EXPRESSIONS
-

- Let count be the value of shnex:count in the count expression. - Let N be the output nodes of evalExpr(count, focusGraph, focusNode, scope). - The output nodes of the count expression is the list consisting of exactly one - xsd:integer literal that is computed as the length of N. -

-
-

The remainder of this section is informative.

+
+

Minus Expressions

+

+ + A blank node that is the subject of the following properties + is called a minus expression with the function name + shnex:MinusExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:minus + A well-formed node expression. + + The nodes that shall be removed from the shnex:nodes. +
shnex:nodes + A well-formed node expression. + + The input nodes. +
+ +

+
+
EVALUATION OF MINUS EXPRESSIONS

- The following example illustrates the use of shnex:count to derive a property - ex:topConceptCount as the number of values of the skos:hasTopConcept - property in a skos:ConceptScheme. + Let minus be the value of shnex:minus + and nodes be the value of shnex:nodes in the minus + expression. + Let M be the output nodes of + evalExpr(minus, focusGraph, focusNode, scope). + Let N be the output nodes of + evalExpr(nodes, focusGraph, focusNode, scope). + The output nodes of the minus expression are the nodes in N + except those that are also in M, preserving the order of N. + Nodes must be equal using term equality, i.e. "01"^^xsd:integer is distinct + from "1"^^xsd:integer.

+
+

The remainder of this section is informative.

+

+ The List Expression example uses shnex:minus. +

+
+ +
+

FilterShape Expressions

+

+ + A blank node that is the subject of the following properties + is called a filterShape expression with the function name + shnex:FilterShapeExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:filterShape + A well-formed shape. + + The shape that all input nodes need to conform to. +
shnex:nodes + A well-formed node expression. + + A node expression producing the nodes that are validated. +
+ +

+
+
EVALUATION OF FILTERSHAPE EXPRESSIONS

-

+ Let filterShape be the value of shnex:filterShape, + and nodes be the value of shnex:nodes in a filterShape + expression. + The output nodes of the filterShape expression are the output nodes of + evalExpr(nodes, focusGraph, focusNode, scope) except those that do not + conform to + the shape filterShape, preserving the order in the list.

-
- -
-

Min Expressions

-

- - A blank node that is the subject of the following properties - is called a min expression with the function name shnex:MinExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:min - A well-formed node expression. - - The input nodes from which the minimum value shall be returned. -
- -

-
-
EVALUATION OF MIN EXPRESSIONS
-

- Let min be the value of shnex:min in the min expression. - Let N be the output nodes of evalExpr(min, focusGraph, focusNode, scope). - The output nodes of the min expression is the list consisting of at most one node - that is computed as the minimum value from N. - Clarify exactly how that is computed, maybe via reference to SPARQL MIN -

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:filterShape to return a subset + of values of the ex:child property where the ex:gender property + has the value "male". +

+

+

+

+
+ +
+

Limit Expressions

+

+ + A blank node that is the subject of the following properties + is called a limit expression with the function name + shnex:LimitExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:limit + sh:datatype xsd:integer
+ sh:minInclusive 0 + 		+ The maximum number of nodes that shall be returned. +
shnex:nodes + A well-formed node expression. + + The input nodes. +
+ +

+
+
EVALUATION OF LIMIT EXPRESSIONS

-

-

-
- -
-

Max Expressions

-

- - A blank node that is the subject of the following properties - is called a max expression with the function name shnex:MaxExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:max - A well-formed node expression. - - The input nodes from which the maximum value shall be returned. -
- + Let limit be the value of shnex:limit + and nodes be the value of shnex:nodes in the limit + expression. + Let N be the output nodes of + evalExpr(nodes, focusGraph, focusNode, scope). + The output nodes of the limit expression are the first limit + nodes in N + from left to right, in the same order.

-
-
EVALUATION OF MAX EXPRESSIONS
-

- Let max be the value of shnex:max in the max expression. - Let N be the output nodes of evalExpr(max, focusGraph, focusNode, scope). - The output nodes of the max expression is the list consisting of at most one node - that is computed as the maximum value from N. - Clarify exactly how that is computed, maybe via reference to SPARQL MAX -

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:limit to compute the + values of a derived property ex:oldestChildren to be a sub-list of + values of ex:child at the current focus node (which is an instance of + the class ex:Person). + The values are computed by first fetching the values of ex:child, then + ordering them by their ex:dateOfBirth, and finally getting only + 2 of these children at most. +

+

+

+

+
+ +
+

Offset Expressions

+

+ + A blank node that is the subject of the following properties + is called an offset expression with the function name + shnex:OffsetExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:offset + sh:datatype xsd:integer
+ sh:minInclusive 0 + 		+ The number of nodes that shall be skipped from the shnex:nodes. +
shnex:nodes + A well-formed node expression. + + The input nodes. +
+ +

+
+
EVALUATION OF OFFSET EXPRESSIONS

- The Example for shnex:min can be easily adapted - for shnex:max. -

-
- -
-

Sum Expressions

-

- - A blank node that is the subject of the following properties - is called a sum expression with the function name shnex:SumExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:sum - A well-formed node expression. - - The input nodes from which the sum shall be returned. -
- + Let offset be the value of shnex:offset + and nodes be the value of shnex:nodes in the offset + expression. + Let N be the output nodes of + evalExpr(nodes, focusGraph, focusNode, scope). + The output nodes of the offset expression are the nodes in N + except for the first offset nodes from left to right, in the same order.

-
-
EVALUATION OF SUM EXPRESSIONS
-

- Let sum be the value of shnex:sum in the sum expression. - Let N be the output nodes of evalExpr(sum, focusGraph, focusNode, scope). - The output nodes of the sum expression is the list consisting of exactly one node - that is computed as the sum of all nodes from N. - Clarify exactly how that is computed, maybe via reference to SPARQL SUM -

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:offset to compute the + values of a derived property ex:remainingChildren to be a sub-list of + values of ex:child at the current focus node (which is an instance of + the class ex:Person). + The values are computed by first fetching the values of ex:child, then + ordering them by their ex:dateOfBirth, and finally skipping the first + of these children. +

+

+

- + +

-
-

Miscellaneous Node Expressions

+
+

OrderBy Expressions

+

TODO: This should be cleaned up from the SHACL-AF definition and requires thought

- This section enumerates node expression functions that did not fit into other categories. -

- -
-

InstancesOf Expressions

-

- - A blank node that is the subject of the following properties - is called an instancesOf expression with the function name shnex:InstancesOfExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:instancesOf - sh:nodeKind sh:IRI - - The class that the output nodes must be instances of. -
- -

-
-
EVALUATION OF INSTANCESOF EXPRESSIONS
-

- Let type be the value of shnex:instancesOf in an instancesOf expression. - The output nodes of the instancesOf expression are the nodes that are SHACL instances - of type in the focus graph. -

-
-

The remainder of this section is informative.

-

- Note that the definition of SHACL instance includes instances of subclasses of the given class. - So if the focus graph contains ex:SubClass rdfs:subClassOf ex:SuperClass and ex:SubInstance a ex:SubClass - then ex:SubInstance will also be returned as instance of ex:SuperClass. -

-

- The interpretation of shnex:instancesOf is similar to sh:targetClass and sh:class. -

-

- Users of this node expression function should be aware that the list of output nodes may be very large. -

-

- The Example for shnex:intersection uses shnex:instanceOf. -

-
- + The Example of shnex:limit also illustrates + shnex:orderBy. +

-
-

Constraint Components

-

- This section introduces SHACL constraint components that operate on node expressions. -

- -
-

sh:expression

-

- Based on node expressions, this section introduces a constraint component called - expression constraints. - Expression constraints can be used in any shape to declare the condition that the - node expression specified via sh:expression has true as its only output node. - The evaluation of these node expressions is repeated for all value nodes of the shape - as the focus node. +

+

Aggregation Expressions

+ +
+

Count Expressions

+

+ + A blank node that is the subject of the following properties + is called a count expression with the function name + shnex:CountExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:count + A well-formed node expression. + + The input nodes that shall be counted. +
+

-

- Constraint Component IRI: sh:ExpressionConstraintComponent -

- -
Parameters:
- - - - - - - - - - - - - -
PropertySummary and Syntax Rules
sh:expression - The node expression that must return true. - The values of sh:expression at a - shape must be well-formed node expressions. -
-
-
TEXTUAL DEFINITION
-
- Let $expr be a value of sh:expression. - For each value node v - where evalExpr(expr, data graph, focusNode, {value: v}) - does not return the list consisting of exactly true as its output nodes, - there is a validation result that has v as its sh:value - and a deep copy of $expr in the results graph as its sh:sourceConstraint. -
+
+
EVALUATION OF COUNT EXPRESSIONS
+

+ Let count be the value of shnex:count in the count + expression. + Let N be the output nodes of + evalExpr(count, focusGraph, focusNode, scope). + The output nodes of the count expression is the list consisting of exactly one + xsd:integer literal that is computed as the length of N. +

The remainder of this section is informative.

- Note that the scope in the evaluation of expression constraints contains the variable value - for the current value node while the variable focusNode is the focus node. + The following example illustrates the use of shnex:count to derive a property + ex:topConceptCount as the number of values of the skos:hasTopConcept + property in a skos:ConceptScheme.

- The following example uses some SPARQL-based node expressions to declare - the constraint that the values of ex:ibanNumber must start with the same two (upper-case) letters as - the values of the path ex:country/ex:code. -

-
+ +
+

Min Expressions

+

+ + A blank node that is the subject of the following properties + is called a min expression with the function name + shnex:MinExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:min + A well-formed node expression. + + The input nodes from which the minimum value shall be returned. +
+ +

+
+
EVALUATION OF MIN EXPRESSIONS
+

+ Let min be the value of shnex:min in the min expression. + Let N be the output nodes of + evalExpr(min, focusGraph, focusNode, scope). + The output nodes of the min expression is the list consisting of at most one + node + that is computed as the minimum value from N. + Clarify exactly how that is computed, maybe via reference to SPARQL + MIN +

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:min to derive a property + ex:minStartDate as the smallest value of the values that can be reached using the + property path ex:exployee/ex:startDate. + In other words, it walks through all employees of the given company and returns the earliest + date on which an employee started. +

+

+

+

-
-

sh:nodeByExpression

+
+

Max Expressions

+

+ + A blank node that is the subject of the following properties + is called a max expression with the function name + shnex:MaxExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:max + A well-formed node expression. + + The input nodes from which the maximum value shall be returned. +
+ +

+
+
EVALUATION OF MAX EXPRESSIONS
+

+ Let max be the value of shnex:max in the max expression. + Let N be the output nodes of + evalExpr(max, focusGraph, focusNode, scope). + The output nodes of the max expression is the list consisting of at most one + node + that is computed as the maximum value from N. + Clarify exactly how that is computed, maybe via reference to SPARQL + MAX +

+
+

The remainder of this section is informative.

- sh:nodeByExpression specifies the condition that each value node conforms to the - node shapes produced by a node expression. - The evaluation of these node expressions is repeated for all value nodes of the shape - as the focus node. + The Example for shnex:min can be easily adapted + for shnex:max. +

+
+ +
+

Sum Expressions

+

+ + A blank node that is the subject of the following properties + is called a sum expression with the function name + shnex:SumExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:sum + A well-formed node expression. + + The input nodes from which the sum shall be returned. +
+

+
+
EVALUATION OF SUM EXPRESSIONS
+

+ Let sum be the value of shnex:sum in the sum expression. + Let N be the output nodes of + evalExpr(sum, focusGraph, focusNode, scope). + The output nodes of the sum expression is the list consisting of exactly one + node + that is computed as the sum of all nodes from N. + Clarify exactly how that is computed, maybe via reference to SPARQL + SUM +

+
+

The remainder of this section is informative.

- Constraint Component IRI: sh:NodeByExpressionConstraintComponent -

- -
Parameters:
- - - - - - - - - - - - - -
PropertySummary and Syntax Rules
sh:nodeByExpression - The node shapes that all value nodes need to conform to. - The values of sh:nodeByExpression in a shape must be well-formed node expressions. -
-
-
TEXTUAL DEFINITION
-
- Let $expr be a value of sh:nodeByExpression. - For each value node v: perform a conformance check of - v against each output node of evalExpr(expr, - data graph, v, {}) s. A failure - MUST be produced if the conformance check of v against - s produces a failure. Otherwise, if v does - not conform to s, there is a validation result - with v as sh:value and a deep copy of - s as sh:sourceConstraint. -
+ Note that shnex:sum needs to be used with care and may be often misunderstood, + when used with property paths. + The problem is that when a path expression is used as input to a sum expression, + the path expression will have eliminated duplicates before they can be processed by the + shnex:sum. + As a result, only the distinct values will be added up. +

+

TODO: Find good example, or drop the feature if none makes sense

+
+ +
+ + + +
+

Miscellaneous Node Expressions

+

+ This section enumerates node expression functions that did not fit into other categories. +

+ +
+

InstancesOf Expressions

+

+ + A blank node that is the subject of the following properties + is called an instancesOf expression with the function name + shnex:InstancesOfExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:instancesOf + sh:nodeKind sh:IRI + + The class that the output nodes must be instances of. +
+ +

+
+
EVALUATION OF INSTANCESOF EXPRESSIONS
+

+ Let type be the value of shnex:instancesOf in an instancesOf + expression. + The output nodes of the instancesOf expression are the nodes that are + SHACL instances + of type in the focus graph. +

The remainder of this section is informative.

- sh:nodeByExpression functions similarly to sh:node, but instead of referencing a fixed node shape, - a referenced node expression is used to dynamically compute the set of node shapes to which each value node must conform. + Note that the definition of SHACL instance includes instances of subclasses of the + given class. + So if the focus graph contains ex:SubClass rdfs:subClassOf ex:SuperClass and + ex:SubInstance a ex:SubClass + then ex:SubInstance will also be returned as instance of ex:SuperClass.

- There are three key differences between sh:nodeByExpression and sh:node: -

    -
  1. - sh:nodeByExpression references a node expression instead of a fixed node shape as sh:node does. -
    2. -
  2. - sh:nodeByExpression cannot reference a node shape that is a blank node as a value like sh:node can, - as a blank node would be interpreted as a node expression. -
    3. -
  3. - Results generated by sh:nodeByExpression additionally include a value for `sh:sourceConstraint`. -
    4. -
+ The interpretation of shnex:instancesOf is similar to sh:targetClass and + sh:class.

- Note that sh:node and sh:nodeByExpression exhibit the same behavior when given a value that is an IRI of a node shape. - In this case, sh:node directly validates against the specified node shape, whereas sh:nodeByExpression interprets the IRI - as an IRI expression that evaluates to a set containing the same node shape. + Users of this node expression function should be aware that the list of output nodes may be very + large.

- The following example demonstrates how sh:nodeByExpression could be used in the context of the W3C Data Cube Vocabulary. - Building upon examples 5 and 6 from the Data Cube Vocabulary documentation, Data Structure Definition is extended with the property eg:hasShape, - which links to an associated node shape to which relevant qb:Observation instances must conform. - To validate that every qb:Observation instance conforms to the appropriate shape, sh:nodeByExpression with a Path Expression - is used to locate the shape at the property path qb:dataSet/qb:structure/eg:hasShape from each qb:Observation instance. + The Example for shnex:intersection uses + shnex:instanceOf.

-
+ +
+ +
+
+

SPARQL Functions

+

+ This section introduces SHACL [[sparql12-query]] that can be used in node expressions. +

+ +
+
+

Constraint Components

+

+ This section introduces SHACL constraint components that operate on node expressions. +

+ +
+

sh:expression

+

+ Based on node expressions, this section introduces a constraint component called + expression constraints. + Expression constraints can be used in any shape to declare the condition that the + node expression specified via sh:expression has true as its only output + node. + The evaluation of these node expressions is repeated for all value nodes of the shape + as the focus node. +

+

+ Constraint Component IRI: + sh:ExpressionConstraintComponent +

+ +
Parameters:
+ + + + + + + + + + + + + +
PropertySummary and Syntax Rules
sh:expression + The node expression that must return true. + The values of sh:expression at + a + shape must be well-formed node expressions. +
+
+
TEXTUAL DEFINITION
+
+ Let $expr be a value of sh:expression. + For each value node v + where evalExpr(expr, data graph, focusNode, {value: v}) + does not return the list consisting of exactly true as its output nodes, + there is a validation result that has v as its sh:value + and a deep copy of $expr in the results graph as its + sh:sourceConstraint. +
+
+

The remainder of this section is informative.

+

+ Note that the scope in the evaluation of expression constraints contains the variable value + for the current value node while the variable focusNode is the focus node. +

+

+ The following example uses some SPARQL-based node expressions to declare + the constraint that the values of ex:ibanNumber must start with the same two (upper-case) + letters as + the values of the path ex:country/ex:code. +

+ +
+ +
+

sh:nodeByExpression

+

+ sh:nodeByExpression specifies the condition that each value node conforms to the + node shapes produced by a node expression. + The evaluation of these node expressions is repeated for all value nodes of the shape + as the focus node. +

+

+ Constraint Component IRI: + sh:NodeByExpressionConstraintComponent +

+ +
Parameters:
+ + + + + + + + + + + + + +
PropertySummary and Syntax Rules
sh:nodeByExpression + The node shapes that all value nodes need to conform to. + The values of + sh:nodeByExpression in a shape must be well-formed node + expressions. +
+
+
TEXTUAL DEFINITION
+
+ Let $expr be a value of sh:nodeByExpression. + For each value node v: perform a conformance check of + v against each output node of evalExpr(expr, + data graph, v, {}) s. A failure + MUST be produced if the conformance check of v against + s produces a failure. Otherwise, if v does + not conform to s, there is a validation result + with v as sh:value and a deep copy of + s as sh:sourceConstraint. +
+
+

The remainder of this section is informative.

+

+ sh:nodeByExpression functions similarly to sh:node, but instead of referencing + a fixed node shape, + a referenced node expression is used to dynamically compute the set of node shapes to + which each value node must conform. +

+

+ There are three key differences between sh:nodeByExpression and sh:node: +

    +
  1. + sh:nodeByExpression references a node expression instead of a fixed node + shape as sh:node does. +
    2. +
  2. + sh:nodeByExpression cannot reference a node shape that is a blank node as + a value like sh:node can, + as a blank node would be interpreted as a node expression. +
    3. +
  3. + Results generated by sh:nodeByExpression additionally include a value for + `sh:sourceConstraint`. +
    4. +
+

+

+ Note that sh:node and sh:nodeByExpression exhibit the same behavior when given + a value that is an IRI of a node shape. + In this case, sh:node directly validates against the specified node shape, whereas + sh:nodeByExpression interprets the IRI + as an IRI expression that evaluates to a set containing the same node shape. +

+

+ The following example demonstrates how sh:nodeByExpression could be used in the context of + the W3C Data Cube Vocabulary. + Building upon examples 5 and 6 from the Data Cube Vocabulary documentation, Data Structure Definition is + extended with the property eg:hasShape, + which links to an associated node shape to which relevant qb:Observation instances + must conform. + To validate that every qb:Observation instance conforms to the appropriate shape, + sh:nodeByExpression with a Path Expression + is used to locate the shape at the property path qb:dataSet/qb:structure/eg:hasShape from + each qb:Observation instance. +

+ -
- + +
-
-

Security Considerations

-

TODO

-
+
-
-

Privacy Considerations

-

TODO

-
+
+

Security Considerations

+

TODO

+
-
-

Acknowledgements

-

Many people contributed to this document, including members of the RDF Data Shapes Working Group.

-
+
+

Privacy Considerations

+

TODO

+
-
-

Internationalization Considerations

-

TODO

-
+
+

Acknowledgements

+

Many people contributed to this document, including members of the RDF Data Shapes Working Group.

+
-
-
+
+

Internationalization Considerations

+

TODO

+
-
- -
- - +
+
+ +
+ +
+ + + + \ No newline at end of file From 350be060156787c266eb691b30a7c4124219864e Mon Sep 17 00:00:00 2001 From: Simon Steyskal Date: Fri, 15 Aug 2025 08:37:26 +0200 Subject: [PATCH 2/9] style: :art: restore formatting of sections --- shacl12-node-expr/index.html | 3955 ++++++++++++++++------------------ 1 file changed, 1902 insertions(+), 2053 deletions(-) diff --git a/shacl12-node-expr/index.html b/shacl12-node-expr/index.html index 1c48ef39..76469195 100644 --- a/shacl12-node-expr/index.html +++ b/shacl12-node-expr/index.html @@ -682,2081 +682,1932 @@

${escapeHtml(functionName)} (${category})

- -
-

This document describes Shapes Constraint Language (SHACL) Node Expressions.

-

- This specification is published by the - Data Shapes Working Group - . -

-
- -
- -
-

Introduction

-

Node expressions

- -
-

Terminology

-
-
Basic RDF Terminology
-
- This document uses the terms - RDF graph, - RDF triple, - IRI, - literal, - blank node, - node of an RDF graph, - datatype, - RDF term, and - term equality, - and - subject, - predicate, and - object of RDF triples - as defined in RDF 1.2 Concepts and Abstract Syntax [[!rdf12-concepts]]. -
-
-
-
Basic SHACL Terminology
-
- This document uses the terms - focus node, - value, - value node, - constraint, - constraint component, - parameter, - mandatory parameter, - optional parameter, - parameter value, - shape, - node shape, - property - shape, - SHACL property path, - SPARQL property path, - data graph, - shapes graph, - target, - validator, - validation - result, - node - expression, - node expression function, - function - name, - output nodes, - focus graph, - evaluation, - evaluation failure, - conform, - conformance - check, - failure, - SHACL instance, - SHACL subclass, - SHACL type, - SHACL list, - members, - well-formed, - deep copy, - as defined in the SHACL 1.2 Core specification [[!shacl12-core]]. -
-
-
-
-

Document Conventions

-

- Some examples in this document use Turtle [[rdf12-turtle]]. - The reader is expected to be familiar with SHACL [[shacl12-core]] and SPARQL - [[sparql12-query]]. -

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PrefixNamespace
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#
shnex:http://www.w3.org/ns/shnex#
skos:http://www.w3.org/2004/02/skos/core#
sparql:http://www.w3.org/ns/sparql#
xsd:http://www.w3.org/2001/XMLSchema#
ex:http://example.com/ns#
- -

Grey boxes such as this include syntax rules that apply to the shapes graph.

- + +
+

This document describes Shapes Constraint Language (SHACL) Node Expressions.

- true - denotes the RDF term - "true"^^xsd:boolean - . - false - denotes the RDF term - "false"^^xsd:boolean + This specification is published by the + Data Shapes Working Group .

-
-

TODO

-
-
-
-

Getting started with Node Expressions

-

This section is informative.

-

- A SHACL shapes graph can declare node expressions as values of various properties where dynamic - computation is useful, - such as sh:targetNode, sh:values and sh:deactivated. - A node expression is represented by an RDF node and can be evaluated to produce a list of output - nodes. - For example, when used at sh:targetNode, a node expression produces the list - of target nodes of a shape. - When used at sh:values, a node expression produces the derived values for the property - specified by sh:path. -

-

- The following example contains a node expression that states that the target nodes of - the shape ex:EstonianCompanyShape are the instances of ex:Company where - the ex:headQuarterCountry is ex:Estonia. -

-

-

-

-

- The following diagram illustrates how this node expression is interpreted, from a logical point of view. - During validation, a SHACL processor will determine the target nodes of the shape - by evaluating the filterShape expression. - However, the filterShape expression first evaluates its input expression, which is specified via - sh:nodes - and is an instancesOf expression. - This will produce all instances of the given class, ex:Company. - The shnex:filterShape is then applied to all of these instances, to keep only the companies - that conform to the provided shape, by having their headquarters in Estonia. -

-
- Illustration of the data flow between node expressions -
-

- The scenario above can also be expressed using SPARQL select - expressions. - For performance reasons, for example, specific implementations of SHACL node expressions might - internally convert node expressions such as the shnex:filterShape above to SPARQL. -

-

-

-

-

- The next example uses a node expression to compute the values of the property ex:employeeCount - as the number of values of the property ex:employee at each instance of - ex:Company. -

-

-

-

-
- Illustration of the data flow between node expressions computing the employee count -
-

- One difference between this example and the previous examples about sh:targetNode - is that these node expressions are evaluated against a given focus node. - This means that when a data visualization needs to render an instance of ex:Company, - the currently displayed company is the focus node, for which the number of employees - will be fetched. -

-

Clarify when these derived properties can be used (e.g. in sh:path expressions but not as - triples elsewhere)

-
- -
-

Node Expression Syntax

-

- This section introduces the general syntax of SHACL node expressions. -

-

- The term node expression function refers to the kind or type - of a node expression. - For example, sh:FilterShapeExpression is a node expression function, - while a specific instance of this function in the graph is the node expression itself. -

-

- The most basic node expression functions are constant node expressions, which are either - literals or IRIs, and simply evaluate to these constants. - All other node expressions are represented by blank nodes, and come in the following two variations: -

- - -
-

Constant Node Expressions

-

- The node expression functions in this section are called constant node expressions. - They were introduced in the SHACL Core specification and are repeated here to keep this document - self-contained. -

- -
-

IRI Expressions

-

- A node expression that is an IRI is called an IRI expression with the - function name - sh:IRIExpression. -

-

- A node in an RDF graph is a well-formed IRI - expression if it is an IRI. -

-
-
EVALUATION OF IRI EXPRESSIONS
-

- The output nodes of an IRI expression are the list consisting of exactly the - node expression itself: -
-
- evalExpr(expr, focusGraph, focusNode, scope) -> [expr] -

+
+
Basic SHACL Terminology
+
+ This document uses the terms + focus node, + value, + value node, + constraint, + constraint component, + parameter, + mandatory parameter, + optional parameter, + parameter value, + shape, + node shape, + property shape, + SHACL property path, + SPARQL property path, + data graph, + shapes graph, + target, + validator, + validation result, + node expression, + node expression function, + function name, + output nodes, + focus graph, + evaluation, + evaluation failure, + conform, + conformance check, + failure, + SHACL instance, + SHACL subclass, + SHACL type, + SHACL list, + members, + well-formed, + deep copy, + as defined in the SHACL 1.2 Core specification [[!shacl12-core]]. +
- -
-

Literal Expressions

+
+

Document Conventions

- A node expression that is a literal is called a literal expression with the - function name - sh:LiteralExpression. -

-

- A node in an RDF graph is a well-formed - literal expression if it is a literal. + Some examples in this document use Turtle [[rdf12-turtle]]. + The reader is expected to be familiar with SHACL [[shacl12-core]] and SPARQL + [[sparql12-query]].

-
-
EVALUATION OF LITERAL EXPRESSIONS
-

- The output nodes of a literal expression are the list consisting of exactly the - node expression itself: -
-
- evalExpr(expr, focusGraph, focusNode, scope) -> [expr] -

-
-
+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrefixNamespace
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#
shnex:http://www.w3.org/ns/shnex#
skos:http://www.w3.org/2004/02/skos/core#
sparql:http://www.w3.org/ns/sparql#
xsd:http://www.w3.org/2001/XMLSchema#
ex:http://example.com/ns#
-
+

Grey boxes such as this include syntax rules that apply to the shapes graph.

-
-

Node Expressions based on Blank Nodes

-
-

Named Parameter Functions

-

- A named parameter function is a node expression function - that is represented by a blank node that is the subject of at least - one triple where the predicate can be used to uniquely identify the function, - which is known as the key parameter. -

- The evaluation of a named parameter function can produce any of the following: -

- -

- For example, the named parameter function - shnex:FilterShapeExpression - has shnex:filterShape as its key parameter. - In this document, key parameters are marked in bold face. -

-

- Expressions based on named parameter functions often - take other node expressions as arguments, - evaluate those input node expressions, - and then produce a different list of nodes - as output nodes. -

-

The remainder of this section is informative.

- This document includes many examples of named parameter functions, such as - the Estonian Company Shape example. + true + denotes the RDF term + "true"^^xsd:boolean + . + false + denotes the RDF term + "false"^^xsd:boolean + .

-
-

List Parameter Functions

-

- A list parameter function is a node expression function - that is represented by a blank node that is the subject of a single - triple where the object is a SHACL list. - The predicate of this triple is called the list parameter property. -

-

- The evaluation of a list parameter function can produce any of the following: -

- -

- Furthermore, each argument of a list parameter function must evaluate to an individual, - single node, - not to a list of nodes. - If an argument is a node expression, then this node expression must evaluate to - a maximum of one output node. - An evaluation failure must be produced if there is more than one output node. - This is different from named parameter functions, where arguments may produce lists of - multiple nodes. -

-

The remainder of this section is informative.

-

- Note that some named parameter functions — such as - shnex:IntersectionExpression — - also use a SHACL list as an object of the key parameter, similar to list parameter - functions which always have a SHACL list as the object of their list parameter - property. - However, these may produce more than one output nodes, and also accept lists as input nodes. -

-

- The following example uses multiple (imaginary) list parameter functions — - ex:coalesce and ex:concat — to compute the - ex:displayName - of a person as either the value of ex:fullName or (if that doesn't exist) - as a concatenation of ex:firstName, a space, and ex:lastName. -

-

-

+ +
+

Getting started with Node Expressions

+

This section is informative.

+

+ A SHACL shapes graph can declare node expressions as values of various properties where dynamic computation is useful, + such as sh:targetNode, sh:values and sh:deactivated. + A node expression is represented by an RDF node and can be evaluated to produce a list of output nodes. + For example, when used at sh:targetNode, a node expression produces the list + of target nodes of a shape. + When used at sh:values, a node expression produces the derived values for the property specified by sh:path. +

+

+ The following example contains a node expression that states that the target nodes of + the shape ex:EstonianCompanyShape are the instances of ex:Company where + the ex:headQuarterCountry is ex:Estonia. +

+

+

-

-
-
- -
-

Handling of Failures

+

- Node expressions may produce a failure instead of a list of output nodes. - Some node expressions evaluate other, nested node expressions. - For example, If Expressions evaluate nested expressions for - shnex:if, shnex:then and shnex:else. - In general, if any such nested expressions produce a failure then the surrounding - expression also produces the same failure. + The following diagram illustrates how this node expression is interpreted, from a logical point of view. + During validation, a SHACL processor will determine the target nodes of the shape + by evaluating the filterShape expression. + However, the filterShape expression first evaluates its input expression, which is specified via sh:nodes + and is an instancesOf expression. + This will produce all instances of the given class, ex:Company. + The shnex:filterShape is then applied to all of these instances, to keep only the companies + that conform to the provided shape, by having their headquarters in Estonia.

-

The remainder of this section is informative.

+
+ Illustration of the data flow between node expressions +

- Note that this policy impacts the evaluation order of node expressions. - For example, shnex:if expressions are evaluated first and shnex:then - will be evaluated only if the shnex:if has returned ( true ). - Even if the shnex:else branch would produce a failure, the output would - still only be the output nodes of the shnex:then branch. + The scenario above can also be expressed using SPARQL select expressions. + For performance reasons, for example, specific implementations of SHACL node expressions might + internally convert node expressions such as the shnex:filterShape above to SPARQL.

-
- -
- -
-

Node Expressions Library

-

- This section defines all node expression functions that are built into SHACL engines - that implement this specification. -

-

- The syntax definitions of node expression functions that are based on blank nodes - typically use a table of properties that these blank nodes can or must have. - Such blank nodes are only well-formed when they are not the subject of any other - triples, and when none of these properties is used more than once. - The tables may also list SHACL constraints with which the property values are required to conform. - In the tables, mandatory properties are rendered in bold face. -

- -
-

Basic Node Expressions

- -
-

Var Expressions

-

- - A blank node that is the subject of the following properties - is called a var expression with the function name - shnex:VarExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:var - sh:datatype xsd:string
- sh:minLength 1 - 		- The variable name, e.g. "focusNode". -
- -

-
-
EVALUATION OF VAR EXPRESSIONS
-

- Let var be the value of shnex:var in the var expression. - The output nodes of the var expression are computed as follows, in order: -

-
    -
  1. if var is "focusNode" then - evalExpr(expr, focusGraph, focusNode, scope) -> [focusNode] -
    2. -
  2. if var is in the scope then - evalExpr(expr, focusGraph, focusNode, scope) -> [ scope[var] ] -
    3. -
  3. otherwise evalExpr(expr, focusGraph, focusNode, scope) -> []
    4. -
-
-

The remainder of this section is informative.

-

- The following example illustrates the use of a var expression pointing at the current - focus node - to state that the default value of the ex:loves relationship is the current instance of - ex:Person, - creating a self-reference. -

-

-

- -
-

List Expressions

-

- - A blank node that is the subject of the following properties - is called a list expression with the function name - shnex:ListExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
rdf:first - - The first member of the list. -
rdf:rest - Must be a well-formed SHACL list. - - The rest of the list, e.g. rdf:nil. -
- -

-
-
EVALUATION OF LIST EXPRESSIONS
-

- The output nodes of a list expression are the members of the SHACL - list. -

-
-

The remainder of this section is informative.

-

- Note that rdf:nil itself is not a list expression because it will be interpreted - as a IRI expression. - As a result, all well-formed list expressions have at least one member. -

-

- The following example declares a property for instances of rdfs:Class - where the values are derived from the values of the path rdfs:subClassOf* - but with the constants from the list ( owl:Thing rdfs:Resource ) removed using - shnex:minus. -

-

-

+

+
+ Illustration of the data flow between node expressions computing the employee count +
+

+ One difference between this example and the previous examples about sh:targetNode + is that these node expressions are evaluated against a given focus node. + This means that when a data visualization needs to render an instance of ex:Company, + the currently displayed company is the focus node, for which the number of employees + will be fetched. +

+

Clarify when these derived properties can be used (e.g. in sh:path expressions but not as triples elsewhere)

+
+ +
+

Node Expression Syntax

+

+ This section introduces the general syntax of SHACL node expressions. +

+

+ The term node expression function refers to the kind or type + of a node expression. + For example, sh:FilterShapeExpression is a node expression function, + while a specific instance of this function in the graph is the node expression itself. +

+

+ The most basic node expression functions are constant node expressions, which are either + literals or IRIs, and simply evaluate to these constants. + All other node expressions are represented by blank nodes, and come in the following two variations: +

+ -
-

Path Expressions

-

- - A blank node that is the subject of the following properties - is called a path expression with the function name - shnex:PathExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:path - Must be a well-formed SHACL property path. - - The path to get the values from. -
shnex:nodes - Optional, must be a well-formed node expression. - - A node expression producing the focus nodes, defaulting - to the current focus node from the evaluation context. -
- +

+

Constant Node Expressions

+

+ The node expression functions in this section are called constant node expressions. + They were introduced in the SHACL Core specification and are repeated here to keep this document self-contained.

-
-
EVALUATION OF PATH EXPRESSIONS
+ +
+

IRI Expressions

- Let path be the value of shnex:path, - and nodes be the value of shnex:nodes in the path - expression. - If shnex:nodes is not given, nodes is the list consistent of exactly - the focus node. - Let N be the nodes produced by - evalExpr(nodes, focusGraph, focusNode, scope). - The output nodes of the path expression are the list of nodes produced by - concatenating - the value nodes of the path at each node in N. - TODO: Clarify if those can contain duplicates. + A node expression that is an IRI is called an IRI expression with the function name + sh:IRIExpression.

-
-

The remainder of this section is informative.

-

- The following example illustrates the use of a path expression to compute the value - of the property ex:topConceptCount. - The path expression returns the values of skos:hasTopConcept at each - skos:ConceptScheme - and these are processed by the shnex:count to return the - number of top concepts. -

-

-

-

-

TODO: Add second example that uses shnex:nodes

+
+ +
+

Literal Expressions

+

+ A node expression that is a literal is called a literal expression with the function name + sh:LiteralExpression. +

+

+ A node in an RDF graph is a well-formed literal expression if it is a literal. +

+
+
EVALUATION OF LITERAL EXPRESSIONS
+

+ The output nodes of a literal expression are the list consisting of exactly the node expression itself: +
+
+ evalExpr(expr, focusGraph, focusNode, scope) -> [expr] +

+
+
+
-
-

Exists Expressions

-

- - A blank node that is the subject of the following properties - is called an exists expression with the function name - shnex:ExistsExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:exists - A well-formed node expression. - - A node expression. If this evaluates to a list with at least one member - then the output nodes are ( true ); otherwise, the output nodes are - ( false ). -
- -

-
-
EVALUATION OF EXISTS EXPRESSIONS
+
+

Node Expressions based on Blank Nodes

+
+

Named Parameter Functions

- Let exists be the value of shnex:exists in the exists - expression. - Let N be the list of nodes produced by - evalExpr(exists, focusGraph, focusNode, scope). - The output nodes of the exists expression are ( true ) if and only if - N has at least one member; otherwise, the output nodes are ( false ). + A named parameter function is a node expression function + that is represented by a blank node that is the subject of at least + one triple where the predicate can be used to uniquely identify the function, + which is known as the key parameter. +

+ The evaluation of a named parameter function can produce any of the following:

-
-

The remainder of this section is informative.

-

- The Example for shnex:if uses - shnex:exists. -

+ +

+ For example, the named parameter function + shnex:FilterShapeExpression + has shnex:filterShape as its key parameter. + In this document, key parameters are marked in bold face. +

+

+ Expressions based on named parameter functions often + take other node expressions as arguments, + evaluate those input node expressions, + and then produce a different list of nodes + as output nodes. +

+

The remainder of this section is informative.

+

+ This document includes many examples of named parameter functions, such as + the Estonian Company Shape example. +

+
+
+

List Parameter Functions

+

+ A list parameter function is a node expression function + that is represented by a blank node that is the subject of a single + triple where the object is a SHACL list. + The predicate of this triple is called the list parameter property. +

+

+ The evaluation of a list parameter function can produce any of the following: +

+ +

+ Furthermore, each argument of a list parameter function must evaluate to an individual, single node, + not to a list of nodes. + If an argument is a node expression, then this node expression must evaluate to + a maximum of one output node. + An evaluation failure must be produced if there is more than one output node. + This is different from named parameter functions, where arguments may produce lists of multiple nodes. +

+

The remainder of this section is informative.

+

+ Note that some named parameter functions — such as shnex:IntersectionExpression — + also use a SHACL list as an object of the key parameter, similar to list parameter functions which always have a SHACL list as the object of their list parameter property. + However, these may produce more than one output nodes, and also accept lists as input nodes. +

+

+ The following example uses multiple (imaginary) list parameter functions — + ex:coalesce and ex:concat — to compute the ex:displayName + of a person as either the value of ex:fullName or (if that doesn't exist) + as a concatenation of ex:firstName, a space, and ex:lastName. +

+

+

+

+
-
-

If Expressions

-

- - A blank node that is the subject of the following properties - is called an if expression with the function name - shnex:IfExpression: - - - - - - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:if - A well-formed node expression. - - A node expression. The shnex:then branch is returned when the - shnex:if expression - returns true as its only output node, in all other cases - shnex:else. -
shnex:then - A well-formed node expression. - Optional but at least one of shnex:then or shnex:else - is required. - - The node expression that is returned when the shnex:if - evaluated to [true]. -
shnex:else - A well-formed node expression. - Optional but at least one of shnex:then or shnex:else - is required. - - The node expression that is returned when the shnex:if did - not evaluate to [true]. -
- +

+

Handling of Failures

+

+ Node expressions may produce a failure instead of a list of output nodes. + Some node expressions evaluate other, nested node expressions. + For example, If Expressions evaluate nested expressions for + shnex:if, shnex:then and shnex:else. + In general, if any such nested expressions produce a failure then the surrounding + expression also produces the same failure.

-
-
EVALUATION OF IF EXPRESSIONS
-

- Let if be the value of shnex:if, - then be the value of shnex:then, and - else be the value of shnex:else for the if expression. - Let IFs be the nodes produced by - evalExpr(if, focusGraph, focusNode, scope). - If IFs is the list ( true ), then the output nodes of the if - expression - are the nodes produced by evalExpr(then, focusGraph, focusNode, scope), or the - empty list if then has no value. - Otherwise, the output nodes are the nodes produced by - evalExpr(else, focusGraph, focusNode, scope), or the empty list if - else has no value. - Implementations MUST apply lazy evaluation techniques, so the shnex:then or - shnex:else branches are only evaluated when necessary. -

-

The remainder of this section is informative.

-

- The following example illustrates the use of shnex:if to compute the - values of a derived property ex:fillColor that may be queried to - compute the colors of cities on a map. - In the example, instances of ex:City that have a value for ex:capitalOf - will be displayed in "blue", while the others will be "red". -

-

+ Note that this policy impacts the evaluation order of node expressions. + For example, shnex:if expressions are evaluated first and shnex:then + will be evaluated only if the shnex:if has returned ( true ). + Even if the shnex:else branch would produce a failure, the output would + still only be the output nodes of the shnex:then branch.

-
-

List Operator Expressions

- -
-

Distinct Expressions

-

- - A blank node that is the subject of the following properties - is called a distinct expression with the function name - shnex:DistinctExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:distinct - A well-formed node expression. - - The node expression that shall be reduced to its distinct members. -
- -

-
-
EVALUATION OF DISTINCT EXPRESSIONS
+
+

Node Expressions Library

+

+ This section defines all node expression functions that are built into SHACL engines + that implement this specification. +

+

+ The syntax definitions of node expression functions that are based on blank nodes + typically use a table of properties that these blank nodes can or must have. + Such blank nodes are only well-formed when they are not the subject of any other + triples, and when none of these properties is used more than once. + The tables may also list SHACL constraints with which the property values are required to conform. + In the tables, mandatory properties are rendered in bold face. +

+ +
+

Basic Node Expressions

+ +
+

Var Expressions

+

+ + A blank node that is the subject of the following properties + is called a var expression with the function name shnex:VarExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:var + sh:datatype xsd:string
+ sh:minLength 1 + 		+ The variable name, e.g. "focusNode". +
+ +

+
+
EVALUATION OF VAR EXPRESSIONS
+

+ Let var be the value of shnex:var in the var expression. + The output nodes of the var expression are computed as follows, in order: +

+
    +
  1. if var is "focusNode" then evalExpr(expr, focusGraph, focusNode, scope) -> [focusNode]
    2. +
  2. if var is in the scope then evalExpr(expr, focusGraph, focusNode, scope) -> [ scope[var] ]
    3. +
  3. otherwise evalExpr(expr, focusGraph, focusNode, scope) -> []
    4. +
+
+

The remainder of this section is informative.

- Let distinct be the value of shnex:distinct in the distinct - expression. - Let input be the output nodes of - evalExpr(distinct, focusGraph, focusNode, scope). - The output nodes of the distinct expression are the list of nodes in - input - in the same order but with duplicates eliminated (the first occurences of each node shall be - kept, the others removed). - Nodes are compared using term equality, i.e. "01"^^xsd:integer is distinct - from "1"^^xsd:integer. + The following example illustrates the use of a var expression pointing at the current focus node + to state that the default value of the ex:loves relationship is the current instance of ex:Person, + creating a self-reference.

-
-

The remainder of this section is informative.

-

- The following example declares a derived property ex:superClassesIncludingRoot - that is computed as the union of the (transitive) values of - rdfs:subClassOf - and the list expression ( rdfs:Resource ). - Since the asserted values of rdfs:subClassOf may already include - rdfs:Resource - (for example, due to an active inference engine on the data graph), shnex:distinct will - make - sure that the output nodes do not include rdfs:Resource twice. -

-

-

+ +
+

List Expressions

+

+ + A blank node that is the subject of the following properties + is called a list expression with the function name shnex:ListExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
rdf:first + + The first member of the list. +
rdf:rest + Must be a well-formed SHACL list. + + The rest of the list, e.g. rdf:nil. +
+ +

+
+
EVALUATION OF LIST EXPRESSIONS
+

+ The output nodes of a list expression are the members of the SHACL list. +

- -

-
- -
-

Intersection Expressions

-

- - A blank node that is the subject of the following properties - is called an intersection expression with the function name - shnex:IntersectionExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:intersection - A well-formed SHACL list where each member is a - well-formed node expression. - - The node expressions that shall be intersected. -
- -

-
-
EVALUATION OF INTERSECTION EXPRESSIONS
+

The remainder of this section is informative.

- Let members be the members of the value of - shnex:intersection in the intersection expression. - The output nodes of the intersection expression are the nodes that form the - intersection of the output nodes - produced by each node expression NE in members, using - evalExpr(NE, focusGraph, focusNode, scope). - Nodes must be equal using term equality, i.e. "01"^^xsd:integer is distinct - from "1"^^xsd:integer. + Note that rdf:nil itself is not a list expression because it will be interpreted + as a IRI expression. + As a result, all well-formed list expressions have at least one member.

-
-

The remainder of this section is informative.

-

- The following example uses shnex:intersection as a sh:targetNode node - expression. - This shape will target all nodes that are SHACL instances of ex:Australian and - ex:German at the same time. -

-

-

+ +
+

Path Expressions

+

+ + A blank node that is the subject of the following properties + is called a path expression with the function name shnex:PathExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:path + Must be a well-formed SHACL property path. + + The path to get the values from. +
shnex:nodes + Optional, must be a well-formed node expression. + + A node expression producing the focus nodes, defaulting + to the current focus node from the evaluation context. +
+ +

+
+
EVALUATION OF PATH EXPRESSIONS
+

+ Let path be the value of shnex:path, + and nodes be the value of shnex:nodes in the path expression. + If shnex:nodes is not given, nodes is the list consistent of exactly the focus node. + Let N be the nodes produced by evalExpr(nodes, focusGraph, focusNode, scope). + The output nodes of the path expression are the list of nodes produced by concatenating + the value nodes of the path at each node in N. + TODO: Clarify if those can contain duplicates. +

- -

+

The remainder of this section is informative.

+

+ The following example illustrates the use of a path expression to compute the value + of the property ex:topConceptCount. + The path expression returns the values of skos:hasTopConcept at each skos:ConceptScheme + and these are processed by the shnex:count to return the + number of top concepts. +

+

+

+

+

TODO: Add second example that uses shnex:nodes

+
+ +
+

Exists Expressions

+

+ + A blank node that is the subject of the following properties + is called an exists expression with the function name shnex:ExistsExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:exists + A well-formed node expression. + + A node expression. If this evaluates to a list with at least one member + then the output nodes are ( true ); otherwise, the output nodes are ( false ). +
+ +

+
+
EVALUATION OF EXISTS EXPRESSIONS
+

+ Let exists be the value of shnex:exists in the exists expression. + Let N be the list of nodes produced by evalExpr(exists, focusGraph, focusNode, scope). + The output nodes of the exists expression are ( true ) if and only if + N has at least one member; otherwise, the output nodes are ( false ). +

+
+

The remainder of this section is informative.

+

+ The Example for shnex:if uses shnex:exists. +

+
+ +
+

If Expressions

+

+ + A blank node that is the subject of the following properties + is called an if expression with the function name shnex:IfExpression: + + + + + + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:if + A well-formed node expression. + + A node expression. The shnex:then branch is returned when the shnex:if expression + returns true as its only output node, in all other cases shnex:else. +
shnex:then + A well-formed node expression. + Optional but at least one of shnex:then or shnex:else is required. + + The node expression that is returned when the shnex:if evaluated to [true]. +
shnex:else + A well-formed node expression. + Optional but at least one of shnex:then or shnex:else is required. + + The node expression that is returned when the shnex:if did not evaluate to [true]. +
+ +

+
+
EVALUATION OF IF EXPRESSIONS
+

+ Let if be the value of shnex:if, + then be the value of shnex:then, and + else be the value of shnex:else for the if expression. + Let IFs be the nodes produced by evalExpr(if, focusGraph, focusNode, scope). + If IFs is the list ( true ), then the output nodes of the if expression + are the nodes produced by evalExpr(then, focusGraph, focusNode, scope), or the empty list if then has no value. + Otherwise, the output nodes are the nodes produced by evalExpr(else, focusGraph, focusNode, scope), or the empty list if else has no value. + Implementations MUST apply lazy evaluation techniques, so the shnex:then or + shnex:else branches are only evaluated when necessary. +

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:if to compute the + values of a derived property ex:fillColor that may be queried to + compute the colors of cities on a map. + In the example, instances of ex:City that have a value for ex:capitalOf + will be displayed in "blue", while the others will be "red". +

+

+

+

+
+
-
-

Union Expressions

-

- - A blank node that is the subject of the following properties - is called a union expression with the function name - shnex:UnionExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:union - A well-formed SHACL list where each member is a - well-formed node expression. - - The node expressions that shall be unioned. -
- -

-
-
EVALUATION OF UNION EXPRESSIONS
+
+

List Operator Expressions

+ +
+

Distinct Expressions

+

+ + A blank node that is the subject of the following properties + is called a distinct expression with the function name shnex:DistinctExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:distinct + A well-formed node expression. + + The node expression that shall be reduced to its distinct members. +
+ +

+
+
EVALUATION OF DISTINCT EXPRESSIONS
+

+ Let distinct be the value of shnex:distinct in the distinct expression. + Let input be the output nodes of evalExpr(distinct, focusGraph, focusNode, scope). + The output nodes of the distinct expression are the list of nodes in input + in the same order but with duplicates eliminated (the first occurences of each node shall be kept, the others removed). + Nodes are compared using term equality, i.e. "01"^^xsd:integer is distinct from "1"^^xsd:integer. +

+
+

The remainder of this section is informative.

+

+ The following example declares a derived property ex:superClassesIncludingRoot + that is computed as the union of the (transitive) values of rdfs:subClassOf + and the list expression ( rdfs:Resource ). + Since the asserted values of rdfs:subClassOf may already include rdfs:Resource + (for example, due to an active inference engine on the data graph), shnex:distinct will make + sure that the output nodes do not include rdfs:Resource twice. +

+

+

+

+
+ +
+

Intersection Expressions

+

+ + A blank node that is the subject of the following properties + is called an intersection expression with the function name shnex:IntersectionExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:intersection + A well-formed SHACL list where each member is a well-formed node expression. + + The node expressions that shall be intersected. +
+ +

+
+
EVALUATION OF INTERSECTION EXPRESSIONS
+

+ Let members be the members of the value of shnex:intersection in the intersection expression. + The output nodes of the intersection expression are the nodes that form the intersection of the output nodes + produced by each node expression NE in members, using evalExpr(NE, focusGraph, focusNode, scope). + Nodes must be equal using term equality, i.e. "01"^^xsd:integer is distinct from "1"^^xsd:integer. +

+
+

The remainder of this section is informative.

+

+ The following example uses shnex:intersection as a sh:targetNode node expression. + This shape will target all nodes that are SHACL instances of ex:Australian and + ex:German at the same time. +

+

+

+

+
+ +
+

Union Expressions

+

+ + A blank node that is the subject of the following properties + is called a union expression with the function name shnex:UnionExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:union + A well-formed SHACL list where each member is a well-formed node expression. + + The node expressions that shall be unioned. +
+ +

+
+
EVALUATION OF UNION EXPRESSIONS
+

+ Let members be the members of the value of shnex:union in the union expression. + The output nodes of the union expression are the concatenation of all output nodes + for each node expression NE in members, using evalExpr(NE, focusGraph, focusNode, scope). + The order is preserved, evaluating the members from left to right and keeping the order of each list of output nodes. +

+
+

The remainder of this section is informative.

+

+ Note that a union expression may produce duplicate output nodes if the individual output nodes overlap. + Use shnex:distinct to eliminate duplicates. +

+

+ The Example for shnex:distinct uses shnex:union. +

+
+ +
+

Minus Expressions

+

+ + A blank node that is the subject of the following properties + is called a minus expression with the function name shnex:MinusExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:minus + A well-formed node expression. + + The nodes that shall be removed from the shnex:nodes. +
shnex:nodes + A well-formed node expression. + + The input nodes. +
+ +

+
+
EVALUATION OF MINUS EXPRESSIONS
+

+ Let minus be the value of shnex:minus + and nodes be the value of shnex:nodes in the minus expression. + Let M be the output nodes of evalExpr(minus, focusGraph, focusNode, scope). + Let N be the output nodes of evalExpr(nodes, focusGraph, focusNode, scope). + The output nodes of the minus expression are the nodes in N + except those that are also in M, preserving the order of N. + Nodes must be equal using term equality, i.e. "01"^^xsd:integer is distinct from "1"^^xsd:integer. +

+
+

The remainder of this section is informative.

+

+ The List Expression example uses shnex:minus. +

+
+ +
+

FilterShape Expressions

+

+ + A blank node that is the subject of the following properties + is called a filterShape expression with the function name shnex:FilterShapeExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:filterShape + A well-formed shape. + + The shape that all input nodes need to conform to. +
shnex:nodes + A well-formed node expression. + + A node expression producing the nodes that are validated. +
+ +

+
+
EVALUATION OF FILTERSHAPE EXPRESSIONS
+

+ Let filterShape be the value of shnex:filterShape, + and nodes be the value of shnex:nodes in a filterShape expression. + The output nodes of the filterShape expression are the output nodes of + evalExpr(nodes, focusGraph, focusNode, scope) except those that do not conform to + the shape filterShape, preserving the order in the list. +

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:filterShape to return a subset + of values of the ex:child property where the ex:gender property + has the value "male". +

+

+

+

+
+ +
+

Limit Expressions

+

+ + A blank node that is the subject of the following properties + is called a limit expression with the function name shnex:LimitExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:limit + sh:datatype xsd:integer
+ sh:minInclusive 0 + 		+ The maximum number of nodes that shall be returned. +
shnex:nodes + A well-formed node expression. + + The input nodes. +
+ +

+
+
EVALUATION OF LIMIT EXPRESSIONS
+

+ Let limit be the value of shnex:limit + and nodes be the value of shnex:nodes in the limit expression. + Let N be the output nodes of evalExpr(nodes, focusGraph, focusNode, scope). + The output nodes of the limit expression are the first limit nodes in N + from left to right, in the same order. +

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:limit to compute the + values of a derived property ex:oldestChildren to be a sub-list of + values of ex:child at the current focus node (which is an instance of + the class ex:Person). + The values are computed by first fetching the values of ex:child, then + ordering them by their ex:dateOfBirth, and finally getting only + 2 of these children at most. +

+

+

+

+
+ +
+

Offset Expressions

+

+ + A blank node that is the subject of the following properties + is called an offset expression with the function name shnex:OffsetExpression: + + + + + + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:offset + sh:datatype xsd:integer
+ sh:minInclusive 0 + 		+ The number of nodes that shall be skipped from the shnex:nodes. +
shnex:nodes + A well-formed node expression. + + The input nodes. +
+ +

+
+
EVALUATION OF OFFSET EXPRESSIONS
+

+ Let offset be the value of shnex:offset + and nodes be the value of shnex:nodes in the offset expression. + Let N be the output nodes of evalExpr(nodes, focusGraph, focusNode, scope). + The output nodes of the offset expression are the nodes in N + except for the first offset nodes from left to right, in the same order. +

+
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:offset to compute the + values of a derived property ex:remainingChildren to be a sub-list of + values of ex:child at the current focus node (which is an instance of + the class ex:Person). + The values are computed by first fetching the values of ex:child, then + ordering them by their ex:dateOfBirth, and finally skipping the first + of these children. +

- Let members be the members of the value of shnex:union - in the union expression. - The output nodes of the union expression are the concatenation of all output - nodes - for each node expression NE in members, using - evalExpr(NE, focusGraph, focusNode, scope). - The order is preserved, evaluating the members from left to right and keeping the - order of each list of output nodes. +

-
-

The remainder of this section is informative.

-

- Note that a union expression may produce duplicate output nodes if the individual - output nodes overlap. - Use shnex:distinct to eliminate duplicates. -

-

- The Example for shnex:distinct uses - shnex:union. -

-
+
-
-

Minus Expressions

-

- - A blank node that is the subject of the following properties - is called a minus expression with the function name - shnex:MinusExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:minus - A well-formed node expression. - - The nodes that shall be removed from the shnex:nodes. -
shnex:nodes - A well-formed node expression. - - The input nodes. -
- -

-
-
EVALUATION OF MINUS EXPRESSIONS
+
+

OrderBy Expressions

+

TODO: This should be cleaned up from the SHACL-AF definition and requires thought

- Let minus be the value of shnex:minus - and nodes be the value of shnex:nodes in the minus - expression. - Let M be the output nodes of - evalExpr(minus, focusGraph, focusNode, scope). - Let N be the output nodes of - evalExpr(nodes, focusGraph, focusNode, scope). - The output nodes of the minus expression are the nodes in N - except those that are also in M, preserving the order of N. - Nodes must be equal using term equality, i.e. "01"^^xsd:integer is distinct - from "1"^^xsd:integer. + The Example of shnex:limit also illustrates shnex:orderBy.

-
-

The remainder of this section is informative.

-

- The List Expression example uses shnex:minus. -

+
+
-
-

FilterShape Expressions

-

- - A blank node that is the subject of the following properties - is called a filterShape expression with the function name - shnex:FilterShapeExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:filterShape - A well-formed shape. - - The shape that all input nodes need to conform to. -
shnex:nodes - A well-formed node expression. - - A node expression producing the nodes that are validated. -
- -

-
-
EVALUATION OF FILTERSHAPE EXPRESSIONS
+
+

Aggregation Expressions

+ +
+

Count Expressions

+

+ + A blank node that is the subject of the following properties + is called a count expression with the function name shnex:CountExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:count + A well-formed node expression. + + The input nodes that shall be counted. +
+ +

+
+
EVALUATION OF COUNT EXPRESSIONS
+

+ Let count be the value of shnex:count in the count expression. + Let N be the output nodes of evalExpr(count, focusGraph, focusNode, scope). + The output nodes of the count expression is the list consisting of exactly one + xsd:integer literal that is computed as the length of N. +

+
+

The remainder of this section is informative.

- Let filterShape be the value of shnex:filterShape, - and nodes be the value of shnex:nodes in a filterShape - expression. - The output nodes of the filterShape expression are the output nodes of - evalExpr(nodes, focusGraph, focusNode, scope) except those that do not - conform to - the shape filterShape, preserving the order in the list. + The following example illustrates the use of shnex:count to derive a property + ex:topConceptCount as the number of values of the skos:hasTopConcept + property in a skos:ConceptScheme.

-
-

The remainder of this section is informative.

-

- The following example illustrates the use of shnex:filterShape to return a subset - of values of the ex:child property where the ex:gender property - has the value "male". -

-

-

+ +
+

Min Expressions

+

+ + A blank node that is the subject of the following properties + is called a min expression with the function name shnex:MinExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:min + A well-formed node expression. + + The input nodes from which the minimum value shall be returned. +
+ +

+
+
EVALUATION OF MIN EXPRESSIONS
+

+ Let min be the value of shnex:min in the min expression. + Let N be the output nodes of evalExpr(min, focusGraph, focusNode, scope). + The output nodes of the min expression is the list consisting of at most one node + that is computed as the minimum value from N. + Clarify exactly how that is computed, maybe via reference to SPARQL MIN +

- -

-
- -
-

Limit Expressions

-

- - A blank node that is the subject of the following properties - is called a limit expression with the function name - shnex:LimitExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:limit - sh:datatype xsd:integer
- sh:minInclusive 0 - 		- The maximum number of nodes that shall be returned. -
shnex:nodes - A well-formed node expression. - - The input nodes. -
- -

-
-
EVALUATION OF LIMIT EXPRESSIONS
+

The remainder of this section is informative.

+

+ The following example illustrates the use of shnex:min to derive a property + ex:minStartDate as the smallest value of the values that can be reached using the + property path ex:exployee/ex:startDate. + In other words, it walks through all employees of the given company and returns the earliest + date on which an employee started. +

- Let limit be the value of shnex:limit - and nodes be the value of shnex:nodes in the limit - expression. - Let N be the output nodes of - evalExpr(nodes, focusGraph, focusNode, scope). - The output nodes of the limit expression are the first limit - nodes in N - from left to right, in the same order. +

-
-

The remainder of this section is informative.

-

- The following example illustrates the use of shnex:limit to compute the - values of a derived property ex:oldestChildren to be a sub-list of - values of ex:child at the current focus node (which is an instance of - the class ex:Person). - The values are computed by first fetching the values of ex:child, then - ordering them by their ex:dateOfBirth, and finally getting only - 2 of these children at most. -

-

-

+ +
+

Max Expressions

+

+ + A blank node that is the subject of the following properties + is called a max expression with the function name shnex:MaxExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:max + A well-formed node expression. + + The input nodes from which the maximum value shall be returned. +
+ +

+
+
EVALUATION OF MAX EXPRESSIONS
+

+ Let max be the value of shnex:max in the max expression. + Let N be the output nodes of evalExpr(max, focusGraph, focusNode, scope). + The output nodes of the max expression is the list consisting of at most one node + that is computed as the maximum value from N. + Clarify exactly how that is computed, maybe via reference to SPARQL MAX +

- -

-
- -
-

Offset Expressions

-

- - A blank node that is the subject of the following properties - is called an offset expression with the function name - shnex:OffsetExpression: - - - - - - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:offset - sh:datatype xsd:integer
- sh:minInclusive 0 - 		- The number of nodes that shall be skipped from the shnex:nodes. -
shnex:nodes - A well-formed node expression. - - The input nodes. -
- -

-
-
EVALUATION OF OFFSET EXPRESSIONS
+

The remainder of this section is informative.

- Let offset be the value of shnex:offset - and nodes be the value of shnex:nodes in the offset - expression. - Let N be the output nodes of - evalExpr(nodes, focusGraph, focusNode, scope). - The output nodes of the offset expression are the nodes in N - except for the first offset nodes from left to right, in the same order. + The Example for shnex:min can be easily adapted + for shnex:max.

-
-

The remainder of this section is informative.

-

- The following example illustrates the use of shnex:offset to compute the - values of a derived property ex:remainingChildren to be a sub-list of - values of ex:child at the current focus node (which is an instance of - the class ex:Person). - The values are computed by first fetching the values of ex:child, then - ordering them by their ex:dateOfBirth, and finally skipping the first - of these children. -

-

-

+ +
+

Sum Expressions

+

+ + A blank node that is the subject of the following properties + is called a sum expression with the function name shnex:SumExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:sum + A well-formed node expression. + + The input nodes from which the sum shall be returned. +
+ +

+
+
EVALUATION OF SUM EXPRESSIONS
+

+ Let sum be the value of shnex:sum in the sum expression. + Let N be the output nodes of evalExpr(sum, focusGraph, focusNode, scope). + The output nodes of the sum expression is the list consisting of exactly one node + that is computed as the sum of all nodes from N. + Clarify exactly how that is computed, maybe via reference to SPARQL SUM +

- -

+

The remainder of this section is informative.

+

+ Note that shnex:sum needs to be used with care and may be often misunderstood, + when used with property paths. + The problem is that when a path expression is used as input to a sum expression, + the path expression will have eliminated duplicates before they can be processed by the shnex:sum. + As a result, only the distinct values will be added up. +

+

TODO: Find good example, or drop the feature if none makes sense

+
+
-
-

OrderBy Expressions

-

TODO: This should be cleaned up from the SHACL-AF definition and requires thought

+
+

Miscellaneous Node Expressions

- The Example of shnex:limit also illustrates - shnex:orderBy. -

+ This section enumerates node expression functions that did not fit into other categories. +

+ +
+

InstancesOf Expressions

+

+ + A blank node that is the subject of the following properties + is called an instancesOf expression with the function name shnex:InstancesOfExpression: + + + + + + + + + + + + + +
PropertyConstraintsDescription
shnex:instancesOf + sh:nodeKind sh:IRI + + The class that the output nodes must be instances of. +
+ +

+
+
EVALUATION OF INSTANCESOF EXPRESSIONS
+

+ Let type be the value of shnex:instancesOf in an instancesOf expression. + The output nodes of the instancesOf expression are the nodes that are SHACL instances + of type in the focus graph. +

+
+

The remainder of this section is informative.

+

+ Note that the definition of SHACL instance includes instances of subclasses of the given class. + So if the focus graph contains ex:SubClass rdfs:subClassOf ex:SuperClass and ex:SubInstance a ex:SubClass + then ex:SubInstance will also be returned as instance of ex:SuperClass. +

+

+ The interpretation of shnex:instancesOf is similar to sh:targetClass and sh:class. +

+

+ Users of this node expression function should be aware that the list of output nodes may be very large. +

+

+ The Example for shnex:intersection uses shnex:instanceOf. +

+
+
+
+

SPARQL Functions

+

+ This section introduces SHACL [[sparql12-query]] that can be used in node expressions. +

-
-

Aggregation Expressions

- -
-

Count Expressions

-

- - A blank node that is the subject of the following properties - is called a count expression with the function name - shnex:CountExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:count - A well-formed node expression. - - The input nodes that shall be counted. -
- +

+ +
+

Constraint Components

+

+ This section introduces SHACL constraint components that operate on node expressions. +

+ +
+

sh:expression

+

+ Based on node expressions, this section introduces a constraint component called + expression constraints. + Expression constraints can be used in any shape to declare the condition that the + node expression specified via sh:expression has true as its only output node. + The evaluation of these node expressions is repeated for all value nodes of the shape + as the focus node.

-
-
EVALUATION OF COUNT EXPRESSIONS
-

- Let count be the value of shnex:count in the count - expression. - Let N be the output nodes of - evalExpr(count, focusGraph, focusNode, scope). - The output nodes of the count expression is the list consisting of exactly one - xsd:integer literal that is computed as the length of N. -

+

+ Constraint Component IRI: sh:ExpressionConstraintComponent +

+ +
Parameters:
+ + + + + + + + + + + + + +
PropertySummary and Syntax Rules
sh:expression + The node expression that must return true. + The values of sh:expression at a + shape must be well-formed node expressions. +
+
+
TEXTUAL DEFINITION
+
+ Let $expr be a value of sh:expression. + For each value node v + where evalExpr(expr, data graph, focusNode, {value: v}) + does not return the list consisting of exactly true as its output nodes, + there is a validation result that has v as its sh:value + and a deep copy of $expr in the results graph as its sh:sourceConstraint. +

The remainder of this section is informative.

- The following example illustrates the use of shnex:count to derive a property - ex:topConceptCount as the number of values of the skos:hasTopConcept - property in a skos:ConceptScheme. + Note that the scope in the evaluation of expression constraints contains the variable value + for the current value node while the variable focusNode is the focus node.

-

- -
-

Min Expressions

-

- - A blank node that is the subject of the following properties - is called a min expression with the function name - shnex:MinExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:min - A well-formed node expression. - - The input nodes from which the minimum value shall be returned. -
- -

-
-
EVALUATION OF MIN EXPRESSIONS
-

- Let min be the value of shnex:min in the min expression. - Let N be the output nodes of - evalExpr(min, focusGraph, focusNode, scope). - The output nodes of the min expression is the list consisting of at most one - node - that is computed as the minimum value from N. - Clarify exactly how that is computed, maybe via reference to SPARQL - MIN -

-
-

The remainder of this section is informative.

-

- The following example illustrates the use of shnex:min to derive a property - ex:minStartDate as the smallest value of the values that can be reached using the - property path ex:exployee/ex:startDate. - In other words, it walks through all employees of the given company and returns the earliest - date on which an employee started. -

-

-

-

-
-

Max Expressions

-

- - A blank node that is the subject of the following properties - is called a max expression with the function name - shnex:MaxExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:max - A well-formed node expression. - - The input nodes from which the maximum value shall be returned. -
- -

-
-
EVALUATION OF MAX EXPRESSIONS
-

- Let max be the value of shnex:max in the max expression. - Let N be the output nodes of - evalExpr(max, focusGraph, focusNode, scope). - The output nodes of the max expression is the list consisting of at most one - node - that is computed as the maximum value from N. - Clarify exactly how that is computed, maybe via reference to SPARQL - MAX -

-
-

The remainder of this section is informative.

+
+

sh:nodeByExpression

- The Example for shnex:min can be easily adapted - for shnex:max. -

-
- -
-

Sum Expressions

-

- - A blank node that is the subject of the following properties - is called a sum expression with the function name - shnex:SumExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:sum - A well-formed node expression. - - The input nodes from which the sum shall be returned. -
- + sh:nodeByExpression specifies the condition that each value node conforms to the + node shapes produced by a node expression. + The evaluation of these node expressions is repeated for all value nodes of the shape + as the focus node.

-
-
EVALUATION OF SUM EXPRESSIONS
-

- Let sum be the value of shnex:sum in the sum expression. - Let N be the output nodes of - evalExpr(sum, focusGraph, focusNode, scope). - The output nodes of the sum expression is the list consisting of exactly one - node - that is computed as the sum of all nodes from N. - Clarify exactly how that is computed, maybe via reference to SPARQL - SUM -

-
-

The remainder of this section is informative.

- Note that shnex:sum needs to be used with care and may be often misunderstood, - when used with property paths. - The problem is that when a path expression is used as input to a sum expression, - the path expression will have eliminated duplicates before they can be processed by the - shnex:sum. - As a result, only the distinct values will be added up. -

-

TODO: Find good example, or drop the feature if none makes sense

-
- -
- - - -
-

Miscellaneous Node Expressions

-

- This section enumerates node expression functions that did not fit into other categories. -

- -
-

InstancesOf Expressions

-

- - A blank node that is the subject of the following properties - is called an instancesOf expression with the function name - shnex:InstancesOfExpression: - - - - - - - - - - - - - -
PropertyConstraintsDescription
shnex:instancesOf - sh:nodeKind sh:IRI - - The class that the output nodes must be instances of. -
- -

-
-
EVALUATION OF INSTANCESOF EXPRESSIONS
-

- Let type be the value of shnex:instancesOf in an instancesOf - expression. - The output nodes of the instancesOf expression are the nodes that are - SHACL instances - of type in the focus graph. -

+ Constraint Component IRI: sh:NodeByExpressionConstraintComponent +

+ +
Parameters:
+ + + + + + + + + + + + + +
PropertySummary and Syntax Rules
sh:nodeByExpression + The node shapes that all value nodes need to conform to. + The values of sh:nodeByExpression in a shape must be well-formed node expressions. +
+
+
TEXTUAL DEFINITION
+
+ Let $expr be a value of sh:nodeByExpression. + For each value node v: perform a conformance check of + v against each output node of evalExpr(expr, + data graph, v, {}) s. A failure + MUST be produced if the conformance check of v against + s produces a failure. Otherwise, if v does + not conform to s, there is a validation result + with v as sh:value and a deep copy of + s as sh:sourceConstraint. +

The remainder of this section is informative.

- Note that the definition of SHACL instance includes instances of subclasses of the - given class. - So if the focus graph contains ex:SubClass rdfs:subClassOf ex:SuperClass and - ex:SubInstance a ex:SubClass - then ex:SubInstance will also be returned as instance of ex:SuperClass. + sh:nodeByExpression functions similarly to sh:node, but instead of referencing a fixed node shape, + a referenced node expression is used to dynamically compute the set of node shapes to which each value node must conform.

- The interpretation of shnex:instancesOf is similar to sh:targetClass and - sh:class. + There are three key differences between sh:nodeByExpression and sh:node: +

    +
  1. + sh:nodeByExpression references a node expression instead of a fixed node shape as sh:node does. +
    2. +
  2. + sh:nodeByExpression cannot reference a node shape that is a blank node as a value like sh:node can, + as a blank node would be interpreted as a node expression. +
    3. +
  3. + Results generated by sh:nodeByExpression additionally include a value for `sh:sourceConstraint`. +
    4. +

- Users of this node expression function should be aware that the list of output nodes may be very - large. + Note that sh:node and sh:nodeByExpression exhibit the same behavior when given a value that is an IRI of a node shape. + In this case, sh:node directly validates against the specified node shape, whereas sh:nodeByExpression interprets the IRI + as an IRI expression that evaluates to a set containing the same node shape.

- The Example for shnex:intersection uses - shnex:instanceOf. + The following example demonstrates how sh:nodeByExpression could be used in the context of the W3C Data Cube Vocabulary. + Building upon examples 5 and 6 from the Data Cube Vocabulary documentation, Data Structure Definition is extended with the property eg:hasShape, + which links to an associated node shape to which relevant qb:Observation instances must conform. + To validate that every qb:Observation instance conforms to the appropriate shape, sh:nodeByExpression with a Path Expression + is used to locate the shape at the property path qb:dataSet/qb:structure/eg:hasShape from each qb:Observation instance.

-
- -
- -
-
-

SPARQL Functions

-

- This section introduces SHACL [[sparql12-query]] that can be used in node expressions. -

- -
-
-

Constraint Components

-

- This section introduces SHACL constraint components that operate on node expressions. -

- -
-

sh:expression

-

- Based on node expressions, this section introduces a constraint component called - expression constraints. - Expression constraints can be used in any shape to declare the condition that the - node expression specified via sh:expression has true as its only output - node. - The evaluation of these node expressions is repeated for all value nodes of the shape - as the focus node. -

-

- Constraint Component IRI: - sh:ExpressionConstraintComponent -

- -
Parameters:
- - - - - - - - - - - - - -
PropertySummary and Syntax Rules
sh:expression - The node expression that must return true. - The values of sh:expression at - a - shape must be well-formed node expressions. -
-
-
TEXTUAL DEFINITION
-
- Let $expr be a value of sh:expression. - For each value node v - where evalExpr(expr, data graph, focusNode, {value: v}) - does not return the list consisting of exactly true as its output nodes, - there is a validation result that has v as its sh:value - and a deep copy of $expr in the results graph as its - sh:sourceConstraint. -
-
-

The remainder of this section is informative.

-

- Note that the scope in the evaluation of expression constraints contains the variable value - for the current value node while the variable focusNode is the focus node. -

-

- The following example uses some SPARQL-based node expressions to declare - the constraint that the values of ex:ibanNumber must start with the same two (upper-case) - letters as - the values of the path ex:country/ex:code. -

- -
- -
-

sh:nodeByExpression

-

- sh:nodeByExpression specifies the condition that each value node conforms to the - node shapes produced by a node expression. - The evaluation of these node expressions is repeated for all value nodes of the shape - as the focus node. -

-

- Constraint Component IRI: - sh:NodeByExpressionConstraintComponent -

- -
Parameters:
- - - - - - - - - - - - - -
PropertySummary and Syntax Rules
sh:nodeByExpression - The node shapes that all value nodes need to conform to. - The values of - sh:nodeByExpression in a shape must be well-formed node - expressions. -
-
-
TEXTUAL DEFINITION
-
- Let $expr be a value of sh:nodeByExpression. - For each value node v: perform a conformance check of - v against each output node of evalExpr(expr, - data graph, v, {}) s. A failure - MUST be produced if the conformance check of v against - s produces a failure. Otherwise, if v does - not conform to s, there is a validation result - with v as sh:value and a deep copy of - s as sh:sourceConstraint. -
-
-

The remainder of this section is informative.

-

- sh:nodeByExpression functions similarly to sh:node, but instead of referencing - a fixed node shape, - a referenced node expression is used to dynamically compute the set of node shapes to - which each value node must conform. -

-

- There are three key differences between sh:nodeByExpression and sh:node: -

    -
  1. - sh:nodeByExpression references a node expression instead of a fixed node - shape as sh:node does. -
    2. -
  2. - sh:nodeByExpression cannot reference a node shape that is a blank node as - a value like sh:node can, - as a blank node would be interpreted as a node expression. -
    3. -
  3. - Results generated by sh:nodeByExpression additionally include a value for - `sh:sourceConstraint`. -
    4. -
-

-

- Note that sh:node and sh:nodeByExpression exhibit the same behavior when given - a value that is an IRI of a node shape. - In this case, sh:node directly validates against the specified node shape, whereas - sh:nodeByExpression interprets the IRI - as an IRI expression that evaluates to a set containing the same node shape. -

-

- The following example demonstrates how sh:nodeByExpression could be used in the context of - the W3C Data Cube Vocabulary. - Building upon examples 5 and 6 from the Data Cube Vocabulary documentation, Data Structure Definition is - extended with the property eg:hasShape, - which links to an associated node shape to which relevant qb:Observation instances - must conform. - To validate that every qb:Observation instance conforms to the appropriate shape, - sh:nodeByExpression with a Path Expression - is used to locate the shape at the property path qb:dataSet/qb:structure/eg:hasShape from - each qb:Observation instance. -

- + +
+
-
- -
-

Security Considerations

-

TODO

-
- -
-

Privacy Considerations

-

TODO

-
- -
-

Acknowledgements

-

Many people contributed to this document, including members of the RDF Data Shapes Working Group.

-
+
+

Security Considerations

+

TODO

+
-
-

Internationalization Considerations

-

TODO

-
+
+

Privacy Considerations

+

TODO

+
-
-
+
+

Acknowledgements

+

Many people contributed to this document, including members of the RDF Data Shapes Working Group.

+
-
- -
+
+

Internationalization Considerations

+

TODO

+
- +
+
- \ No newline at end of file +
+ +
+ + From 0cdd7099c56db0e8f4c4453fb02c139af3a1ae61 Mon Sep 17 00:00:00 2001 From: simonstey Date: Sat, 16 Aug 2025 07:29:02 +0200 Subject: [PATCH 3/9] =?UTF-8?q?Import=20SPARQL=20function=20triples=20into?= =?UTF-8?q?=20shnex-sparql.ttl=20=E2=80=94=20labels,=20descriptions,=20cat?= =?UTF-8?q?egories,=20spec=20links.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- shacl12-vocabularies/shnex-sparql.ttl | 814 ++++++++++++++++++++++++++ 1 file changed, 814 insertions(+) create mode 100644 shacl12-vocabularies/shnex-sparql.ttl diff --git a/shacl12-vocabularies/shnex-sparql.ttl b/shacl12-vocabularies/shnex-sparql.ttl new file mode 100644 index 00000000..b94d30a5 --- /dev/null +++ b/shacl12-vocabularies/shnex-sparql.ttl @@ -0,0 +1,814 @@ +## W3C SOFTWARE AND DOCUMENT NOTICE AND LICENSE +## https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document +## -------- + +# W3C SHACL Node Expressions Vocabulary + +# THIS VERSION IS UNDER DEVELOPMENT BY THE DATA-SHAPES (SHACL 1.2) WG + +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . +@prefix dc: . +@prefix sh: . +@prefix shnex: . +@prefix sparql: . + +shnex-sparql: + a owl:Ontology ; + rdfs:label "W3C SHACL SPARQL Functions Vocabulary"@en ; + rdfs:comment "This vocabulary defines SPARQL functions for use with SHACL."@en ; + sh:declare [ + sh:prefix "shnex" ; + sh:namespace "http://www.w3.org/ns/shnex#"^^xsd:anyURI ; + ] ; + owl:imports , . + + +# Spec link pattern: +# For functions in the source whose rdfs:isDefinedBy is the generic spec homepage +# a per-function anchor was constructed +# as where LOCALNAME is +# the SPARQL local name (e.g., sparql:str -> #func-str). Where a function had a +# more specific anchor in the source, the same target was used. (This comment +# documents the fragment pattern used for constructed links.) + +# Imported SPARQL function terms (rdf:type, rdfs:label, dc:description, shnex:category, rdfs:isDefinedBy) +# Category values: algebraic, numeric, string, date, aggregate, other + +sparql:plus + a sparql:Function ; + rdfs:label "Plus"@en ; + dc:description "This operator adds two numeric expressions and returns their sum."@en ; + shnex:category "algebraic" ; + rdfs:isDefinedBy ; + . + +sparql:subtract + a sparql:Function ; + rdfs:label "Subtract"@en ; + dc:description "This operator subtracts the second numeric expression from the first and returns the result."@en ; + shnex:category "algebraic" ; + rdfs:isDefinedBy ; + . + +sparql:multiply + a sparql:Function ; + rdfs:label "Multiply"@en ; + dc:description "This operator multiplies two numeric expressions and returns the product."@en ; + shnex:category "algebraic" ; + rdfs:isDefinedBy ; + . + +sparql:divide + a sparql:Function ; + rdfs:label "Divide"@en ; + dc:description "This operator divides the first numeric expression by the second and returns the result."@en ; + shnex:category "algebraic" ; + rdfs:isDefinedBy ; + . + +sparql:unary-minus + a sparql:Function ; + rdfs:label "Unary minus"@en ; + dc:description "This unary operator returns the negation of a numeric expression."@en ; + shnex:category "algebraic" ; + rdfs:isDefinedBy ; + . + +sparql:unary-plus + a sparql:Function ; + rdfs:label "Unary plus"@en ; + dc:description "This unary operator returns the numeric expression unchanged, acting primarily as a syntactic indicator."@en ; + shnex:category "algebraic" ; + rdfs:isDefinedBy ; + . + +sparql:equals + a sparql:Function ; + rdfs:label "Equals"@en ; + dc:description "This operator compares two expressions for equality."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:not-equals + a sparql:Function ; + rdfs:label "Not equals"@en ; + dc:description "This operator tests two expressions for inequality."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:greater-than + a sparql:Function ; + rdfs:label "Greater than"@en ; + dc:description "This operator tests whether the first RDF term is greater than the second RDF term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:less-than + a sparql:Function ; + rdfs:label "Less than"@en ; + dc:description "This operator tests whether the first RDF term is less than the second RDF term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:greater-than-or-equal + a sparql:Function ; + rdfs:label "Greater than or equal"@en ; + dc:description "This operator tests whether the first RDF term is greater or equal to the second RDF term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:less-than-or-equal + a sparql:Function ; + rdfs:label "Less than or equal"@en ; + dc:description "This operator tests whether the first RDF term is less than or equal to the second RDF term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:logical-not + a sparql:Function ; + rdfs:label "Logical not"@en ; + dc:description "This form computes the logical NOT of a boolean expression."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +# Functional forms +sparql:bound + a sparql:FunctionalForm ; + rdfs:label "Bound"@en ; + dc:description "This form checks whether a variable is bound (assigned a value) in the current solution."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:if + a sparql:FunctionalForm ; + rdfs:label "If"@en ; + dc:description "This conditional form evaluates a test expression and returns one of two provided expressions based on the boolean outcome of the test."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:coalesce + a sparql:FunctionalForm ; + rdfs:label "Coalesce"@en ; + dc:description "This form returns the first non-error, non-unbound value from a sequence of expressions."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:filter-exists + a sparql:FunctionalForm ; + rdfs:label "Filter exists"@en ; + dc:description "This form tests whether a given pattern exists for each solution."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:filter-not-exists + a sparql:FunctionalForm ; + rdfs:label "Filter not exists"@en ; + dc:description "This form tests whether a given pattern does not exist for each solution."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:logical-or + a sparql:FunctionalForm ; + rdfs:label "Logical or"@en ; + dc:description "This form computes the logical OR of two boolean expressions."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:logical-and + a sparql:FunctionalForm ; + rdfs:label "Logical and"@en ; + dc:description "This form computes the logical AND of two boolean expressions."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:in + a sparql:FunctionalForm ; + rdfs:label "In"@en ; + dc:description "This form checks whether a given value matches any value from a list of expressions."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:not-in + a sparql:FunctionalForm ; + rdfs:label "Not in"@en ; + dc:description "This form returns true if the value is not found, or false if the value is found, in the list of expressions."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +# Functions on RDF terms +sparql:sameTerm + a sparql:Function ; + rdfs:label "Same term"@en ; + dc:description "This function checks whether two RDF terms are the same in the strict sense, including their lexical forms, datatypes, and language tags for literals."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:sameValue + a sparql:Function ; + rdfs:label "Same value"@en ; + dc:description "This function compares two RDF terms for equivalent RDF values, potentially considering numeric type equivalencies and other canonical forms beyond strict term identity."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:RDFterm-equal + a sparql:Function ; + rdfs:label "RDFterm equal"@en ; + dc:description "Deprecated"@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:isIRI + a sparql:Function ; + rdfs:label "Is IRI"@en ; + dc:description "This function returns true if the provided term is an IRI, and false otherwise."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:isURI + a sparql:Function ; + rdfs:label "Is URI"@en ; + dc:description "This function returns true if the provided term is an IRI, and false otherwise."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:isBlank + a sparql:Function ; + rdfs:label "Is blank"@en ; + dc:description "This function returns true if the provided term is a blank node, and false otherwise."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:isLiteral + a sparql:Function ; + rdfs:label "Is literal"@en ; + dc:description "This function returns true if the provided term is an RDF literal, and false otherwise."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:isNumeric + a sparql:Function ; + rdfs:label "Is numeric"@en ; + dc:description "This function returns true if the provided term is a numeric literal (e.g., xsd:integer, xsd:decimal, xsd:float, or xsd:double), and false otherwise."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:str + a sparql:Function ; + rdfs:label "Str"@en ; + dc:description "This function returns the lexical form of an RDF term, which for IRIs is the IRI string, and for literals is the lexical representation."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:lang + a sparql:Function ; + rdfs:label "Lang"@en ; + dc:description "This function returns the language tag of a literal, or an empty string if no language tag is present or the term is not a literal."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:langdir + a sparql:Function ; + rdfs:label "Langdir"@en ; + dc:description "This function returns the initial text direction of a literal."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:hasLang + a sparql:Function ; + rdfs:label "Has lang"@en ; + dc:description "This function returns true if the given RDF literal has a specified language, matching the literal’s language tag."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:hasLangdir + a sparql:Function ; + rdfs:label "Has langdir"@en ; + dc:description "This function returns true if the given RDF literal has an initial text direction."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:datatype + a sparql:Function ; + rdfs:label "Datatype"@en ; + dc:description "This function returns the datatype IRI of a literal term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:iri + a sparql:Function ; + rdfs:label "IRI"@en ; + dc:description "This function returns an IRI with the given string."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:uri + a sparql:Function ; + rdfs:label "URI"@en ; + dc:description "This function returns an IRI with the given string."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:bnode + a sparql:Function ; + rdfs:label "BNode"@en ; + dc:description "This function returns a blank node."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:strdt + a sparql:Function ; + rdfs:label "Strdt"@en ; + dc:description "This function creates a typed literal from a string and a datatype IRI, returning an RDF literal with the specified lexical form and datatype."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:strlang + a sparql:Function ; + rdfs:label "Strlang"@en ; + dc:description "This function creates an RDF literal with the specified lexical form and language tag."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:strlangdir + a sparql:Function ; + rdfs:label "Strlangdir"@en ; + dc:description "This function creates an RDF literal with language tag and initial text direction."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:uuid + a sparql:Function ; + rdfs:label "UUID"@en ; + dc:description "This function generates a UUID as an IRI."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:struuid + a sparql:Function ; + rdfs:label "StrUUID"@en ; + dc:description "This function generates a UUID as a string."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +# Functions on strings +sparql:strlen + a sparql:Function ; + rdfs:label "Strlen"@en ; + dc:description "This function returns the length of the lexical form of a string literal, measured in characters."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:substr + a sparql:Function ; + rdfs:label "Substr"@en ; + dc:description "This function returns the substring of the given string starting at a specified position and optionally limited to a given length."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:ucase + a sparql:Function ; + rdfs:label "Ucase"@en ; + dc:description "This function transforms all alphabetic characters in the input string to uppercase, following Unicode case-folding conventions"@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:lcase + a sparql:Function ; + rdfs:label "Lcase"@en ; + dc:description "This function transforms all alphabetic characters in the input string to lowercase, according to Unicode case-folding rules."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:strstarts + a sparql:Function ; + rdfs:label "Strstarts"@en ; + dc:description "This function returns true if the first string argument begins with the second string argument, and false otherwise."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:strends + a sparql:Function ; + rdfs:label "Strends"@en ; + dc:description "This function returns true if the first string argument ends with the second string argument, and false otherwise."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:contains + a sparql:Function ; + rdfs:label "Contains"@en ; + dc:description "This function returns true if the first string argument contains the second string argument as a substring, and false otherwise."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:strbefore + a sparql:Function ; + rdfs:label "Strbefore"@en ; + dc:description "This function returns the substring of the first argument that precedes the first occurrence of the second argument."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:strafter + a sparql:Function ; + rdfs:label "Strafter"@en ; + dc:description "This function returns the substring of the first argument that follows the first occurrence of the second argument."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:concat + a sparql:Function ; + rdfs:label "Concat"@en ; + dc:description "This function concatenates two or more string literals into one continuous string."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:langMatches + a sparql:Function ; + rdfs:label "LangMatches"@en ; + dc:description "This function checks whether a given language tag matches a specified language range."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:regex + a sparql:Function ; + rdfs:label "Regex"@en ; + dc:description "This function tests whether a string matches a regular expression pattern, optionally with a specified flag (e.g., i for case-insensitive)."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:replace + a sparql:Function ; + rdfs:label "Replace"@en ; + dc:description "This function performs a regular expression search-and-replace on a string, returning the modified string."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +sparql:encode + a sparql:Function ; + rdfs:label "Encode"@en ; + dc:description "This function encodes a string using a specified method (e.g., URI-encoding), returning the encoded version."@en ; + shnex:category "string" ; + rdfs:isDefinedBy ; + . + +# Functions on numbers +sparql:abs + a sparql:Function ; + rdfs:label "Abs"@en ; + dc:description "This function returns the absolute value of a numeric argument."@en ; + shnex:category "numeric" ; + rdfs:isDefinedBy ; + . + +sparql:round + a sparql:Function ; + rdfs:label "Round"@en ; + dc:description "This function rounds a numeric argument to the nearest integer."@en ; + shnex:category "numeric" ; + rdfs:isDefinedBy ; + . + +sparql:ceil + a sparql:Function ; + rdfs:label "Ceil"@en ; + dc:description "This function returns the smallest integer greater than or equal to the numeric argument."@en ; + shnex:category "numeric" ; + rdfs:isDefinedBy ; + . + +sparql:floor + a sparql:Function ; + rdfs:label "Floor"@en ; + dc:description "This function returns the greatest integer less than or equal to the numeric argument."@en ; + shnex:category "numeric" ; + rdfs:isDefinedBy ; + . + +sparql:rand + a sparql:Function ; + rdfs:label "Rand"@en ; + dc:description "This function returns a random number between 0 and 1."@en ; + shnex:category "numeric" ; + rdfs:isDefinedBy ; + . + +# Functions on datetimes +sparql:now + a sparql:Function ; + rdfs:label "Now"@en ; + dc:description "This function returns the current dateTime (with or without a timezone) at the moment of query execution."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +sparql:year + a sparql:Function ; + rdfs:label "Year"@en ; + dc:description "This function returns the year component of an xsd:dateTime or xsd:date."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +sparql:month + a sparql:Function ; + rdfs:label "Month"@en ; + dc:description "This function returns the month component of an xsd:dateTime or xsd:date."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +sparql:day + a sparql:Function ; + rdfs:label "Day"@en ; + dc:description "This function returns the day component of an xsd:dateTime or xsd:date."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +sparql:hours + a sparql:Function ; + rdfs:label "Hours"@en ; + dc:description "This function returns the hour component (0–23) of an xsd:dateTime value."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +sparql:minutes + a sparql:Function ; + rdfs:label "Minutes"@en ; + dc:description "This function returns the minute component (0–59) of an xsd:dateTime value."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +sparql:seconds + a sparql:Function ; + rdfs:label "Seconds"@en ; + dc:description "This function returns the second component (0–60, including leap seconds) of an xsd:dateTime value."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +sparql:timezone + a sparql:Function ; + rdfs:label "Timezone"@en ; + dc:description "This function returns the timezone component as a dayTimeDuration for an xsd:dateTime value with a specified time zone, or an empty value if none."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +sparql:tz + a sparql:Function ; + rdfs:label "TZ"@en ; + dc:description "This function returns the timezone component as a string in ISO 8601 format if present in the xsd:dateTime value, or an empty string otherwise."@en ; + shnex:category "date" ; + rdfs:isDefinedBy ; + . + +# Functions on triple terms +sparql:triple + a sparql:Function ; + rdfs:label "Triple"@en ; + dc:description "This function constructs a triple term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:subject + a sparql:Function ; + rdfs:label "Subject"@en ; + dc:description "This function returns the subject of a triple term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:predicate + a sparql:Function ; + rdfs:label "Predicate"@en ; + dc:description "This function returns the predicate of a triple term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:object + a sparql:Function ; + rdfs:label "Object"@en ; + dc:description "This function returns the object of a triple term."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:isTriple + a sparql:Function ; + rdfs:label "Is triple"@en ; + dc:description "This function returns true if the argument is a triple term, and false otherwise."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +# Hash functions +sparql:md5 + a sparql:Function ; + rdfs:label "MD5"@en ; + dc:description "This function computes the MD5 hash of the lexical form of a string, returning a hexadecimal string representation of the hash."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:sha1 + a sparql:Function ; + rdfs:label "SHA1"@en ; + dc:description "This function computes the SHA-1 hash of the lexical form of a string, returning a hexadecimal string representation of the result."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:sha256 + a sparql:Function ; + rdfs:label "SHA256"@en ; + dc:description "This function computes the SHA-256 hash of the lexical form of a string, returning the resulting hash as a hexadecimal string."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:sha384 + a sparql:Function ; + rdfs:label "SHA384"@en ; + dc:description "This function computes the SHA-384 hash of the lexical form of a string, returning the resulting hexadecimal string."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +sparql:sha512 + a sparql:Function ; + rdfs:label "SHA512"@en ; + dc:description "This function computes the SHA-512 hash of the lexical form of a string, returning the result as a hexadecimal string."@en ; + shnex:category "other" ; + rdfs:isDefinedBy ; + . + +# Aggregate functions +sparql:agg-count + a sparql:Aggregate ; + rdfs:label "COUNT"@en ; + dc:description "Aggregate function COUNT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-count-distinct + a sparql:Aggregate ; + rdfs:label "COUNT DISTINCT"@en ; + dc:description "Aggregate function COUNT with DISTINCT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-sum + a sparql:Aggregate ; + rdfs:label "SUM"@en ; + dc:description "Aggregate function SUM"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-sum-distinct + a sparql:Aggregate ; + rdfs:label "SUM DISTINCT"@en ; + dc:description "Aggregate function SUM with DISTINCT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-min + a sparql:Aggregate ; + rdfs:label "MIN"@en ; + dc:description "Aggregate function MIN"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-min-distinct + a sparql:Aggregate ; + rdfs:label "MIN DISTINCT"@en ; + dc:description "Aggregate function MIN with DISTINCT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-max + a sparql:Aggregate ; + rdfs:label "MAX"@en ; + dc:description "Aggregate function MAX"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-max-distinct + a sparql:Aggregate ; + rdfs:label "MAX DISTINCT"@en ; + dc:description "Aggregate function MAX with DISTINCT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-avg + a sparql:Aggregate ; + rdfs:label "AVG"@en ; + dc:description "Aggregate function AVG"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-avg-distinct + a sparql:Aggregate ; + rdfs:label "AVG DISTINCT"@en ; + dc:description "Aggregate function AVG with DISTINCT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-sample + a sparql:Aggregate ; + rdfs:label "SAMPLE"@en ; + dc:description "Aggregate function SAMPLE"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-sample-distinct + a sparql:Aggregate ; + rdfs:label "SAMPLE DISTINCT"@en ; + dc:description "Aggregate function SAMPLE with DISTINCT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-group-concat + a sparql:Aggregate ; + rdfs:label "GROUP_CONCAT"@en ; + dc:description "Aggregate function GROUP_CONCAT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . + +sparql:agg-group-concat-distinct + a sparql:Aggregate ; + rdfs:label "GROUP_CONCAT DISTINCT"@en ; + dc:description "Aggregate function GROUP_CONCAT with DISTINCT"@en ; + shnex:category "aggregate" ; + rdfs:isDefinedBy ; + . From f28f2dd32bc5bc45e6e155f01feb8726ec16edcf Mon Sep 17 00:00:00 2001 From: simonstey Date: Sat, 16 Aug 2025 07:32:44 +0200 Subject: [PATCH 4/9] Render SPARQL functions table in node-expr UI from local shnex-sparql.ttl --- shacl12-node-expr/index.html | 300 +++++++++++++++++++++-------------- 1 file changed, 178 insertions(+), 122 deletions(-) diff --git a/shacl12-node-expr/index.html b/shacl12-node-expr/index.html index 76469195..9a972886 100644 --- a/shacl12-node-expr/index.html +++ b/shacl12-node-expr/index.html @@ -8,156 +8,212 @@