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..af1cf187c --- /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 + + + + + + + + + + + +
+
+
+ 1955 / 08 / 06 +
+
+
+ + + 1955 / 08 / 06 + + + + + + + + + + + +
+
+
+ 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..cafed9998 --- /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 + + + + + + + + + + + +
+
+
+ + 1955 / 08 / 06 + +
+
+
+ + + 1955 / 08 / 06 + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + + + + + + 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..0cd468c6e --- /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 + + + + + + + + + + + +
+
+
+ + 1955 / 08 / 06 + +
+
+
+ + + 1955 / 08 / 06 + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + + + + + + 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..e807aaa35 --- /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 + + + + + + + + + + + +
+
+
+ + 1955 / 08 / 06 + +
+
+
+ + + 1955 / 08 / 06 + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + + + + + + + +
+
+
+ Affiliation +
+
+
+ + + Affiliation + + + + + + + + + + + + + + +
+
+
+ World Wide Web Consortium +
+
+
+ + + World Wide Web Consortium + + + + + + + + + + + +
+
+
+ Name +
+
+
+ + + Name + + + + + + + + + + + +
+
+
+ 1994 / 10 / 01 +
+
+
+ + + 1994 / 10 / 01 + + + + + + + + + + + +
+
+
+ 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..f0832a40b --- /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 + + + + + + + + + + + +
+
+
+ + 1955 / 08 / 06 + +
+
+
+ + + 1955 / 08 / 06 + + + + + + + + + + + +
+
+
+ + 📅 + +
+
+
+ + + 📅 + + + + + + + + + + + + + + + + + +
+
+
+ Affiliation +
+
+
+ + + Affiliation + + + + + + + + + + + +
+
+
+ + + 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..3d4a4dfc3 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,512 @@

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

+ +

+ One 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 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, selecting + shui:DatePickerEditor + for the birth date field and + shui:TextFieldEditor for + the remaining fields. +

+ +

+ Here is how the SHACL Renderer applies the SHACL UI concepts in this + editable form: +

+ +
    +
  • + 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 display the ISO 8601 lexical value + 1955-06-08 using localized date formatting. For + example, an application configured for Australian users may choose + to display the value as 08-06-1955. +
    • +
  • + 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 ex:TimBL as a form in a SHACL Renderer. +
+ +
+

Computed Resource Labels

+

+ The data graph for a person contains enough information to derive a + more meaningful label. Instead of rendering the resource as + Tim B L using local name resolution, the shapes graph + can define a node expression that computes an rdfs:label + value from properties of the schema:Person instance. + Label Resolution then uses that computed value as the resource's + label. +

+ + + +

+ Note that `schema:honorificPrefix` has no `sh:minCount`, so it is + optional. The `rdfs:label` node expression should therefore handle + missing values. For brevity, this example assumes that + `schema:honorificPrefix` is always present. +

+ +

+ 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 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 ex:TimBL as a form in a SHACL Renderer. + +

+ When rendering the form for the resource ex:TimBL, 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 same + property shape to prefer the details editor. +

+ + + +

+ 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 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 also used in ordinary SHACL validation, + allows the SHACL Renderer to 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.

@@ -1620,7 +2134,7 @@

Local Name Resolution

Patterns

Add common UI form patterns here, e.g., error handling and validation, conditional rendering, etc. For each section, clearly state whether it's normative or informative and describe its use case.

-

TODO: consider removing the explicit "patterns" section and move these topics under SHACL UI

+

TODO: consider removing the explicit "patterns" section and move these topics under Getting Started with SHACL UI

Root Shapes and Entry-Point Forms

@@ -1670,7 +2184,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.