Issue 163 path

shacl12-core/images/Makefile

@@ -0,0 +1,4 @@
+all: SHACL-UML.svg
+
+%.svg: %.puml
+	plantuml -Tsvg $^

shacl12-core/images/SHACL-UML.puml

@@ -0,0 +1,66 @@
+@startuml
+hide circles
+hide empty members
+skinparam pathHoverColor red ' on cover, highlight blue links as red
+' skinparam topurl https://raw.githack.com/w3c/data-shapes/master/shacl12-core/index.html ' links resolve to anchors in current HTML page, when the SVG is embedded
+
+class "<color:blue><u>sh:Shape" as Shape [[#shapes]] {
+  [[#targetClass sh:targetClass]] : rdfs:Class
+  [[#targetNode sh:targetNode]] : any
+  [[#targetSubjectsOf sh:targetSubjectsOf]] : rdf:Property
+  [[#targetObjectsOf sh:targetObjectsOf]] : rdf:Property
+  [[#targetWhere sh:targetWhere]] : sh:NodeShape
+  ....
+  [[#deactivated sh:deactivated]] : xsd:boolean
+  [[#message sh:message]] : xsd:string or rdf:langString
+  [[#severity sh:severity]] : sh:Severity
+}
+
+class "<color:blue><u>sh:NodeShape" as NodeShape [[#node-shapes]] {
+  [[#constraints Constraint parameters]], for example:
+  [[#NodeKindConstraintComponent sh:nodeKind]] a sh:NodeKind
+  [[#ClosedConstraintComponent sh:closed]] : xsd:boolean or [[#syntax-rule-closed-datatype sh:ByTypes]]
+  [[#ClosedConstraintComponent sh:ignoredProperties]] : list
+  [[#OrConstraintComponent sh:or]], [[#AndConstraintComponent sh:and]], [[#XoneConstraintComponent sh:xone]] : list of Shape
+  [[#NotConstraintComponent sh:not]] : [[#shapes sh:Shape]]
+  ...
+}
+
+class "<color:blue><u>sh:PropertyShape" as PropertyShape [[#property-shapes]] {
+  [[#property-paths sh:path]] : predicate or list or blank node
+  ....
+  [[#constraints Constraint parameters]], for example:
+  [[#MinCountConstraintComponent sh:minCount]], [[#MaxCountConstraintComponent sh:maxCount]] : xsd:integer
+  [[#MinLengthConstraintComponent sh:minLength]], [[#MaxLengthConstraintComponent sh:maxLength]] : xsd:integer
+  [[#ClassConstraintComponent sh:class]] or [[#DatatypeConstraintComponent sh:datatype]] : IRI or list of IRIs
+  [[#NodeConstraintComponent sh:node]] : [[#node-shapes sh:NodeShape]]
+  ...
+  ....
+  [[#core-components-list List constraints]]
+  [[#MemberShapeConstraintComponent sh:memberShape]] : [[#node-shapes sh:NodeShape]]
+  [[#MinListLengthConstraintComponent sh:minListLength]], [[#MaxListLengthConstraintComponent sh:maxListLength]]: xsd:integer
+  [[#UniqueMembersConstraintComponent sh:uniqueMembers]] : xsd:boolean
+  ....
+  [[#name sh:name]] : xsd:string or rdf:langString
+  [[#description sh:description]] : xsd:string or rdf:langString
+  [[#syntax-rule-path-defaultValue sh:defaultValue]] : any
+  [[#syntax-rule-path-defaultValue sh:values]] : any
+  [[#codeIdentifier sh:codeIdentifier]] : xsd:string 
+  [[#order sh:order]] : xsd:integer or xsd:decimal
+}
+
+class "<color:blue><u>sh:PropertyGroup" as PropertyGroup [[#group sh:group]] {
+  [[#group sh:order]] : xsd:integer or xsd:decimal
+  ... eg rdfs:label
+}
+
+Shape <|-- NodeShape
+Shape <|-- PropertyShape
+NodeShape -> PropertyShape : [[#property-shapes sh:property]] *
+PropertyShape --> PropertyGroup : [[#group sh:group]]
+
+' These links make the diagram too busy, so omit them for now. They are listed as fields
+' PropertyShape -> NodeShape : [[#NodeConstraintComponent sh:node]]
+' PropertyShape -> NodeShape : [[#MemberShapeConstraintComponent sh:memberShape]]
+' Shape -> NodeShape : [[#targetWhere sh:targetWhere]]
+@enduml

shacl12-core/index.html

@@ -1115,70 +1115,15 @@ <h2>Shapes and Constraints</h2>
 
 			<p><em>The following introduction is non-normative.</em></p>
 			<p>
-				The following informal diagram provides an overview of some of the key classes in the SHACL vocabulary.
+				The following UML diagram provides an overview of some of the key classes and properties in the SHACL vocabulary.
 				Each box represents a class.
 				The content of the boxes under the class name lists some of the properties that instances of these classes may have, together with their value types.
-				The arrows indicate <code>rdfs:subClassOf</code> triples.
+				Empty arrowheads indicate inheritance (<code>rdfs:subClassOf</code>) and normal arrowheads indicate RDF relations.
+			</p>
+			<div id="SHACL-UML.svg"></div>
+			<p>
+				The <a href="http://www.w3.org/ns/shacl.ttl">Turtle serialization of the SHACL vocabulary</a> contains the complete SHACL vocabulary.
 			</p>
-			<div>
-				<div class="diagram-class" style="margin-left: 200px">
-					<div class="diagram-class-name"><a href="#shapes">sh:Shape</a></div>
-					<div class="diagram-class-properties">
-						<div class="diagram-class-properties-start">
-							<div><a href="#targetClass">sh:targetClass</a> : rdfs:Class</div>
-							<div><a href="#targetNode">sh:targetNode</a> : any</div>
-							<div><a href="#targetObjectsOf">sh:targetObjectsOf</a> : rdf:Property</div>
-							<div><a href="#targetSubjectsOf">sh:targetSubjectsOf</a> : rdf:Property</div>
-						</div>
-						<div class="diagram-class-properties-section">
-							<div><a href="#deactivated">sh:deactivated</a> : xsd:boolean</div>
-							<div><a href="#message">sh:message</a> : xsd:string or rdf:langString</div>
-							<div><a href="#severity">sh:severity</a> : sh:Severity</div>
-						</div>
-					</div>
-				</div>
-				<div style="height: 60px; margin-left: 260px">
-					<img alt="Class Diagram Arrows" src="images/Class-Diagram-Arrows.png">
-				</div>
-				<div style="white-space: nowrap; min-width: 1000px">
-				<div class="diagram-class" style="float: left; margin-right: 60px;">
-					<div class="diagram-class-name"><a href="#node-shapes">sh:NodeShape</a></div>
-					<div class="diagram-class-properties">
-						<div class="diagram-class-properties-start">
-							<div><b><a href="#constraints">Constraint parameters</a></b>, for example:</div>
-							<div><a href="#ClosedConstraintComponent">sh:closed</a> : xsd:boolean or sh:ByTypes</div>
-							<div><a href="#OrConstraintComponent">sh:or</a> : rdf:List</div>
-							<div><a href="#NotConstraintComponent">sh:not</a> : sh:Shape</div>
-							<div><a href="#PropertyConstraintComponent">sh:property</a> : sh:PropertyShape</div>
-						</div>
-					</div>
-				</div>
-				<div class="diagram-class" style="float: left;">
-					<div class="diagram-class-name"><a href="#property-shapes">sh:PropertyShape</a></div>
-					<div class="diagram-class-properties">
-						<div class="diagram-class-properties-start">
-							<div><b><a href="#constraints">Constraint parameters</a></b>, for example:</div>
-							<div><a href="#MinCountConstraintComponent">sh:minCount</a>, <a href="#MaxCountConstraintComponent">sh:maxCount</a> : xsd:integer</div>
-							<div><a href="#ClassConstraintComponent">sh:class</a> or <a href="#DatatypeConstraintComponent">sh:datatype</a> : rdfs:Resource</div>
-							<div><a href="#NodeConstraintComponent">sh:node</a> : sh:NodeShape</div>
-						</div>
-						<div class="diagram-class-properties-section">
-							<div><a href="#name">sh:name</a> : xsd:string or rdf:langString</div>
-							<div><a href="#description">sh:description</a> : xsd:string or rdf:langString</div>
-							<div><a href="#syntax-rule-path-defaultValue">sh:defaultValue</a> : any</div>
-							<div><a href="#group">sh:group</a> : sh:PropertyGroup</div>
-						</div>
-						<div class="diagram-class-properties-section">
-							<div><a href="#property-shapes">sh:path</a> : rdfs:Resource</div>
-						</div>
-					</div>
-				</div>
-				<div style="clear: both"></div>
-				</div>
-				<p>
-					The <a href="http://www.w3.org/ns/shacl.ttl">Turtle serialization of the SHACL vocabulary</a> contains the complete SHACL vocabulary.
-				</p>
-			</div>
 
 			<section id="shapes">
 
@@ -7976,12 +7921,20 @@ <h2>Changes between SHACL 1.0 Core and SHACL 1.2 Core</h2>
 
 	<script type="text/javascript">
 
-		tooltip = "Targets are not the only way to initiate validation, SHACL also allows specific nodes to be validated against specific shapes.";
-		var t = document.getElementsByClassName("target-can-be-skipped");
-		for (var i = 0; i < t.length; i++) {
-			t[i].title = tooltip;
-		}
+		// tooltip = "Targets are not the only way to initiate validation, SHACL also allows specific nodes to be validated against specific shapes.";
+		// var t = document.getElementsByClassName("target-can-be-skipped");
+		// for (var i = 0; i < t.length; i++) {
+		// 	t[i].title = tooltip;
+		// };
 
+    // Load and inline SVG diagram
+    // TODO: add desc="UML class diagram for SHACL showing Shape, NodeShape, PropertyShape, PropertyGroup" for accessibility
+    fetch('images/SHACL-UML.svg')
+      .then(response => response.text())
+      .then(svgText => {
+        const container = document.getElementById('SHACL-UML.svg');
+        container.innerHTML = svgText;
+      });
 	</script>
 
 

shacl12-sparql/index.html

@@ -930,7 +930,7 @@ <h3>Syntax of SPARQL-based Constraints</h3>
 					and this value is either <code>true</code> or <code>false</code>.
 				</p>
 				<p>
-					SELECT queries used in the context of <a>property shapes</a> use a special variable named <code>PATH</code> as a placeholder for the path used by the shape.
+					SELECT queries used in the context of <a>property shapes</a> use a special variable named <code>PATH</code> (spelled in UPPERCASE) as a placeholder for the path used by the shape.
 				</p>
 				<p class="syntax">
 					<span data-syntax-rule="PATH-position">The only legal use of the variable <code>PATH</code> in the SPARQL queries of <a>SPARQL-based constraints</a>
@@ -1042,19 +1042,27 @@ <h3>Validation with SPARQL-based Constraints</h3>
 				<div class="def def-text">
 					<div class="def-header">TEXTUAL DEFINITION</div>
 					<div class="def-text-body">
-						Let <code>$sparql</code> be a <a>value</a> of <code>sh:sparql</code>.
-						There are no validation results if the <a>SPARQL-based constraint</a> has <code>true</code>
-						as a <a>value</a> for the property <code>sh:deactivated</code>.
-						Otherwise, execute the SPARQL query specified by the <a>SPARQL-based constraint</a> <code>$sparql</code>
-						<a>pre-binding</a> the variable <code>this</code> as described in <a href="#sparql-constraints-prebound"></a>.
-						If the <a>shape</a> is a <a>property shape</a>, then prior to execution
-						<dfn data-lt="substituted">substitute</dfn> the variable <code>PATH</code> where it appears in the <a>predicate</a>
-						position of a <a data-cite="sparql12-query/#QSynTriples">triple pattern</a>
-						with a valid SPARQL surface syntax string of the <a>SHACL property path</a>
-						specified via <code>sh:path</code> at the <a>property shape</a>.
-						<span id="sparql-constraints-validation-rule">There is one validation result for each <a>solution</a> that does not have <code>true</code> as the <a>binding</a> for the variable <code>failure</code>.
-						These validation results MUST have the property values explained in <a href="#sparql-constraints-variables"></a>.
-						A <a>failure</a> MUST be produced if and only if one of the <a>solutions</a> has <code>true</code> as the <a>binding</a> for <code>failure</code>.</span>
+            <p>
+						  Let <code>$sparql</code> be a <a>value</a> of <code>sh:sparql</code>.
+						  There are no validation results if the <a>SPARQL-based constraint</a> has <code>true</code>
+						  as a <a>value</a> for the property <code>sh:deactivated</code>.
+						  Otherwise, execute the SPARQL query specified by the <a>SPARQL-based constraint</a> <code>$sparql</code>
+						  <a>pre-binding</a> the variable <code>this</code> as described in <a href="#sparql-constraints-prebound"></a>.
+            </p>
+						<p>
+              If the <a>shape</a> is a <a>property shape</a>, then prior to execution
+						  <dfn data-lt="substituted">substitute</dfn> the variable <code>PATH</code> where it appears in the <a>predicate</a>
+						  position of a <a data-cite="sparql12-query/#QSynTriples">triple pattern</a>
+						  with a valid SPARQL surface syntax string of the <a>SHACL property path</a>
+						  specified via <code>sh:path</code> at the <a>property shape</a>.
+              If <code>sh:path</code> is not a well-formed <a data-cite="shacl12-core/#dfn-shacl-property-paths">SHACL property path</a> then return an error,
+              and as a precaution may also substitute the signal value <code>"BAD-PATH"</code>, which will make the SPARQL query invalid.
+            </p>
+            <p>
+						  <span id="sparql-constraints-validation-rule">There is one validation result for each <a>solution</a> that does not have <code>true</code> as the <a>binding</a> for the variable <code>failure</code>.
+						    These validation results MUST have the property values explained in <a href="#sparql-constraints-variables"></a>.
+						    A <a>failure</a> MUST be produced if and only if one of the <a>solutions</a> has <code>true</code> as the <a>binding</a> for <code>failure</code>.</span>
+            </p>
 					</div>
 				</div>
 				<section id="sparql-constraints-prebound">
@@ -1546,10 +1554,8 @@ <h3>Validation with SPARQL-based Constraint Components</h3>
 					<li>
 						For <a>SELECT-based validators</a>:
 						If the <a>shape</a> is a <a>property shape</a>, then prior to execution
-						<a>substitute</a> the variable <code>PATH</code> where it appears in the <a>predicate</a>
-						position of a <a data-cite="sparql12-query/#QSynTriples">triple pattern</a>
-						with a valid SPARQL surface syntax string of the <a>SHACL property path</a>
-						specified via <code>sh:path</code> at the <a>property shape</a>.
+						<a>substitute</a> the variable <code>PATH</code> with a valid SPARQL surface syntax string of the <a>SHACL property path</a>
+            (see the reference "<a>substitute</a>" for details).
 						Let <code>QS</code> be the <a>solutions</a> produced by executing the SPARQL query.
 					</li>
 				</ul>
@@ -2261,6 +2267,7 @@ <h2>Security and Privacy Considerations</h2>
 			</p>
 			<p>
 				SHACL-SPARQL includes all the <a data-cite="sparql12-query/#security">security issues of SPARQL</a>.
+        In particular, the <a data-cite="shacl12-sparql/#dfn-substituted">substitution</a> of variable <code>PATH</code> constitutes SPARQL string injection, which may pose additional risks.
 			</p>
 		</section>
 

shacl12-vocabularies/shacl-shacl.ttl

@@ -23,11 +23,11 @@ shsh:
 shsh:ListShape
 	a sh:NodeShape ;
 	rdfs:label "List shape"@en ;
-	rdfs:comment "A shape describing well-formed RDF lists. Currently does not check for non-recursion. This could be expressed using SHACL-SPARQL."@en ;
+	rdfs:comment "A shape describing well-formed RDF lists. Currently does not check for non-recursion (this could be expressed using SHACL-SPARQL)."@en ;
 	rdfs:seeAlso <https://www.w3.org/TR/shacl/#syntax-rule-SHACL-list> ;
 	sh:property [
 		sh:path [ sh:zeroOrMorePath rdf:rest ] ;
-		rdfs:comment "Each list member (including this node) must be have the shape shsh:ListNodeShape."@en ;
+		rdfs:comment "Each list member (including this node) must have the shape shsh:ListNodeShape."@en ;
 		sh:hasValue rdf:nil ;
 		sh:node shsh:ListNodeShape ;
 	] .