From b5effe840fe5fbc30a0d50994ebad65487b2cfc5 Mon Sep 17 00:00:00 2001 From: Edmond Chuc Date: Mon, 8 Jun 2026 14:39:26 +1000 Subject: [PATCH 01/18] Add UI getting started section --- .../shacl-renderer-data-graph.drawio.svg | 270 ++++++++++ .../shacl-renderer-shapes-graph-01.drawio.svg | 299 +++++++++++ .../shacl-renderer-shapes-graph-02.drawio.svg | 299 +++++++++++ ...shacl-renderer-timbl-w3c-nested.drawio.svg | 474 ++++++++++++++++ .../shacl-renderer-timbl-w3c.drawio.svg | 345 ++++++++++++ shacl12-ui/index.html | 505 +++++++++++++++++- 6 files changed, 2184 insertions(+), 8 deletions(-) create mode 100644 shacl12-ui/images/diagrams/shacl-renderer-data-graph.drawio.svg create mode 100644 shacl12-ui/images/diagrams/shacl-renderer-shapes-graph-01.drawio.svg create mode 100644 shacl12-ui/images/diagrams/shacl-renderer-shapes-graph-02.drawio.svg create mode 100644 shacl12-ui/images/diagrams/shacl-renderer-timbl-w3c-nested.drawio.svg create mode 100644 shacl12-ui/images/diagrams/shacl-renderer-timbl-w3c.drawio.svg diff --git a/shacl12-ui/images/diagrams/shacl-renderer-data-graph.drawio.svg b/shacl12-ui/images/diagrams/shacl-renderer-data-graph.drawio.svg new file mode 100644 index 000000000..013a25534 --- /dev/null +++ b/shacl12-ui/images/diagrams/shacl-renderer-data-graph.drawio.svg @@ -0,0 +1,270 @@ + + + + + + + + + + + + + +
+
+
+ John +
+
+
+ + + John + + + + + + + + + + + +
+
+
+ Additional Name +
+
+
+ + + Additional Name + + + + + + + + + + + +
+
+
+ Birth Date +
+
+
+ + + Birth Date + + + + + + + + + + + +
+
+
+ Family Name +
+
+
+ + + Family Name + + + + + + + + + + + +
+
+
+ Given Name +
+
+
+ + + Given Name + + + + + + + + + + + +
+
+
+ Honorific Prefix +
+
+
+ + + Honorific Prefix + + + + + + + + + + + +
+
+
+ Tim B L +
+
+
+ + + Tim B L + + + + + + + + + + + +
+
+
+ 08 / 06 / 1955 +
+
+
+ + + 08 / 06 / 1955 + + + + + + + + + + + +
+
+
+ Berners-Lee +
+
+
+ + + Berners-Lee + + + + + + + + + + + +
+
+
+ Tim +
+
+
+ + + Tim + + + + + + + + + + + +
+
+
+ Sir +
+
+
+ + + Sir + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/shacl12-ui/images/diagrams/shacl-renderer-shapes-graph-01.drawio.svg b/shacl12-ui/images/diagrams/shacl-renderer-shapes-graph-01.drawio.svg new file mode 100644 index 000000000..7f3ee79d3 --- /dev/null +++ b/shacl12-ui/images/diagrams/shacl-renderer-shapes-graph-01.drawio.svg @@ -0,0 +1,299 @@ + + + + + + + + + + + + + +
+
+
+ Tim B L +
+
+
+ + + Tim B L + + + + + + + + + + + +
+
+
+ Name +
+
+
+ + + Name + + + + + + + + + + + +
+
+
+ Sir +
+
+
+ + + Sir + + + + + + + + + + + +
+
+
+ Honorific Prefix +
+
+
+ + + Honorific Prefix + + + + + + + + + + + +
+
+
+ Given Name +
+
+
+ + + Given Name + + + + + + + + + + + +
+
+
+ Additional Name +
+
+
+ + + Additional Name + + + + + + + + + + + +
+
+
+ Family Name +
+
+
+ + + Family Name + + + + + + + + + + + +
+
+
+ Birth Date +
+
+
+ + + Birth Date + + + + + + + + + + + +
+
+
+ Tim +
+
+
+ + + Tim + + + + + + + + + + + +
+
+
+ John +
+
+
+ + + John + + + + + + + + + + + +
+
+
+ Berners-Lee +
+
+
+ + + Berners-Lee + + + + + + + + + + + +
+
+
+ + 08 / 06 / 1955 + +
+
+
+ + + 08 / 06 / 1955 + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/shacl12-ui/images/diagrams/shacl-renderer-shapes-graph-02.drawio.svg b/shacl12-ui/images/diagrams/shacl-renderer-shapes-graph-02.drawio.svg new file mode 100644 index 000000000..6e7d41ce8 --- /dev/null +++ b/shacl12-ui/images/diagrams/shacl-renderer-shapes-graph-02.drawio.svg @@ -0,0 +1,299 @@ + + + + + + + + + + + + + +
+
+
+ Sir Tim Berners-Lee +
+
+
+ + + Sir Tim Berners-Lee + + + + + + + + + + + +
+
+
+ Name +
+
+
+ + + Name + + + + + + + + + + + +
+
+
+ Sir +
+
+
+ + + Sir + + + + + + + + + + + +
+
+
+ Honorific Prefix +
+
+
+ + + Honorific Prefix + + + + + + + + + + + +
+
+
+ Given Name +
+
+
+ + + Given Name + + + + + + + + + + + +
+
+
+ Additional Name +
+
+
+ + + Additional Name + + + + + + + + + + + +
+
+
+ Family Name +
+
+
+ + + Family Name + + + + + + + + + + + +
+
+
+ Birth Date +
+
+
+ + + Birth Date + + + + + + + + + + + +
+
+
+ Tim +
+
+
+ + + Tim + + + + + + + + + + + +
+
+
+ John +
+
+
+ + + John + + + + + + + + + + + +
+
+
+ Berners-Lee +
+
+
+ + + Berners-Lee + + + + + + + + + + + +
+
+
+ + 08 / 06 / 1955 + +
+
+
+ + + 08 / 06 / 1955 + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/shacl12-ui/images/diagrams/shacl-renderer-timbl-w3c-nested.drawio.svg b/shacl12-ui/images/diagrams/shacl-renderer-timbl-w3c-nested.drawio.svg new file mode 100644 index 000000000..b5cb1293e --- /dev/null +++ b/shacl12-ui/images/diagrams/shacl-renderer-timbl-w3c-nested.drawio.svg @@ -0,0 +1,474 @@ + + + + + + + + + + + + + +
+
+
+ Sir Tim Berners-Lee +
+
+
+ + + Sir Tim Berners-Lee + + + + + + + + + + + +
+
+
+ Name +
+
+
+ + + Name + + + + + + + + + + + +
+
+
+ Sir +
+
+
+ + + Sir + + + + + + + + + + + +
+
+
+ Honorific Prefix +
+
+
+ + + Honorific Prefix + + + + + + + + + + + +
+
+
+ Given Name +
+
+
+ + + Given Name + + + + + + + + + + + +
+
+
+ Additional Name +
+
+
+ + + Additional Name + + + + + + + + + + + +
+
+
+ Family Name +
+
+
+ + + Family Name + + + + + + + + + + + +
+
+
+ Birth Date +
+
+
+ + + Birth Date + + + + + + + + + + + +
+
+
+ Tim +
+
+
+ + + Tim + + + + + + + + + + + +
+
+
+ John +
+
+
+ + + John + + + + + + + + + + + +
+
+
+ Berners-Lee +
+
+
+ + + Berners-Lee + + + + + + + + + + + +
+
+
+ + 08 / 06 / 1955 + +
+
+
+ + + 08 / 06 / 1955 + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + + + + + + + +
+
+
+ Founder +
+
+
+ + + Founder + + + + + + + + + + + + + + +
+
+
+ World Wide Web Consortium +
+
+
+ + + World Wide Web Consortium + + + + + + + + + + + +
+
+
+ Name +
+
+
+ + + Name + + + + + + + + + + + +
+
+
+ 01 / 10 / 1994 +
+
+
+ + + 01 / 10 / 1994 + + + + + + + + + + + +
+
+
+ Founding Date +
+
+
+ + + Founding Date + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + +
+
+
+ + https://www.w3c.org + +
+
+
+ + + https://www.w3c.org + + + + + + + + + + + +
+
+
+ URL +
+
+
+ + + URL + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/shacl12-ui/images/diagrams/shacl-renderer-timbl-w3c.drawio.svg b/shacl12-ui/images/diagrams/shacl-renderer-timbl-w3c.drawio.svg new file mode 100644 index 000000000..49c290499 --- /dev/null +++ b/shacl12-ui/images/diagrams/shacl-renderer-timbl-w3c.drawio.svg @@ -0,0 +1,345 @@ + + + + + + + + + + + + + +
+
+
+ Sir Tim Berners-Lee +
+
+
+ + + Sir Tim Berners-Lee + + + + + + + + + + + +
+
+
+ Name +
+
+
+ + + Name + + + + + + + + + + + +
+
+
+ Sir +
+
+
+ + + Sir + + + + + + + + + + + +
+
+
+ Honorific Prefix +
+
+
+ + + Honorific Prefix + + + + + + + + + + + +
+
+
+ Given Name +
+
+
+ + + Given Name + + + + + + + + + + + +
+
+
+ Additional Name +
+
+
+ + + Additional Name + + + + + + + + + + + +
+
+
+ Family Name +
+
+
+ + + Family Name + + + + + + + + + + + +
+
+
+ Birth Date +
+
+
+ + + Birth Date + + + + + + + + + + + +
+
+
+ Tim +
+
+
+ + + Tim + + + + + + + + + + + +
+
+
+ John +
+
+
+ + + John + + + + + + + + + + + +
+
+
+ Berners-Lee +
+
+
+ + + Berners-Lee + + + + + + + + + + + +
+
+
+ + 08 / 06 / 1955 + +
+
+
+ + + 08 / 06 / 1955 + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + + + + + + + +
+
+
+ Founder +
+
+
+ + + Founder + + + + + + + + + + + +
+
+
+ + + https://example.com/ns#W3C + + +
+
+
+ + + https://example.com/ns#W3C + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/shacl12-ui/index.html b/shacl12-ui/index.html index a6432c323..8305e76dd 100644 --- a/shacl12-ui/index.html +++ b/shacl12-ui/index.html @@ -187,7 +187,7 @@

