From 56268bacbfe03685b6c4ed248cd0aadc2d04d745 Mon Sep 17 00:00:00 2001 From: Edmond Chuc Date: Mon, 17 Nov 2025 12:29:13 +1000 Subject: [PATCH 1/4] Add property roles section --- shacl12-ui/index.html | 136 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/shacl12-ui/index.html b/shacl12-ui/index.html index 51786875..327fd01f 100644 --- a/shacl12-ui/index.html +++ b/shacl12-ui/index.html @@ -1513,6 +1513,142 @@

Other Complex Paths

+
+

Property Roles

+ +

+ RDF resources commonly use properties to specify labels and descriptions, 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. +

+ +

+ 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 shui:PropertyRole and the property shui:propertyRole. +

+ +

Direct Role Annotation

+ +

+ Property roles can be annotated on property shapes by using the shui:propertyRole 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. +

+ +

+ 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. +

+ +

+ 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. +

+ + + +

Qualified Role Annotation

+ +

When multiple predicates serve the same role in the data but require a defined precedence, the qualified role annotation should be used.

+ +

+ For property shapes annotated with the same role, user interfaces should prefer the shape with the smallest sh:order value. If multiple shapes + share the same role, they must be sorted and processed in ascending order of their sh:order values. In addition, any property shape + using a qualified role annotation is always preferred over a shape using a direct, unqualified role annotation. +

+ + + +

+ 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. +

+ + + +

Core Property Roles

+ +

+ The following sections define the instances of shui:PropertyRole in the SHUI namespace. These property roles MUST be supported + by SHACL Renderers. Additional property roles may be defined in other namespaces. +

+ +

shui:LabelRole

+ +

+ The shui:LabelRole is used to identify properties whose values serve as human-readable display labels. + Common examples of display label predicates include rdfs:label, skos:prefLabel, and schema:name. +

+ +

Definitions

+ +

shui:PropertyRole Class

+ +

+ 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 shui:PropertyRole. +

+ +

shui:propertyRole Property

+ +

+ The property used to annotate property shapes with roles. Its value is expected to be either an instance of shui:PropertyRole or a + resource that itself declares a shui:propertyRole and an associated sh:order value. +

+
+

Summary of Syntax Rules from this Specification

From 757a08de581745738ced4f399ae6df87dbd2c6e8 Mon Sep 17 00:00:00 2001 From: Edmond Chuc <37032744+edmondchuc@users.noreply.github.com> Date: Tue, 18 Nov 2025 14:47:30 +1000 Subject: [PATCH 2/4] Apply suggestion from @bergos and @TallTed Co-authored-by: Ted Thibodeau Jr --- shacl12-ui/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shacl12-ui/index.html b/shacl12-ui/index.html index 327fd01f..b667eaad 100644 --- a/shacl12-ui/index.html +++ b/shacl12-ui/index.html @@ -1517,7 +1517,7 @@

Other Complex Paths

Property Roles

- RDF resources commonly use properties to specify labels and descriptions, which user-interface engines depend on to render structured content. + 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.

From 0348362af06de905dc128b26bc371cf6c240f490 Mon Sep 17 00:00:00 2001 From: Edmond Chuc <37032744+edmondchuc@users.noreply.github.com> Date: Tue, 18 Nov 2025 15:43:04 +1000 Subject: [PATCH 3/4] Apply suggestion from @bergos and @TallTed Co-authored-by: Ted Thibodeau Jr --- shacl12-ui/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shacl12-ui/index.html b/shacl12-ui/index.html index b667eaad..2dc289a0 100644 --- a/shacl12-ui/index.html +++ b/shacl12-ui/index.html @@ -1519,7 +1519,7 @@

Property Roles

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. + be annotated with explicit roles for elements such as labels, descriptions, and other rendering properties.

From 3d3492f67eac0d53845a82d2efcac2cc72e8ae3c Mon Sep 17 00:00:00 2001 From: Edmond Chuc <37032744+edmondchuc@users.noreply.github.com> Date: Tue, 18 Nov 2025 15:45:12 +1000 Subject: [PATCH 4/4] Apply @TallTed suggestions from code review Co-authored-by: Ted Thibodeau Jr --- shacl12-ui/index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/shacl12-ui/index.html b/shacl12-ui/index.html index 2dc289a0..232079a3 100644 --- a/shacl12-ui/index.html +++ b/shacl12-ui/index.html @@ -1524,19 +1524,19 @@

Property Roles

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 shui:PropertyRole and the property shui:propertyRole. + Property Roles are defined in the SHUI namespace and define the class shui:PropertyRole and the property shui:propertyRole.

Direct Role Annotation

Property roles can be annotated on property shapes by using the shui:propertyRole 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. + SHACL renderers may use such direct annotations to drive the way specific user-interface elements are displayed.

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. + When this is done, the resulting behavior is undefined.