[UI] Add property roles section

shacl12-ui/index.html

@@ -1513,6 +1513,142 @@ <h4>Other Complex Paths</h4>
         </section>
     </section>
 
+    <section id="property-roles">
+      <h2>Property Roles</h2>
+
+      <p>
+        RDF resources commonly use properties to specify labels, descriptions, and other information needed for rendering, which user-interface engines depend on to render structured content.
+        However, the vocabularies defining these properties vary across domains and communities. To ensure consistent interpretation, property shapes can
+        be annotated with explicit roles for elements such as labels and descriptions.
+      </p>
+
+      <p>
+        This section introduces Property Roles for annotating SHACL property shapes along with several core property roles defined in the SHUI namespace.
+        Property Roles is defined in the SHUI namespace and defines the class <code>shui:PropertyRole</code> and the property <code>shui:propertyRole</code>.
+      </p>
+
+      <h3>Direct Role Annotation</h3>
+
+      <p>
+        Property roles can be annotated on property shapes by using the <code></code>shui:propertyRole</code> predicate and linking directly to a property role instance. 
+        SHACL renderers may use this direct annotation to drive how specific user-interface elements are displayed.
+      </p>
+
+      <p>
+        It is possible but not recommended to assign the same property role to multiple property shapes that apply to the same focus node using the direct role annotation form. 
+        When this occurs, the resulting behavior is undefined.
+      </p>
+
+      <p>
+        The example below illustrates the common case where a property shape is directly annotated with shui:LabelRole. This informs user-interfaces that the shape's value nodes
+        represent human-readable labels for resources.
+      </p>
+
+      <aside class="example" title="Direct role annotation">
+        <div class="shapes-graph">
+          <div class="turtle">
+ex:Label a sh:PropertyShape ;
+    sh:path skos:prefLabel ;
+    shui:propertyRole shui:LabelRole ;
+.
+          </div>
+        </div>
+        <p>
+          This example illustrates the common case where a property shape is directly annotated with <code>shui:LabelRole</code>. 
+          This informs user-interfaces that the shape's value nodes represent human-readable labels for resources.
+        </p>
+      </aside>
+
+      <h3>Qualified Role Annotation</h3>
+
+      <p>When multiple predicates serve the same role in the data but require a defined precedence, the qualified role annotation should be used.</p>
+
+      <p>
+        For property shapes annotated with the same role, user interfaces should prefer the shape with the smallest <code>sh:order</code> value. If multiple shapes
+        share the same role, they must be sorted and processed in ascending order of their <code>sh:order</code> values. In addition, any property shape
+        using a qualified role annotation is always preferred over a shape using a direct, unqualified role annotation.
+      </p>
+
+      <aside class="example" title="Qualified role annotation">
+        <div class="shapes-graph">
+          <div class="turtle">
+ex:PrefLabel a sh:PropertyShape ;
+sh:path skos:prefLabel ;
+shui:propertyRole [
+    shui:propertyRole shui:LabelRole ;
+    sh:order 0
+]
+.
+
+ex:Name a sh:PropertyShape ;
+sh:path schema:name ;
+shui:propertyRole [
+    shui:propertyRole shui:LabelRole ;
+    sh:order 1
+]
+.
+          </div>
+        </div>
+        <p>
+          The following example demonstrates two property shapes with qualified role annotations ordered by <code>sh:order</code>.
+        </p>
+      </aside>
+
+      <p>
+        The qualified role annotation can also be expressed using triple annotations. SHACL Renderers that support RDF 1.2
+        should support the triple annotation syntax in addition to the RDF 1.1-compatible qualified role annotation syntax.
+      </p>
+
+      <aside class="example" title="Qualified role annotation using RDF 1.2 triple annotations">
+        <div class="shapes-graph">
+          <div class="turtle">
+ex:PrefLabel a sh:PropertyShape ;
+    sh:path skos:prefLabel ;
+    shui:propertyRole shui:LabelRole {| sh:order 0 |}
+.
+
+ex:Name a sh:PropertyShape ;
+    sh:path schema:name ;
+    shui:propertyRole shui:LabelRole {| sh:order 1 |}
+.
+          </div>
+        </div>
+        <p>
+          This example demonstrates two property shapes with qualified role annotations ordered by <code>sh:order</code> using RDF 1.2 triple annotations.
+        </p>
+      </aside>
+
+      <h3>Core Property Roles</h3>
+
+      <p>
+        The following sections define the instances of <code>shui:PropertyRole</code> in the SHUI namespace. These property roles MUST be supported
+        by SHACL Renderers. Additional property roles may be defined in other namespaces.
+      </p>
+
+      <h4>shui:LabelRole</h4>
+
+      <p>
+        The <code>shui:LabelRole</code> is used to identify properties whose values serve as human-readable display labels.
+        Common examples of display label predicates include <code>rdfs:label</code>, <code>skos:prefLabel</code>, and <code>schema:name</code>.
+      </p>
+
+      <h3>Definitions</h3>
+
+      <h4>shui:PropertyRole Class</h4>
+
+      <p>
+        The class of roles that a property shape may take with respect to its focus nodes. It is not required, but recommended, that roles
+        defined in other namespaces subclass <code>shui:PropertyRole</code>.
+      </p>
+
+      <h4>shui:propertyRole Property</h4>
+
+      <p>
+        The property used to annotate property shapes with roles. Its value is expected to be either an instance of <code>shui:PropertyRole</code> or a
+        resource that itself declares a <code>shui:propertyRole</code> and an associated <code>sh:order</code> value.
+      </p>
+    </section>
+
     <section id="syntax-rules" class="appendix">
       <h2>Summary of Syntax Rules from this Specification</h2>
     </section>