Skip to content

Commit 48953d2

Browse files
HolgerKnublauchrecalcitrantsupplant
HolgerKnublauch
and
recalcitrantsupplant
authored
Node Expression Intro and Syntax overview chapters (#441)
* Started some introductory section * Progress with the definitions and examples * Fixed duplicate section ID, broken references after merge * Apply suggestions from code review Co-authored-by: David Habgood <[email protected]> --------- Co-authored-by: David Habgood <[email protected]>
1 parent c31f28b commit 48953d2

File tree

3 files changed

+256
-11
lines changed

3 files changed

+256
-11
lines changed

‎shacl12-node-expr/images/CountExampleDiagram.png

39.3 KB
Loading

‎shacl12-node-expr/images/FilterShapeExampleDiagram.png

50.8 KB
Loading

‎shacl12-node-expr/index.html

Lines changed: 256 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -479,9 +479,10 @@ <h3>Terminology</h3>
479479
<dfn data-cite="shacl12-core#dfn-node-expression" data-lt="node expression|node expresssions">node expression</dfn>,
480480
<dfn data-cite="shacl12-core#dfn-node-expression-function" data-lt="node expression function|node expresssion functions">node expression function</dfn>,
481481
<dfn data-cite="shacl12-core#dfn-function-name" data-lt="node expression function name">function name</dfn>,
482-
<dfn data-cite="shacl12-core#dfn-key-parameter" data-lt="key parameter">key parameter</dfn>,
483482
<dfn data-cite="shacl12-core#dfn-output-nodes" data-lt="output nodes">output nodes</dfn>,
484483
<dfn data-cite="shacl12-core#dfn-focus-graph" data-lt="focus graph">focus graph</dfn>,
484+
<dfn data-cite="shacl12-core#dfn-evaluation">evaluation</dfn>,
485+
<dfn data-cite="shacl12-core#dfn-evaluation-failure">evaluation failure</dfn>,
485486
<dfn data-cite="shacl12-core#dfn-conform" data-lt="conform|conforms">conform</dfn>,
486487
<dfn data-cite="shacl12-core#dfn-failure" data-lt="failure|failures">failure</dfn>,
487488
<dfn data-cite="shacl12-core#dfn-shacl-instance" data-lt="shacl instance">SHACL instance</dfn>,
@@ -557,17 +558,177 @@ <h3>Document Conventions</h3>
557558
</section>
558559
</section>
559560

561+
<section id="getting-started">
562+
<h2>Getting started with Node Expressions</h2>
563+
<p><em>This section is informative.</em></p>
564+
<p>
565+
SHACL <a>shapes graphs</a> can declare node expressions as values of various properties where dynamic computation is useful,
566+
such as <code>sh:targetNode</code>, <code>sh:values</code> and <code>sh:deactivated</code>.
567+
Node expressions are represented by RDF nodes and can be evaluated to produce a list of <a>output nodes</a>.
568+
For example when used at <code>sh:targetNode</code>, a node expression produces the list
569+
of target nodes of a <a>shape</a>.
570+
When used at <code>sh:values</code>, a node expression produces the derived values for the property specified by <code>sh:path</code>.
571+
</p>
572+
<p id="EstonianCompanyShapeExample">
573+
The following example contains a node expression that states that the <a>target</a> nodes of
574+
the shape <code>ex:EstonianCompanyShape</code> are the instances of <code>ex:Company</code> where
575+
the <code>ex:headQuarterCountry</code> is <code>ex:Estonia</code>.
576+
</p>
577+
<p>
578+
<aside class="example" title="A node expression used to compute the target nodes of a shape.">
579+
<div class="shapes-graph">
580+
<div class="turtle">
581+
ex:EstonianCompanyShape
582+
a sh:NodeShape ;
583+
sh:targetNode <b>[
584+
sh:nodes [
585+
sh:instancesOf ex:Company ;
586+
] ;
587+
sh:filterShape [
588+
sh:property [
589+
sh:path ex:headQuarterCountry ;
590+
sh:hasValue ex:Estonia ;
591+
]
592+
]
593+
]</b> .
594+
</div>
595+
<div class="jsonld">
596+
TODO
597+
</div>
598+
</div>
599+
</aside>
600+
</p>
601+
<p>
602+
The following diagram illustrates how this node expression is interpreted, from a logical point of view.
603+
During validation, a SHACL processor will determine the <a>target</a> nodes of the shape
604+
by evaluating the <a>filterShape expression</a>.
605+
The filterShape expression, however, first evaluates its input expression, which is specified via <code>sh:nodes</code>
606+
and is an <a>instancesOf expression</a>.
607+
This will produce all instances of the given class <code>ex:Company</code>.
608+
The <code>sh:filterShape</code> is then applied to all of these instances, to only keep the companies
609+
that <a>conform</a> to the provided <a>shape</a> by having their headquarter in Estonia.
610+
</p>
611+
<div>
612+
<img
613+
alt="Illustration of the data flow between node expressions"
614+
src="images/FilterShapeExampleDiagram.png"
615+
width="800px"
616+
>
617+
</div>
618+
<p>
619+
The same scenario as above can also be expressed using SPARQL <a href="shacl12-sparql#SelectExpression">select expressions</a>.
620+
Specific implementations of the SHACL node expressions may (for example for performance reasons)
621+
internally convert node expressions such as the <code>sh:filterShape</code> above to SPARQL.
622+
</p>
623+
<p>
624+
<aside class="example" title="A SPARQL select expression used to compute the target nodes of a shape.">
625+
<div class="shapes-graph">
626+
<div class="turtle">
627+
ex:EstonianCompanyShape
628+
a sh:NodeShape ;
629+
sh:targetNode <b>[
630+
sh:select """
631+
SELECT ?company
632+
WHERE {
633+
?company rdf:type/rdfs:subClassOf* ex:Company .
634+
?company ex:headQuarterCountry ex:Estonia .
635+
}
636+
"""
637+
]</b> .
638+
</div>
639+
<div class="jsonld">
640+
TODO
641+
</div>
642+
</div>
643+
</aside>
644+
</p>
645+
<p>
646+
The next example uses a node expression to compute the values of the property <code>ex:employeeCount</code>
647+
as the number of values of the property <code>ex:employee</code> at each instance of <code>ex:Company</code>.
648+
</p>
649+
<p>
650+
<aside class="example" title="A node expression used to compute the values of a derived property.">
651+
<div class="shapes-graph">
652+
<div class="turtle">
653+
ex:Company
654+
a sh:ShapeClass ;
655+
sh:property ex:Company-employee ;
656+
sh:property ex:Company-employeeCount .
657+
658+
ex:Company-employee
659+
a sh:PropertyShape ;
660+
sh:name "employees" ;
661+
sh:description "The company's employee(s)." ;
662+
sh:path ex:employee ;
663+
sh:class ex:Person .
664+
665+
ex:Company-employeeCount
666+
a sh:PropertyShape ;
667+
sh:name "employee count" ;
668+
sh:description "The number of employees, automatically computed." ;
669+
sh:path ex:employeeCount ;
670+
sh:datatype xsd:integer ;
671+
sh:values <b>[
672+
sh:count [
673+
sh:path ex:employee ;
674+
]
675+
]</b> .
676+
</div>
677+
<div class="jsonld">
678+
TODO
679+
</div>
680+
</div>
681+
</aside>
682+
</p>
683+
<div>
684+
<img
685+
alt="Illustration of the data flow between node expressions computing the employee count"
686+
src="images/CountExampleDiagram.png"
687+
width="800px"
688+
>
689+
</div>
690+
<p>
691+
A difference between this example and the previous examples about <code>sh:targetNode</code>
692+
is that these node expressions are evaluated against a given <a>focus node</a>.
693+
So when a data visualization needs to render an instance of <code>ex:Company</code>,
694+
the currently displayed company is the <a>focus node</a>, from which the number of employees
695+
will be fetched.
696+
</p>
697+
<p class="todo">Clarify when these derived properties can be used (e.g. in sh:path expressions but not as triples elsewhere)</p>
698+
</section>
699+
560700
<section id="syntax">
561701
<h2>Node Expression Syntax</h2>
562702
<p>
563703
This section introduces the general syntax of SHACL <a>node expressions</a>.
564704
</p>
705+
<p>
706+
The term <a>node expression function</a> refers to the <em>kind</em> or <em>type</em>
707+
of a <a>node expression</a>.
708+
For example, <code>sh:FilterShapeExpression</code> is a <a>node expression function</a>
709+
while a specific instance of this function in the <a>graph</a> is the <a>node expression</a> itself.
710+
</p>
711+
<p>
712+
The most basic node expression functions are <a>constant node expressions</a>, which are either
713+
<a>literals</a> or <a>IRIs</a> and simply evaluate to these constants.
714+
All other node expressions are represented by <a>blank nodes</a> and come in the following two variations.
715+
</p>
716+
<ul>
717+
<li>
718+
<a>Named parameter functions</a> are represented by a <a>blank node</a> that is the subject of one or more
719+
triples, including the <a>key parameter</a> of the node expression function.
720+
</li>
721+
<li>
722+
<a>List parameter functions</a> are comparable to traditional functions in, for example, SPARQL
723+
and are represented by a <a>blank node</a> that is the subject of a single triple with a SHACL list as its object.
724+
</li>
725+
</ul>
565726

566727
<section id="ConstantNodeExpression">
567728
<h3>Constant Node Expressions</h3>
568729
<p>
569-
The <a>node expression functions</a> in this section were introduced in the SHACL Core
570-
specification but are repeated here to keep this document self-contained.
730+
The <a>node expression functions</a> in this section are called <dfn>constant node expressions</dfn>.
731+
They were introduced in the SHACL Core specification but are repeated here to keep this document self-contained.
571732
</p>
572733

573734
<section id="IRIExpression">
@@ -614,19 +775,103 @@ <h3>Literal Expressions</h3>
614775

615776
<section id="blank-node-functions">
616777
<h2>Node Expressions based on Blank Nodes</h2>
617-
<p>
618-
...
619-
</p>
778+
<section id="NamedParameterFunctions">
779+
<h3>Named Parameter Functions</h3>
780+
<p>
781+
A <dfn>named parameter function</dfn> is a <a>node expression function</a>
782+
that is represented by a <a>blank node</a> that is the <a>subject</a> of at least
783+
one <a>triple</a> where the <a>predicate</a> can be used to uniquely identify the function,
784+
which is known as the <dfn>key parameter</dfn>.
785+
</p>
786+
<p>The evaluation of a <a>named parameter function</a> can produce either:
787+
<ul>
788+
<li>zero <a>output nodes</a>, i.e. the empty list</li>
789+
<li>one or more <a>output nodes</a>, i.e. a list of one or more nodes</li>
790+
<li>an <a>evaluation failure</a>, i.e. an (unexpected) error during the evaluation</li>
791+
</ul>
792+
</p>
793+
<p>
794+
For example, the <a>named parameter function</a> <a href="#FilterShapeExpression">sh:FilterShapeExpression</a> has
795+
<code>sh:filterShape</code> as its <a>key parameter</a>.
796+
In this document, key parameters are marked in <b>bold face</b>.
797+
</p>
798+
<p>
799+
Expressions based on <a>named parameter functions</a> often take other <a>node expressions</a>
800+
as arguments, evaluate those input node expressions and then produce a different list of <a>nodes</a>
801+
as <a>output nodes</a>.
802+
</p>
803+
<p><em>The remainder of this section is informative.</em></p>
804+
<p>
805+
This document includes many examples of <a>named parameter functions</a>, such as
806+
the <a href="#EstonianCompanyShapeExample">Estonian Company Shape example</a>.
807+
</p>
808+
</section>
620809
<section id="ListParameterFunction">
621810
<h3>List Parameter Functions</h3>
622811
<p>
623-
...
812+
A <dfn>list parameter function</dfn> is a <a>node expression function</a>
813+
that is represented by a <a>blank node</a> that is the <a>subject</a> of a single
814+
<a>triple</a> where the <a>object</a> is a <a>SHACL list</a>.
815+
The <a>predicate</a> of this <a>triple</a> is called the <dfn>list parameter property</dfn>.
624816
</p>
625-
</section>
626-
<section id="NamedArgumentFunctions">
627-
<h3>Named Argument Functions</h3>
628817
<p>
629-
...
818+
The <a>evaluation</a> of a <a>list parameter function</a> can produce either:
819+
</p>
820+
<ul>
821+
<li>one <a>output node</a>, i.e. a list of one <a>node</a></li>
822+
<li>zero <a>output nodes</a>, i.e. the empty list</li>
823+
<li>an <a>evaluation failure</a>, i.e. an (unexpected) error during the evaluation</li>
824+
</ul>
825+
<p>
826+
Furthermore, all arguments of a <a>list parameter function</a> must evaluate to individual <a>nodes</a>
827+
and not lists of nodes.
828+
If an argument is a <a>node expression</a> then this <a>node expression</a> must evaluate to
829+
at most one <a>output node</a>.
830+
An <a>evaluation failure</a> must be produced if there is more than one <a>output node</a>.
831+
This is different from <a>named parameter functions</a>, where arguments may produce lists of multiple nodes.
832+
</p>
833+
<p><em>The remainder of this section is informative.</em></p>
834+
<p>
835+
Note that some <a>named parameter functions</a> such as <code>sh:IntersectionExpression</code>
836+
also use <a>SHACL lists</a> as object of the <a>key parameter</a>, similar to <a>list parameter functions</a> which always have <a>SHACL lists</a> as object of their <a>list parameter property</a>.
837+
However, these may produce more than one <a>output nodes</a> and also accept lists as input nodes.
838+
</p>
839+
<p>
840+
The following example uses multiple (imaginary) <a>list parameter functions</a>
841+
<code>ex:coalesce</code> and <code>ex:concat</code> to compute the <code>ex:displayName</code>
842+
of a person as either the value of <code>ex:fullName</code> or (if that doesn't exist)
843+
as the concatenation of first and last names, with a space in between.
844+
</p>
845+
<p>
846+
<aside class="example" title="A comple node expression based on list parameter functions.">
847+
<div class="shapes-graph">
848+
<div class="turtle">
849+
ex:Person-displayName
850+
a sh:PropertyShape ;
851+
sh:name "display name" ;
852+
sh:path ex:displayName ;
853+
sh:datatype xsd:string ;
854+
sh:values <b>[
855+
ex:coalesce (
856+
[
857+
# This is a path expression that is expected to return zero or one values
858+
sh:path ex:fullName ;
859+
]
860+
[
861+
ex:concat (
862+
[ sh:path ex:firstName ] # Path expression with at most one value
863+
" " # A constant literal expression
864+
[ sh:path ex:lastName ] # Path expression with at most one value
865+
)
866+
]
867+
)
868+
]</b> .
869+
</div>
870+
<div class="jsonld">
871+
TODO
872+
</div>
873+
</div>
874+
</aside>
630875
</p>
631876
</section>
632877
</section>

0 commit comments

Comments
 (0)