editorial on pre-binding

shacl/index.html

@@ -1507,6 +1507,7 @@ <h3>SPARQL definitions for built-in constraint components</h3>
 				<p>
 					Note that the parameter tables in each of the following sections have a column called Value Type which indicates the expected
 					type of the parameter values for documentation purposes, without enforcing any formal restrictions.
+					Based on the parameter IRIs on the tables, <a>pre-bound</a> variables are defined using the <a>parameter names</a>.
 				</p>
 				<p>
 					Some SPARQL definitions in this section also assume the existence of a built-in SPARQL function <a href="#hasShape"><code>sh:hasShape</code></a>.
@@ -3663,13 +3664,13 @@ <h3>Parameters Declaration (sh:parameter)</h3>
 					Each <code>sh:Parameter</code> must have exactly one value <code>p</code> for the property <code>sh:predicate</code> and the value must be an IRI.
 					The <dfn data-lt="local names">local name</dfn> of an <a>IRI</a> is defined as the longest <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCNAME</a>
 					at the end of the <a>IRI</a>, not immediately preceded by the first colon in the <a>IRI</a>.
-					The local names of the <a>values</a> of <code>sh:predicate</code> must fulfill the following conditions (to ensure that a correct mapping from parameters into SPARQL variables is possible):
+					The <dfn data-lt="parameter names">parameter name</dfn> is defined as the <a>local name</a> of the <a>value</a> of <code>sh:predicate</code>.
+					To ensure that a correct mapping from parameters into SPARQL variables is possible, every <a>parameter name</a>:
 				</p>
 				<ul>
-					<li>The <a>local name</a> must be a valid <a href="http://www.w3.org/TR/sparql11-query/#rVARNAME">SPARQL VARNAME</a></li>
-					<li>There must not be any other declared <a>parameter</a> for the same <a>constraint component</a> that has a <code>sh:predicate</code> with the same <a>local name</a></li>
-					<li>The <a>local name</a> must not be <code>this</code>, <code>shapesGraph</code> or <code>currentShape</code>.</li>
-					<li>The <a>local name</a> must not be <code>focusNode</code>, <code>path</code> or <code>value</code>.</li>
+					<li>Must be a valid <a href="http://www.w3.org/TR/sparql11-query/#rVARNAME">SPARQL VARNAME</a></li>
+					<li>Must not be equal to <code>this</code>, <code>shapesGraph</code>, <code>currentShape</code>, <code>focusNode</code>, <code>predicate</code>, <code>path</code> or <code>value</code>.</li>
+					<li>Must not be equal to another <a>parameter name</a> in the same <a>constraint component</a></li>
 				</ul>
 				<p>
 					An <code>sh:Parameter</code> may have its property <code>sh:optional</code> set to <code>true</code>
@@ -3683,6 +3684,13 @@ <h3>Parameters Declaration (sh:parameter)</h3>
 					but also constraint parameters such as <code>sh:class</code>.
 					Some implementations MAY use these constraint parameters to prevent the execution of constraint components with invalid parameter values.
 				</p>
+				<section id="constraint-components-parameter-pre-binding">
+					<h4>Parameter pre-binding</h4>
+					<p>
+						Every <a>parameter name</a> defines a <a>pre-bound</a> variable for the <a>constraint component</a> the parameter belongs to.
+						This variable can be used in the SPARQL definition of the <a>constraint component</a>  and the SHACL engine MUST <a>pre-bind</a> it to the parameter value.
+					</p>
+				</section>
 			</section>
 			<section id="labelTemplate">
 				<h3>Label Templates (sh:labelTemplate)</h3>
@@ -4250,6 +4258,28 @@ <h2>Pre-binding of Variables in SPARQL Queries</h2>
 				so that they have the provided value.
 				In other words, whenever a SPARQL processor evaluates a pre-bound variable, it must use the given value.
  			</p>
+
+			<section id="pre-bindound-variables">
+				<h3>Pre-bound variables</h3>
+				<p>
+					SHACL defines two forms of variable pre-binding:
+				</p>
+				<ol>
+			        <li><a href="#sparql-constraints-prebound">Global pre-bound variables</a> that are available in all SPARQL-based constraints, SPARQL-based constraint components and SPARQL-based targets.</li>
+					<li>Local pre-bound variables available only within a SPARQL-based constraint component and defined through the <a href="#constraint-components-parameter-pre-binding">component parameters</a> </li>
+				</ol>
+				<p>
+					The variable <code>path</code> has a special treatment in SHACL and must be processed before any other pre-bound variable.
+					SHACL processors must perform string substitution of every occurrence of the variable <code>path</code> to the <a href="#path-syntax">generated SPARQL property path</a> before performing any pre-binding.
+				</p>
+				<p>
+					The variable <code>predicate</code> is not a pre-bound variable in SHACL and when used and will be treated as a normal SPARQL variable.
+					Users are expected to use <code>path</code> instead of <code>predicate</code>.
+					<br/>><span class="todo">should we disallow the variable predicate instead to avoid confusion?</span>
+				</p>
+
+			</section>
+
 		</section>
 
 		<section id="ack" class="appendix informative">