Document Outline

Content.

-
+

Introduction

RDF applications commonly provide user interfaces that allow users to view and edit RDF resources. @@ -216,7 +216,7 @@

Introduction

shapes who wish to generate forms for their data.

-
+

Scope

The scope of this specification is limited to form rendering for viewing and editing RDF resources @@ -477,14 +477,26 @@

Document Conventions

rdfs: http://www.w3.org/2000/01/rdf-schema# + + schema: + http://schema.org/ + sh: http://www.w3.org/ns/shacl# + + shnex: + http://www.w3.org/ns/shacl-node-expr# + shui: http://www.w3.org/ns/shacl-ui# + + sparql: + http://www.w3.org/ns/sparql# + xsd: http://www.w3.org/2001/XMLSchema# @@ -505,8 +517,11 @@

Document Conventions

"@context": { "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", "rdfs": "http://www.w3.org/2000/01/rdf-schema#", + "schema": "http://schema.org/", "sh": "http://www.w3.org/ns/shacl#", + "shnex": "http://www.w3.org/ns/shacl-node-expr#", "shui": "http://www.w3.org/ns/shacl-ui#", + "sparql": "http://www.w3.org/ns/sparql#", "xsd": "http://www.w3.org/2001/XMLSchema#", "ex": "http://example.com/ns#", "dct": "http://purl.org/dc/terms/" @@ -614,13 +629,487 @@

RDF Abstract Model Compatibility

-
-

SHACL UI

-

- TODO: provide an introduction, use cases, and examples on SHACL UI basics. +

+

Getting Started with SHACL UI

+

+ This section introduces the basics of SHACL UI through a simple example. + By the end, you will understand how a SHACL Renderer uses SHACL Core + concepts to generate user interface forms, and how SHACL UI annotations + can tailor those forms to your use case. +

+ +

+ A goal of SHACL UI is to provide users with a simple way to generate + usable forms from a shapes graph and a data graph. This allows SHACL + shapes authors who are not necessarily software developers to inspect + how their shapes are interpreted as user interface forms, gather + feedback from collaborators, and prototype ideas without requiring + extensive software development effort.

-

Add conceptual model diagram and UI mockups to illustrate the concepts.

+
+

Data Graph Only

+ +

+ Let's start with defining a simple data graph that we'll use + throughout this section. +

+ + + +

+ With just the data graph, we have enough information for a SHACL + Renderer to generate a simple editable form. +

+ + A diagram of the ex:TimBL as a form in a SHACL Renderer. + +

+ There are a few SHACL UI concepts working together to render this + form. First, the labels in the form for the resource name and its + properties use Label Resolution to generate human-readable + labels. Second, the Scoring System + determines the most suitable editor widgets to render. Lastly, the + Scoring System has selected two widgets: + shui:DatePickerEditor + for the birth date field and + shui:TextFieldEditor for + the remaining fields. +

+ +
    +
  • + The resource ex:TimBL is displayed as + Tim B L. +
    • +
  • + The resource's properties are inherently unordered, so the + application has chosen to display them alphabetically. + In the next example, we will use SHACL annotations to define a more + logical ordering. +
    • +
  • + Given that the value of the birth date field is an + xsd:date, the Scoring System has determined that the + shui:DatePickerEditor widget is the most appropriate. + Note that date widgets may perform localized date formatting, so + for a user in Australia, the date may be displayed as + DD-MM-YYYY. +
    • +
  • + All other values are xsd:string, so the Scoring System + has selected shui:TextFieldEditor as the most + suitable widget for them. +
    • +
+
+ +
+

Adding a Shapes Graph

+

+ Now that we've seen how a SHACL Renderer can produce an editable form + from only a data graph, let's see how adding a shapes graph that + targets the resource affects the result. +

+ + + +

+ With both the data graph and shapes graph provided to the SHACL + Renderer, the editable form can use shape constraints for input + validation; see the related + Displaying Validation + Results pattern. The renderer also uses + sh:group and sh:order annotations to + control the form layout. In this example, the name-related properties + are grouped into a Name section and ordered + according to their sh:order values, while the birth + date is rendered separately because it does not belong to a group. +

+ +

+ The same shape also introduces simple cardinality constraints. + sh:minCount 1 marks the given name and family name as + required fields, while sh:maxCount 1 tells the renderer + that those fields and the birth date should be edited as single values. + Properties without sh:minCount remain optional, and + properties without sh:maxCount 1 may be rendered with + controls for adding more than one value. +

+ + A diagram of the ex:TimBL as a form in a SHACL Renderer. +
+ +
+

Computed Resource Labels

+

+ The data graph contains enough information to display a more useful + resource label than the resource's local name. Instead of rendering + the node as Tim B L, the shapes graph can define + a computed rdfs:label using a node expression. Label + Resolution then uses this computed label as the resource's display + name. +

+ + + +

+ The rendered form now uses the computed rdfs:label as + the resource label, so the resource is displayed by its full name + rather than its local name. +

+ + A diagram of the ex:TimBL as a form in a SHACL Renderer. +
+ +
+

Nested Resource Forms

+ +

+ RDF data commonly contains relationships between resources. So far, + we have shown how a SHACL Renderer generates a form for a single + resource. In some cases, however, editing a resource is easier when + the form also includes contextual information from related resources. + The following example demonstrates this pattern. +

+ + + + A diagram of the ex:TimBL as a form in a SHACL Renderer. + +

+ When rendering the form for the ex:TimBL resource, the + Scoring System would, by default, render the + schema:affiliation value using a + shui:IRIEditor, allowing the + user to reference another resource without displaying its properties. + However, it can be useful to show the ex:W3C resource + nested in the same view. To do this, we can configure the shape to + prefer the details editor for that property. +

+ + + +

+ With the new property shape, the SHACL Renderer now nests the + ex:W3C resource in the same form as the + ex:TimBL resource. +

+ + A diagram of the ex:TimBL as a form in a SHACL Renderer. + +
+ +
+

Summary and Next Steps

+

+ This section has shown that a data graph and a SHACL Renderer are + enough to produce a usable editable form. Adding a shapes graph, + including constraints that are also used in ordinary SHACL validation, + lets the SHACL Renderer use those semantics to produce more meaningful + forms. +

+ +

+ We have only briefly touched on cardinality constraints. Other useful + but more complex topics include logical constraints and using dynamic + SHACL to populate the values for the enum and autocomplete editors. + You can find these in the Patterns section. +

+
+
+ +
+

Rendering Concepts

+ +

+ Add conceptual model diagram on rendering concepts and how they relate + to each other as well as other concepts such as widgets. +

This section explains the UI concepts and how they work together.

@@ -1670,7 +2159,7 @@

Form Messages and Error Handling

-

Displaying Validation Results

+

Displaying Validation Results

This sub-section should address the "Mapping validation results to the form" mentioned in ISSUE 823.

From 52fb316dadefae51317c1894e31f8a2c2f1a1430 Mon Sep 17 00:00:00 2001 From: Edmond Chuc Date: Mon, 8 Jun 2026 14:51:30 +1000 Subject: [PATCH 02/18] Fix UI node expression concat, typos and links --- shacl12-ui/index.html | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/shacl12-ui/index.html b/shacl12-ui/index.html index 8305e76dd..e7466df30 100644 --- a/shacl12-ui/index.html +++ b/shacl12-ui/index.html @@ -660,7 +660,7 @@

Data Graph Only

ex:TimBL a schema:Person ; schema:honorificPrefix "Sir" ; - schema:givenName "Timothy" ; + schema:givenName "Tim" ; schema:additionalName "John" ; schema:familyName "Berners-Lee" ; schema:birthDate "1955-06-08"^^xsd:date ; @@ -889,7 +889,9 @@

Computed Resource Labels

sh:values [ sparql:concat ( [ shnex:pathValues schema:honorificPrefix ] + " " [ shnex:pathValues schema:givenName ] + " " [ shnex:pathValues schema:familyName ] ) ] ; @@ -944,7 +946,7 @@

Nested Resource Forms

ex:TimBL a schema:Person ; schema:honorificPrefix "Sir" ; - schema:givenName "Timothy" ; + schema:givenName "Tim" ; schema:additionalName "John" ; schema:familyName "Berners-Lee" ; schema:birthDate "1955-06-08"^^xsd:date ; @@ -981,14 +983,16 @@

Nested Resource Forms

>

- When rendering the form for the ex:TimBL resource, the - Scoring System would, by default, render the - schema:affiliation value using a + When rendering the form for the ex:TimBL resource, a + property shape for schema:affiliation can identify the + value as an IRI using sh:nodeKind sh:IRI. Without an + explicit details-editor preference, the Scoring System can then render + the value using a shui:IRIEditor, allowing the user to reference another resource without displaying its properties. However, it can be useful to show the ex:W3C resource - nested in the same view. To do this, we can configure the shape to - prefer the details editor for that property. + nested in the same view. To do this, we can configure the same + property shape to prefer the details editor.