#327: Added section on Annotations (#330)

* #327: Added section on Annotations

* Apply suggestions from code review

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

* #327: Fixed trivial grammar error

---------

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Author: HolgerKnublauch

shacl12-sparql/index.html

@@ -1206,7 +1206,113 @@ <h3>Validation with SPARQL-based Constraint Components</h3>
 				</p>
 			</section>
 		</section>
-		
+				
+		<section id="sparql-constraints-annotations">
+			<h2>Annotation Properties</h2>
+			<p>
+				This section extends the general <a href="#sparql-constraints-variables">mechanism</a>
+				to produce validation results using <a href="sparql-constraints">SPARQL-based constraints</a> or
+				<a href="sparql-constraint-components">constraint components</a>.
+			</p>
+			<p>
+				Implementations that support this feature make it possible to inject <dfn>annotation properties</dfn>
+				into the validation result nodes created for each <a>solution</a> produced by the <code>SELECT</code> queries of a
+				SPARQL-based <a>constraint</a> or <a>constraint component</a>.
+				Any such annotation property needs to be declared via a <a>value</a> of <code>sh:resultAnnotation</code> at
+				the <a>subject</a> of the <code>sh:select</code> or <code>sh:ask</code> <a>triple</a>.
+			</p>
+			<p class="syntax">
+				<span data-syntax-rule="resultAnnotation-nodeKind">The <a>values</a> of <code>sh:resultAnnotation</code> are
+				called <dfn data-lt="result annotation">result annotations</dfn> and are either <a>IRIs</a> or <a>blank nodes</a></span>.
+			</p>
+			<p>
+				<a>Result annotations</a> have the following properties:
+			</p>
+			<table class="term-table">
+				<tr>
+					<th>Property</th>
+					<th>Summary and Syntax Rules</th>
+				</tr>
+				<tr>
+					<td><code>sh:annotationProperty</code></td>
+					<td>
+						The property that shall be set.
+						<span data-syntax-rule="annotationProperty">Each <a>result annotation</a> has exactly one <a>value</a>
+						for the property <code>sh:annotationProperty</code> and this value is an <a>IRI</a>.</span>
+					</td>
+				</tr>
+				<tr>
+					<td><code>sh:annotationVarName</code></td>
+					<td>
+						The name of the SPARQL variable to take the annotation values from.
+						<span data-syntax-rule="annotationVarName">Each <a>result annotation</a> has at most 1 <a>value</a>
+						for the property <code>sh:annotationVarName</code> and this <a>value</a> is <a>literal</a> with
+						<a>datatype</a> <code>xsd:string</code>.</span>
+					</td>
+				</tr>
+				<tr>
+					<td><code>sh:annotationValue</code></td>
+					<td>
+						Constant <a>RDF terms</a> that shall be used as default values.
+					</td>
+				</tr>
+			</table>
+			<p>
+				For each <a>solution</a> of a <code>SELECT</code> result set, a SHACL processor that supports annotations
+				walks through the declared result annotations.
+				The mapping from result annotations to SPARQL variables uses the following rules:
+			</p>
+			<ol>
+				<li>Use the <a>value</a> of the property <code>sh:annotationVarName</code></li>
+				<li>If no such <a>value</a> exists, use the <a>local name</a> of the <a>value</a> of <code>sh:annotationProperty</code> 
+				as the variable name.</li>
+			</ol>
+			<p>
+				If a variable name could be determined, then the SHACL processor copies the <a>binding</a> for the given variable
+				as a value for the property specified using <code>sh:annotationProperty</code> 
+				into the validation result that is being produced for the current <a>solution</a>.
+				If the variable has no <a>binding</a> in the result set <a>solution</a>,
+				then the <a>values</a> of <code>sh:annotationValue</code> are used, if present.
+			</p>
+			<p>
+				Here is an example illustrating the use of result annotations.
+			</p>
+			<pre class="example-shapes">
+ex:AnnotationExample
+	a sh:NodeShape ;
+	sh:targetNode ex:ExampleResource ;
+	sh:sparql [   # _:b1
+		sh:resultAnnotation [
+			sh:annotationProperty ex:time ;
+			sh:annotationVarName "time" ;
+		] ;
+		sh:select """
+			SELECT $this ?message ?time
+			WHERE {
+				BIND (CONCAT("The ", "message.") AS ?message) .
+				BIND (NOW() AS ?time) .
+			}
+			""" ;
+	] .</pre>
+			<p>
+				Validation produces the following validation report:
+			</p>
+			<pre class="example-results">
+[	a sh:ValidationReport ;
+	sh:conforms false ;
+	sh:result [
+		a sh:ValidationResult ;
+		sh:focusNode ex:ExampleResource ;
+		sh:resultMessage "The message." ;
+		sh:resultSeverity sh:Violation ;
+		sh:sourceConstraint _:b1 ;
+		sh:sourceConstraintComponent sh:SPARQLConstraintComponent ;
+		sh:sourceShape ex:AnnotationExample ;
+		ex:time "2015-03-27T10:58:00"^^xsd:dateTime ;  # Example
+	]
+] .</pre>
+		</section>
+
 		<section id="sparql-node-expressions">
 			<h2>SPARQL-based Node Expressions</h2>
 			<p>
@@ -1734,6 +1840,7 @@ <h2>Revision History</h2>
 			<h2>Changes between SHACL 1.0 SPARQL and SHACL 1.2 SPARQL Extensions</h2>
 			<ul>
 				<li>Added the <a>node expression function</a> <a href="#SelectExpression"><code>sh:SelectExpression</code></a>, see <a href="https://github.com/w3c/data-shapes/issues/288">Issue 288</a></li>
+				<li>Added support for <a>annotation properties</a>, see <a href="https://github.com/w3c/data-shapes/issues/327">Issue 327</a></li>
 				<li>Added the <a>node expression function</a> <a href="#SPARQLExprExpression"><code>sh:SPARQLExprExpression</code></a>, see <a href="https://github.com/w3c/data-shapes/issues/315">Issue 315</a></li>
 			</ul>
 		</section>