ISSUE-220: Added explanatory paragraph and new section on finding shapes

shacl/index.html

@@ -280,6 +280,7 @@ <h2>Revision History</h2>
 				The detailed list of changes and their diffs can be found in the <a href="https://github.com/w3c/data-shapes/commits/gh-pages/shacl/index.html">Git repository</a>.
 			</p>
 			<ul>
+				<li><b>2017-01-26</b>: Added section on "Finding Shapes" (<a href="http://www.w3.org/2014/data-shapes/track/issues/220">ISSUE-220</a>)</li>
 				<li><b>2017-01-26</b>: Added sh:xor (<a href="http://www.w3.org/2014/data-shapes/track/issues/219">ISSUE-219</a>)</li>
 				<li><b>2017-01-24</b>: New definition of pre-binding (first draft based on <a href="https://w3c.github.io/sparql-exists/docs/sparql-exists.html">SPARQL EXISTS CG Draft Report</a>) (<a href="http://www.w3.org/2014/data-shapes/track/issues/68">ISSUE-68</a>)</li>
 				<li><b>2017-01-19</b>: Moved SPARQL annotation properties mechanism to advanced features WG Note in anticipation of the vote on (<a href="http://www.w3.org/2014/data-shapes/track/issues/218">ISSUE-218</a>)</li>
@@ -942,6 +943,13 @@ <h3>Shapes</h3>
 				<p class="syntax" data-syntax-rule="shape-nodeKind">
 					A <dfn data-lt="shape|shapes">shape</dfn> is an <a>IRI</a> or <a>blank node</a> in the <a>shapes graph</a>.
 				</p>
+				<p>
+					Note that the definition above does not include the syntax rules of <a>well-formed</a> shapes.
+					Those are found throughout the document and summarized in Appendix <a href="#syntax-rules"></a>.
+					For example, shapes that have <a>literals</a> as values for <code>sh:targetClass</code> are <a>ill-formed</a>.
+					Also see section <a href="#shapes-finding"></a> on practical guidance on how to distinguish shapes
+					from other <a>IRIs</a> or <a>blank nodes</a> in a graph.
+				</p>
 				<p>
 					Informally, a shape determines how to validate a <a>focus node</a> based on the <a>values</a> of properties and other characteristics of the focus node.
 					For example, shapes can declare the condition that a focus node be an IRI or that a focus node has a particular value for a property and also a minimum number of values for the property.
@@ -1430,10 +1438,36 @@ <h4>Deactivating a Shape</h4>
 					<pre class="example-data">
 ex:JohnDoe a ex:Person .</pre>
 				</section>
+
+				<section id="shapes-finding" class="informative">
+					<h4>Finding all Shapes in a Graph</h4>
+					<p>
+						The definition of what a <a>shape</a> is from section <a href="#shapes"></a> is minimalistic and does not provide sufficient conditions to
+						distinguish shapes from any other <a>IRI</a> or <a>blank node</a> in a <a>shapes graph</a>.
+						However, some applications, such as user interface tools, may want to identify all shapes in a given graph.
+						Depending on the application, the following rules are recommended to identify shapes:
+					</p>
+					<ul>
+						<li>
+							All <a>SHACL instances</a> of <code>sh:NodeShape</code> or <code>sh:PropertyShape</code>.
+						</li>
+						<li>
+							All <a>subjects</a> of triples that have <code>sh:targetClass</code>, <code>sh:targetNode</code>,
+							<code>sh:targetObjectsOf</code> or <code>sh:targetSubjectsOf</code> as <a>predicate</a>.
+						</li>
+						<li>
+							All <a>subjects</a> of triples that have a <a>parameter</a> as <a>predicate</a>.
+						</li>
+						<li>
+							All <a>values</a> of <a>shape-expecting constraint parameters</a> such as <code>sh:shape</code>,
+							including handling of those that are <a>list-taking constraint parameters</a> such as <code>sh:or</code>.
+						</li>
+					</ul>
+				</section>
 			</section>
 
 			<section id="node-shapes">
-				<h4>Node Shapes</h4>
+				<h3>Node Shapes</h3>
 				<p class="syntax">
 					A <dfn data-lt="node shapes">node shape</dfn> is a <a>shape</a> in the <a>shapes graph</a> that
 					is not the <a>subject</a> of a <a>triple</a> with <code>sh:path</code> as its <a>predicate</a>.
@@ -1449,7 +1483,7 @@ <h4>Node Shapes</h4>
 			</section>
 
 			<section id="property-shapes">
-				<h4>Property Shapes</h4>
+				<h3>Property Shapes</h3>
 				<p class="syntax">
 					<span data-syntax-rule="PropertyShape">A <dfn data-lt="property shapes">property shape</dfn> must be the <a>subject</a> of a <a>triple</a> that has <code>sh:path</code> as its <a>predicate</a>.</span>
 					<span data-syntax-rule="path-maxCount">A node that has more than one <a>value</a> for <code>sh:path</code> is <a>ill-formed</a>.</span>