Skip to content

Commit d72b95d

Browse files
edmondchucedmondchuc
authored
Merge pull request #651 from w3c/ui/property-roles
[UI] Add property roles section
2 parents 418e25b + 8c619e4 commit d72b95d

File tree

1 file changed

+149
-0
lines changed

1 file changed

+149
-0
lines changed

‎shacl12-ui/index.html‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -537,6 +537,19 @@ <h3>Document Conventions</h3>
537537
<section id="conformance">
538538
<p>TODO</p>
539539
</section>
540+
541+
<section id="compatibility">
542+
<h2>RDF Abstract Model Compatibility</h2>
543+
544+
<p class="ednote">
545+
At the time of writing, RDF 1.2 is a Working Draft. This section will be reviewed and updated when RDF 1.2 becomes a W3C Recommendation.
546+
</p>
547+
548+
<p>
549+
SHACL Renderers implementing this specification MUST support RDF 1.1 and SHOULD support RDF 1.2. When RDF 1.2 is supported, and unless
550+
stated otherwise in this document, implementations SHOULD prefer RDF 1.2 syntax and data model features over their RDF 1.1 counterparts.
551+
</p>
552+
</section>
540553
</section>
541554

542555
<section id="widgets">
@@ -1539,6 +1552,142 @@ <h4>shui:ValueTableViewer</h4>
15391552
</section>
15401553
</section>
15411554

1555+
<section id="property-roles">
1556+
<h2>Property Roles</h2>
1557+
1558+
<p>
1559+
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.
1560+
However, the vocabularies defining these properties vary across domains and communities. To ensure consistent interpretation, property shapes can
1561+
be annotated with explicit roles for elements such as labels, descriptions, and other rendering properties.
1562+
</p>
1563+
1564+
<p>
1565+
This section introduces Property Roles for annotating SHACL property shapes, along with several built-in property roles defined in the SHUI namespace.
1566+
Property Roles are defined in the SHUI namespace and define the class <code>shui:PropertyRole</code> and the property <code>shui:propertyRole</code>.
1567+
</p>
1568+
1569+
<h3>Direct Role Annotation</h3>
1570+
1571+
<p>
1572+
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.
1573+
SHACL renderers may use such direct annotations to drive the way specific user-interface elements are displayed.
1574+
</p>
1575+
1576+
<p>
1577+
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.
1578+
When this is done, the resulting behavior is undefined.
1579+
</p>
1580+
1581+
<p>
1582+
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
1583+
represent human-readable labels for resources.
1584+
</p>
1585+
1586+
<aside class="example" title="Direct role annotation">
1587+
<div class="shapes-graph">
1588+
<div class="turtle">
1589+
ex:Label a sh:PropertyShape ;
1590+
sh:path skos:prefLabel ;
1591+
shui:propertyRole shui:LabelRole ;
1592+
.
1593+
</div>
1594+
</div>
1595+
<p>
1596+
This example illustrates the common case where a property shape is directly annotated with <code>shui:LabelRole</code>.
1597+
This informs user-interfaces that the shape's value nodes represent human-readable labels for resources.
1598+
</p>
1599+
</aside>
1600+
1601+
<h3>Qualified Role Annotation</h3>
1602+
1603+
<p>When multiple predicates serve the same role in the data but require a defined precedence, the qualified role annotation should be used.</p>
1604+
1605+
<p>
1606+
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
1607+
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
1608+
using a qualified role annotation is always preferred over a shape using a direct, unqualified role annotation.
1609+
</p>
1610+
1611+
<aside class="example" title="Qualified role annotation">
1612+
<div class="shapes-graph">
1613+
<div class="turtle">
1614+
ex:PrefLabel a sh:PropertyShape ;
1615+
sh:path skos:prefLabel ;
1616+
shui:propertyRole [
1617+
shui:propertyRole shui:LabelRole ;
1618+
sh:order 0
1619+
]
1620+
.
1621+
1622+
ex:Name a sh:PropertyShape ;
1623+
sh:path schema:name ;
1624+
shui:propertyRole [
1625+
shui:propertyRole shui:LabelRole ;
1626+
sh:order 1
1627+
]
1628+
.
1629+
</div>
1630+
</div>
1631+
<p>
1632+
The following example demonstrates two property shapes with qualified role annotations ordered by <code>sh:order</code>.
1633+
</p>
1634+
</aside>
1635+
1636+
<p>
1637+
The qualified role annotation can also be expressed using triple annotations. SHACL Renderers that support RDF 1.2
1638+
should support the triple annotation syntax in addition to the RDF 1.1-compatible qualified role annotation syntax.
1639+
</p>
1640+
1641+
<aside class="example" title="Qualified role annotation using triple annotations">
1642+
<div class="shapes-graph">
1643+
<div class="turtle">
1644+
ex:PrefLabel a sh:PropertyShape ;
1645+
sh:path skos:prefLabel ;
1646+
shui:propertyRole shui:LabelRole {| sh:order 0 |}
1647+
.
1648+
1649+
ex:Name a sh:PropertyShape ;
1650+
sh:path schema:name ;
1651+
shui:propertyRole shui:LabelRole {| sh:order 1 |}
1652+
.
1653+
</div>
1654+
</div>
1655+
<p>
1656+
This example demonstrates two property shapes with qualified role annotations ordered by <code>sh:order</code> using RDF 1.2 triple annotations.
1657+
</p>
1658+
</aside>
1659+
1660+
<h3>Built-in Property Roles</h3>
1661+
1662+
<p>
1663+
The following sections define the instances of <code>shui:PropertyRole</code> in the SHUI namespace. These property roles MUST be supported
1664+
by SHACL Renderers. Additional property roles may be defined in other namespaces.
1665+
</p>
1666+
1667+
<h4>shui:LabelRole</h4>
1668+
1669+
<p>
1670+
The <code>shui:LabelRole</code> is used to identify properties whose values serve as human-readable display labels.
1671+
Common examples of display label predicates include <code>rdfs:label</code>, <code>skos:prefLabel</code>, and <code>schema:name</code>.
1672+
</p>
1673+
1674+
<h3>Definitions</h3>
1675+
1676+
<h4>shui:PropertyRole Class</h4>
1677+
1678+
<p>
1679+
The class of roles that a property shape may take with respect to its focus nodes. It is not required, but recommended, that roles
1680+
defined in other namespaces subclass <code>shui:PropertyRole</code>.
1681+
</p>
1682+
1683+
<h4>shui:propertyRole Property</h4>
1684+
1685+
<p>
1686+
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
1687+
resource that itself declares a <code>shui:propertyRole</code> and an associated <code>sh:order</code> value.
1688+
</p>
1689+
</section>
1690+
15421691
<section id="syntax-rules" class="appendix">
15431692
<h2>Summary of Syntax Rules from this Specification</h2>
15441693
</section>

0 commit comments

Comments
 (0)