Copyright © 2025-2026 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
This specification describes Shapes Constraint Language (SHACL) User Interfaces.
This specification is published by the Data Shapes Working Group.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C standards and drafts index.
This document was published by the Data Shapes Working Group as a Working Draft using the Recommendation track.
Publication as a Working Draft does not imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than a work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent that the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 18 August 2025 W3C Process Document.
This specification is part of the SHACL 1.2 family of specifications. See the SHACL 1.2 Overview for a more detailed introduction to them.
The specifications are as follows:
Working Drafts:
Editor's Drafts:
Implementers can partially check their level of conformance with the above specifications by testing themselves with the test cases each presents, linked to in their metadata. Note, however, that passing all the tests in a test suite does not imply complete conformance to the specifications, it only implies that the implementation conforms to the aspects tested by the test suite.
Content.
RDF applications commonly provide user interfaces that allow users to view and edit RDF resources. SHACL Core, together with vocabularies such as DASH, has often been used for this purpose by describing the structure, constraints, labels, and presentation-relevant metadata associated with RDF data.
SHACL User Interfaces are defined by this specification as a complementary vocabulary and rendering model for generating forms from SHACL shapes. It introduces UI-specific concepts and processing rules for determining widgets, resolving labels, and grouping and ordering the form components used to manage RDF resources.
Existing SHACL shapes and RDF data can be used to generate functional forms without additional SHACL UI annotations. SHACL UI annotations allow authors to provide more specific rendering information, enabling implementations to generate more tailored and consistent forms. The goal is to improve interoperability between SHACL-based form generation systems by defining common behavior across implementations.
This specification is intended for RDF application developers, RDF data editors, and authors of SHACL shapes who wish to generate forms for their data.
The scope of this specification is limited to form rendering for viewing and editing RDF resources using SHACL Core concepts such as shapes, constraints, and property paths. It defines processing behavior for label and language resolution, field grouping and ordering, and widget determination for value nodes.
This specification does not define the visual styling of the user interface, including the styling of individual widgets or the form as a whole.
Although it addresses some presentation-adjacent aspects, such as field grouping through sh:PropertyGroup and label handling, it defines how these are processed rather than how they are displayed.
This specification also does not define broader application-level user interface features such as search, filtering, or navigation. It does not define a protocol for updating data stores, nor does it define form submission handling, validation behavior, or error handling. Accessibility requirements for implementations and rendered interfaces are also out of scope, though implementations are encouraged to follow relevant accessibility guidelines.
Link to definitions and concepts from other docs, such as SHACL Core, RDF 1.2, etc.
Terminology used throughout this specification is taken from several sources:
The SHACL & RDF terms include: binding , blank node , conformance , constraint , constraint component , data graph , datatype , failure , focus node , RDF graph , ill-formed , IRI , literal , local name , member , node , node shape , object , parameter , pre-binding , predicate , property path , property shape , RDF term , SHACL instance , SHACL list , SHACL subclass , shape , shapes graph , solution , subject , target , triple , validation , validation report , validation result , validator , value , value node , global configuration .
sh:path, the latter of which is commonly used to label form elements.
The process includes label property resolution and language resolution, and considers labeling-related annotations from the
shapes graph, data graph, application environment, and user preferences, to determine the best label for UI presentation.
Within this specification, the following namespace prefix definitions are used:
| Prefix | Namespace |
|---|---|
foaf: |
http://xmlns.com/foaf/0.1/ |
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/ |
shuic: |
http://www.w3.org/ns/shacl-ui-community/ |
skos: |
http://www.w3.org/2004/02/skos/core# |
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/ |
Within this specification, the following JSON-LD context is used:
{
"@context": {
"foaf": "http://xmlns.com/foaf/0.1/",
"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/",
"shuic": "http://www.w3.org/ns/shacl-ui-community/",
"skos": "http://www.w3.org/2004/02/skos/core#",
"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/"
}
}
Note that the URI of the graph defining the SHACL vocabulary itself is
equivalent to the namespace above, i.e., it includes the
#. References to the SHACL vocabulary, e.g., via
owl:imports should include the #.
The Turtle serialization of the SHACL UI vocabulary contains the complete SHACL UI vocabulary.
Throughout the specification, color-coded boxes containing RDF graphs in Turtle and JSON-LD will appear. The color and title of a box indicate whether it is a Shapes graph, a Data graph, or something else. The Turtle specification fragments use the prefix bindings given above. The JSON-LD specification fragments use the context given above. Only the Turtle specifications will have parts highlighted.
Grey boxes such as this include syntax rules that apply to the shapes graph.
true denotes the RDF term
"true"^^xsd:boolean. false denotes the RDF
term "false"^^xsd:boolean.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
TODO: define conformance criteria for SHACL UI implementations.
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.
SHACL Renderers implementing this specification MUST support RDF 1.1 and SHOULD support RDF 1.2. When RDF 1.2 is supported, and unless stated otherwise in this document, implementations SHOULD prefer RDF 1.2 syntax and data model features over their RDF 1.1 counterparts.
When RDF 1.2 is supported, wherever this specification refers to rdf:langString, a SHACL Renderer also accepts an
rdf:dirLangString value in its place. This acceptance is a SHACL UI convenience that applies to widget selection and form
input only; it does not establish an RDF subtype relationship between the two datatypes, whose value spaces (and lexical spaces) are
disjoint. Validation via sh:datatype remains strict: the value a widget writes back MUST conform to the datatype declared
for the property, and a property shape that admits both datatypes for validation expresses this using a list of datatypes, for example
sh:datatype ( rdf:langString rdf:dirLangString ).
This section is non-normative.
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.
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.
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:
ex:TimBL is displayed as
Tim B L.
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.
xsd:string, so the Scoring System
has selected shui:TextFieldEditor as the most
suitable widget for them.
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.
This shapes graph contains a single node shape that targets the
schema:Person class. The node shape defines nested
property shapes with datatype constraints, cardinality constraints,
and display ordering hints using sh:order and
sh:group.
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, as defined in the related
Grouping, Ordering, and Layout
Hints pattern. 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.
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.
This shapes graph now contains a new property shape with a node
expression to compute the value for rdfs: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.
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.
The data graph describes Sir Tim Berners-Lee and the W3C using the schema.org vocabulary. Because the organization name is language-tagged, Language Resolution can select the most appropriate label for the user's locale.
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.
This shapes graph now contains a new property shape for
schema:affiliation with an IRI node kind constraint and
a preference for the
shui:DetailsEditor
widget.
With the new property shape, the SHACL Renderer now nests the
ex:W3C resource in the same form as the
ex:TimBL resource.
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.
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.
A SHACL Renderer is software that processes SHACL shapes and data and dynamically generates a user-interface using one or more node UI components. Implementations may add supplementary UI elements, such as a submit button to save changes, controls to toggle between edit and view modes, selectors for focus node and node shape, or visualizations of validation report messages. They may also provide:
TODO: review SHACL Renderer definition, particularly the manual and automatic mode, now that we have the scoring system defined.
SHACL UI may operate in different modes - such as search or query - to support various UI use cases. Each may require different inputs to the traditional form use case.
This section focuses specifically on the form mode.
At a minimum, a SHACL UI processor requires the following inputs:
In form mode, SHACL UI uses the focus node as the primary resource to render, and the node shape as the root definition, applying its own constraints - as well as any other connected shapes - to generate the form.
In some scenarios, an application may allow the user to choose which node shape to apply to a form. To support this, the system needs a function that determines which node shapes are valid for, or targets a given focus node, based on the data and shapes graphs. This process may occur before supplying the required inputs to the SHACL UI processor.
Another possible input combination is to provide a data graph, a shapes graph, and a focus node, and let the SHACL UI processor determine the most suitable root node shape to apply to the form. However, this approach might not be feasible in practice, as it introduces significant complexity and places additional burden on UI implementors.
What other input combinations should we consider?
A shapes graph may contain a SHACL instance of the class shui:Configuration
to define global configuration properties for rendering the UI.
sh:Graph is a SHACL subclass of shui:Configuration.
The following properties can be defined for a shui:Configuration instance.
| Property | Summary and Syntax Rules |
|---|---|
shui:defaultNamespace |
The default namespace used to construct fresh user-added nodes.
The value of shui:defaultNamespace is a Literal whose value is a valid IRI.
|
shui:languagePreference |
The language selection for displaying labels in widgets.
The value of shui:languagePreference is a well-formed SHACL list where all members are language tags.
The preferred language is determined according to the order of priority in the list from beginning (highest) to end (lowest).
An empty literal ("") represents no language, i.e., a string literal with no language tag.
|
shui:timeZone |
The time zone used to construct new terms with datatype xsd:dateTime.
The value of shui:timeZone is of datatype xsd:string and SHOULD be an IANA time-zone identifier.
|
shui:labelPreference |
The label properties used to determine the labels to display in widgets and labels to represent node values in the widgets.
The value of shui:labelPreference is a well-formed SHACL list where all members are SHACL Property Paths.
The preferred label property is determined according to the order of priority in the list from beginning (highest) to end (lowest).
|
shui:readOnlyGraph |
The graphs that contain read-only triples. The value of shui:readOnlyGraph is a well-formed SHACL list where all members are IRIs. Triples contained in a read-only graph cannot be edited, e.g. because they were inferred by a reasoner.
A SHACL Renderer MUST respect the read-only state of triples, indicate it accordingly in the user interface and thereby distinguish editable data from read-only data.
|
shui:defaultOrder |
The effective order assumed for property shapes and property groups that do not specify sh:order, as defined in Grouping, Ordering, and Layout Hints.
The value of shui:defaultOrder is of datatype xsd:decimal or xsd:integer, which are the datatypes that sh:order permits.
Where it is absent, a property shape or property group without sh:order has no effective order.
|
TODO: Describe the constraint collection/aggregation behaviour here for both Node and Property UI Component.
When generating user interfaces, it is often necessary to determine the most suitable user interface widget (e.g., a text input, a date picker, a checkbox) for a given value or SHACL constraint. To achieve this, SHACL UI defines a scoring system built on top of SHACL's validation process, providing a flexible and extensible mechanism that implementers and applications can use to determine which widgets are applicable.
Common use cases for the scoring system include:
xsd:date.sh:datatype constraint.
The scoring graph is populated with instances of shui:WidgetMatcher. A
shui:WidgetMatcher associates a widget (via shui:widget) with the
conditions under which it applies, expressed as SHACL shapes referenced through
shui:shapesGraphShape (validated against the shape node in the shapes graph)
and shui:dataGraphShape (validated against the focus node in the data graph).
An implementation MUST NOT select or offer a widget that it does not implement. When a widget that the implementation does not implement matches, or when no widget matches, the implementation MUST report this to the application. How these reports are handled or presented is left to the application. Two kinds of matcher are defined:
shui:WidgetScore — a matcher that additionally carries a
shui:score. When its shapes match, its widget is recorded with that score
by the score function.
shui:WidgetAcceptMatcher — a matcher used by the
accept function to decide whether a
widget is applicable at all. A widget without a shui:WidgetAcceptMatcher is
accepted unconditionally.
The score function is the entry point to the scoring system.
It combines both kinds of matcher: a widget is returned only if one of its shui:WidgetScore instances
matches and the widget is accepted according to its shui:WidgetAcceptMatcher instances.
A widget can also be attached to a shape directly, using shui:editor or shui:viewer. Such a widget
takes part in scoring like any other: the scoring graph is expected to contain a shui:WidgetScore
whose shui:shapesGraphShape matches shapes that declare the widget in this way.
Scoring graph preparation supplies such a
shui:WidgetScore for declared widgets that have none, so that a widget attached to a shape is never
silently ignored.
A shui:score is any xsd:integer or xsd:decimal. The score
function simply orders widgets by descending score. The absolute value of a score has no meaning of its own.
The built-in widgets nevertheless follow a small set of conventional bands, described below, so that the relative order of widgets is predictable. Third-party widget authors SHOULD reuse these bands so that their widgets interleave with the built-in ones as intended. A widget that should win over a built-in in some situation uses a score in the same band as, or a higher band than, that built-in.
Scores are compared globally across the whole scoring graph, not per widget. Two widgets whose
matching shui:WidgetScore instances carry the same score are ordered lexicographically by the Unicode code point
values of their shui:widget IRIs, as defined in the score function.
A band is therefore a shared frame of reference, not a guarantee of a unique position.
| Band | Meaning |
|---|---|
| 40 | The shape explicitly declares this widget with shui:editor or shui:viewer. This is also the default
value of shui:defaultWidgetScore used by scoring
graph preparation for a declared widget that has no shui:WidgetScore of its own, so a declared widget
always competes at the top of the ladder.
|
| 30 | Native match: the value's datatype or node kind is exactly what the widget is designed for and the widget
is the canonical choice for such values — for example an xsd:string value for a text field, an xsd:date
value for a date picker, or a blank node for the blank-node viewer.
|
| 20 | Strong but secondary match: a good fit for the value or shape that is not the single canonical widget for it — for example a text area for an arbitrary string, or a widget selected from the value's datatype where a more specific widget may also apply. |
| 10 | Shape-constraint match: the shape constrains the datatype or node kind (for example with sh:datatype or
sh:nodeKind) even though the value itself may be absent or not yet of that type.
|
| 1 | Last-resort fallback: the widget can technically present or edit the value but is rarely the best choice. It is offered so that some widget is always available. |
| 0 | Applicable but discouraged: the widget is included for completeness or manual override and should never be chosen as the default. |
The built-in widgets occasionally use an intermediate score, such as 5, to break a tie between two widgets that
would otherwise share a band. Such values are fine-tuning between the bands above and are not themselves bands.
To declare that a widget is not applicable under some condition, give the widget a
shui:WidgetAcceptMatcher whose shapes match the applicable case, rather than a shui:WidgetScore with a low or
negative score.
A widget can be attached to a shape directly, with shui:editor or shui:viewer, without the
scoring graph saying anything about that widget. Scoring graph preparation extends the
scoring graph with a shui:WidgetScore for each such widget, so that it participates in
the score function like any other widget.
A scoring graph MUST be prepared by this function before it is passed to the
score function. Without preparation, a widget that is only
attached to a shape with shui:editor or shui:viewer is never returned.
Inputs:
shui:WidgetMatcher definitions
(shui:WidgetScore and shui:WidgetAcceptMatcher).
Output:
shui:WidgetScore for each explicitly declared widget that has none.
Steps:
D be the value of the global configuration property shui:defaultWidgetScore.
If no such value is given, let D be 40, which is the score conventionally used by the
shui:WidgetScore instances of the built-in widgets that match an explicitly
declared widget.
P in shui:editor and shui:viewer
W of the property P of the shapes in the
shapes graph. These are the widgets that are explicitly declared on a shape. A value of
P at a node that is not a shape does not declare a widget and is ignored. A value of
P that is not an IRI is also ignored: a widget is identified by an IRI, and a non-IRI value
such as a blank node cannot be matched reliably with sh:hasValue across graphs.
W
shui:WidgetScore whose shui:widget
value is W, continue with the next W. The scoring graph
already defines how W is scored.
shui:WidgetScore to the prepared scoring graph with
the following:
W as shui:widget.D as shui:score.shui:shapesGraphShape, a sh:NodeShape with a single property shape whose sh:path is
P and whose sh:hasValue is W.
The scoring graph says nothing about ex:MyCustomEditor, so preparation adds the following
shui:WidgetScore, which matches exactly those shapes that declare that widget with
shui:editor:
The global configuration is defined by
PR #900, which is not merged yet.
Add shui:defaultWidgetScore to its property table once it is.
Scoring graph preparation depends only on the shapes graph and the scoring graph, not on a focus node or a shape node. It is therefore the same for every call of the score function over those two graphs, and implementations MAY perform it once and reuse the result. Applying it to an already prepared scoring graph makes no further changes.
A widget that the scoring graph already scores is left untouched, even when the existing
shui:WidgetScore instances do not cover the declared case. A scoring graph that scores a widget is expected to
also define how that widget is scored when a shape declares it, conventionally with a shui:WidgetScore whose
shui:shapesGraphShape tests the shui:editor or shui:viewer property.
The validation function used by the matcher function to validate the focus node against a list of shape nodes.
Inputs:
Steps:
true.false.
false.true.
If any SHACL validation fails due to malformed shapes, the validation function should log a warning and return false.
Shape validation errors should not cause the Matcher function to fail.
The matcher function used by the score function and the accept function to validate whether a widget score applies to a given focus node and shape node.
Inputs:
shui:WidgetMatcher definitions
(shui:WidgetScore and shui:WidgetAcceptMatcher).
shui:WidgetMatcher (for example a shui:WidgetScore or a shui:WidgetAcceptMatcher).
Steps:
shui:dataGraphShape property
is present, and no value for the shui:shapesGraphShape is present, return false.shui:shapesGraphShape property of matcher node as shape node.false, return false.true.shui:dataGraphShape property of matcher node as shape node.false, return false.true.
The score function determines which widgets should be used for a given combination of a focus node and a
shape node. It is the entry point to the scoring system: it returns the widgets whose
shui:WidgetScore matches and that are accepted according to their
shui:WidgetAcceptMatcher instances, ordered from best to worst match.
Inputs:
undefined.shui:WidgetMatcher definitions
(shui:WidgetScore and shui:WidgetAcceptMatcher). It MUST be a scoring graph that has been prepared
according to scoring graph preparation.
Output:
shui:score so that
the best match comes first. The sequence is empty if no widget matches and is accepted.
A widget result holds the shui:widget of a matching shui:WidgetScore,
the IRI of that shui:WidgetScore, and its shui:score.
Steps:
results.shui:WidgetScore in the scoring graph, sorted by shui:score
in descending order and then lexicographically by the Unicode codepoint values of shui:widget.S of type shui:WidgetScore, in that order
S as matcher node.false, continue with the next instance.shui:widget of S as widget node.false, continue with the next instance.R be the widget result with the following:
shui:widget of S.S.shui:score of S.R to results.results.
A caller that only needs the best matching widget takes the first result of the sequence.
The order of the results is fixed by the shui:score values and shui:widget IRIs alone,
which are known before any widget matcher is evaluated. The score function therefore does not need to evaluate
every widget matcher in order to produce its first result, and implementations MAY produce results
lazily — for example as an iterator or a generator — evaluating the matchers for each shui:WidgetScore
only when the caller requests the next result. Only the matchers up to and including the first accepted widget then
have to be evaluated: if the best scoring widget is rejected by its shui:WidgetAcceptMatcher, the next
best is evaluated, and so on. Because widget matchers are evaluated independently of one another, lazy and eager
evaluation produce the same sequence.
Several shui:WidgetScore instances may share the same shui:widget, in which case the accept
function is called more than once for that widget with the same inputs. The accept function is deterministic for a
given focus node and shape node, so implementations MAY evaluate it once per widget and reuse the result.
The sequence returned by the score function can be empty, for example when no value is present yet and the shape node declares no constraints from which a suitable widget can be derived. This mostly affects editing, since an existing value usually provides enough information to select a widget for viewing it. This specification deliberately does not define a fallback widget for this case. How a renderer handles it is left to the implementation, which may for instance take into account how familiar its intended users are with RDF.
The score function MUST raise an error and terminate the algorithm in the following scenarios:
The accept function used by the score function to check if a widget is applicable.
Inputs:
shui:WidgetMatcher definitions
(shui:WidgetScore and shui:WidgetAcceptMatcher).
Steps:
shui:WidgetAcceptMatcher instance M with a matching shui:widget value.M exists, return true.M as matcher node.The widget with the highest score SHOULD be selected as the default widget from the Scoring Algorithm results. Implementations MAY allow users to switch to any widget included in the results.
Since multiple score entries may reference the same widget, a post-processing step SHOULD be performed to normalize the score results (for example, by aggregating or de-duplicating entries by widget) before presenting the widget choices to the user.
Widget matchers are malformed if they fail to validate against the matcher validation shapes graph. That graph defines two shapes:
shui:ScoreShape targets shui:WidgetScore. A well-formed shui:WidgetScore has exactly one
shui:widget (an IRI), exactly one shui:score (an xsd:decimal or xsd:integer), and any
shui:dataGraphShape or shui:shapesGraphShape it declares references a valid node.
shui:AcceptMatcherShape targets shui:WidgetAcceptMatcher. A well-formed
shui:WidgetAcceptMatcher has exactly one shui:widget (an IRI), no shui:score, and any
shui:dataGraphShape or shui:shapesGraphShape it declares references a valid node.
TODO: consider moving this section under "SHACL UI Concepts".
The following sub-sections enumerate the currently defined instances of shui:Editor from the SHACL UI namespace.
Property shapes can explicitly specify the preferred editor for its values using shui:editor.
If no such value has been specified, the system should pick a suitable default viewer based on the
scoring system outlined for each widget.
The following sub-sections enumerate the currently defined instances of shui:Viewer from the SHACL UI namespace.
A property shape can have an explicitly specified preferred viewer for its values in shui:viewer.
If no such value has been specified, the system should pick a suitable default viewer based on the
scoring system outlined for each widget.
Most viewers render a single RDF value on the screen, typically as a single widget.
Form editors offer buttons to edit individual values and to add or delete values.
However, some viewers need to take more complete control over how multiple values of a property at a focus node are rendered.
The only example of such a viewer in SHACL UI is shui:ValueTableViewer, which displays
all values of a property as an HTML table.
In such cases, the notions of generic add and delete buttons do not apply.
Such viewers are called Multi Viewers and are declared instances of shui:MultiViewer instead of shui:SingleViewer.
The equivalent classes for editors are shui:MultiEditor and shui:SingleEditor.
TODO: This section may not be needed if we decide to fold in the use of different constraints for common form scenarios under the Patterns section.
SHACL Property Paths can be used to render a SHACL shape as a user interface. Property paths define how data values are accessed or modified relative to a focus node.
The following subsections outline the scenarios in which SHACL UI implementations are expected to support different kinds of property paths for viewing and editing operations.
In view mode, property paths are used to retrieve and display data values associated with a shape. A SHACL UI implementation must provide mechanisms to resolve these paths for visualization.
SHACL UI implementations MUST support both predicate paths and inverse paths in view mode. This ensures that values reachable via simple forward or inverse relationships can be displayed to the user.
The following example illustrates how predicate and inverse paths are used in view mode to access and display values, either directly from the focus node or through incoming relationships from other nodes.
A SHACL UI could display the person’s foaf:name as text and list departments that
reference the person via ex:member.
SHACL UI implementations SHOULD support other complex property paths besides inverse paths in view mode as well. These complex paths include sequence paths, alternative paths, zero-or-more paths, one-or-more paths, and zero-or-one paths as defined in SHACL Core.
Support for these complex paths is recommended, but optional, and can be left out in cases where the implementation aims to provide symmetry between view and edit modes, and such paths are not supported in edit mode.
The following examples illustrate a sequence path and an alternative path, both of which may be used for richer data traversal in view mode.
A SHACL UI could display Alice’s city as "Ghent" by traversing the ex:address node,
and display the title of ex:book1 as “Linked Data Design”.
In edit mode, property paths determine how changes to data and the creation of new data are applied through the user interface.
SHACL UI implementations MUST support predicate paths and inverse paths in edit mode. This allows users to modify data linked by simple properties or inverse properties.
The following example illustrates how predicate and inverse paths can be used in edit mode to modify a person’s name and manage their membership in departments.
A SHACL UI might render a text input for foaf:name and a selector for the
departments.
Editing inverse paths requires the UI to ensure consistent updates on the related nodes.
SHACL UI implementations SHOULD support alternative paths in edit mode. This enables editing where a shape can constrain multiple potential properties, and the UI can allow users to choose which alternative to use when entering or modifying data.
When editing existing or newly created statements, the UI SHOULD provide a mechanism to update the
predicate to one of the enumerated paths in the sh:alternativePath list, but only if
those paths are either predicate paths or inverse paths. This restriction is necessary
because the object of sh:alternativePath is a SHACL list that may contain any valid
property path expression, including complex path types that are not generally feasible to edit
directly through a user interface.
Although redundant, SHACL permits nesting of sh:alternativePath expressions.
Such nesting simply flattens to a single list of predicate or inverse paths and does not alter the
effective set of alternatives available for editing.
The following example illustrates how an alternative path can be used in edit mode to allow a book's
title to be provided through either dct:title or rdfs:label.
A SHACL UI could show the existing title “Semantic Web Foundations” and allow the user to choose
whether
to edit it via dct:title or rdfs:label.
SHACL UI implementations MAY support the other complex paths (i.e., sequence paths, zero-or-more paths, one-or-more paths, and zero-or-one paths) in edit mode.
Implementers are encouraged to support these when their use cases require advanced data navigation or editing patterns, but such support is not mandatory as the complexity of editing through these paths may not be feasible in all user interface contexts.
Supporting complex property paths in edit mode introduces challenges related to ambiguity and the generation of intermediate data structures. Even when a path is used for view-only purposes, implementations must ensure that restrictions are in place to prevent ambiguous traversal results. SHACL property paths allow navigation across multiple steps in a graph, which can lead to situations where a single value is reachable through multiple distinct paths.
The following shape and data graph illustrate how a node can be reachable via a complex path expression, making editing operations ambiguous.
In this example, the node ex:screw can be reached from
ex:compounded-thing through two distinct paths:
ex:compounded-thing → ex:hasPart → ex:part-a → ex:hasPart → ex:screwex:compounded-thing → ex:hasPart → ex:part-b → ex:hasPart → ex:screwThis illustrates why editing along complex property paths is non-trivial: it can be unclear which intermediate nodes or triples correspond to a user’s intended modification.
UI literals — such as labels, descriptions, and other human-readable strings required for rendering a user interface — are selected based on language tags. This section defines how an application determines which language to use when multiple language-tagged literals are available for a given property.
When selecting a UI literal, the preferred language is determined according to the following order of priority. Each option itself provides an ordered list of languages where earlier entries are preferred over later ones:
shui:languagePreference.Accept-Language HTTP header or the navigator.languages Web API. These SHOULD be
used as the default values when no application-level language preference has been configured.
Language tags are matched according to the basic filtering scheme defined in [RFC4647] section 3.3.1.
In particular, a language tag such as en-US SHOULD be considered a match for a preferred
language of en.
If no literal matching the preferred language is available, implementations MAY fall back to a literal in another available language (or without a declared language) or apply the label resolution fallback strategy as defined for the relevant context.
Label resolution determines the most appropriate human-readable string to display for an RDF resource in a user interface. This section defines the algorithm for determining that label, considering annotations in the shapes graph, values in the data graph, and fallback strategies when no suitable label is found.
Label resolution is applied in two contexts:
sh:path.
Label property resolution (i.e., determining the label properties for retrieving label values) is done according to the preferred property IRIs listed in the global configuration property shui:labelPreference.
Preferred labels default to sh:name for Property Labels and rdfs:label for Value Node Labels.
To determine the label for a property UI component whose property shape has
a sh:path pointing to a property path P, implementations MUST
apply the following steps in order, stopping at the first step that yields a result:
To determine the label for a single value node V, implementations MUST apply the following steps in order, stopping at the first step that yields a result:
sh:path is annotated with
shui:propertyRole shui:LabelRole, retrieve the values of that path from
the data graph for subject V. Select the best matching value using
language resolution.
If a match is found, use that literal as the label.
To determine the label for an IRI, the local name L of the IRI SHOULD be used; this process is called local name resolution. Implementations SHOULD transform the local name into a human-friendly form, for example, by splitting camel case identifiers into words.
When rendering with a German language preference, the foaf:firstName field
label is resolved to "Vorname"@de from sh:name. The label
for the value node ex:acme is resolved to "ACME GmbH"@de
from rdfs:label in the data graph.
Since the property shape for dct:creator has no sh:name and
no rdfs:label is available for the dct:creator predicate,
the label falls back to the local name "creator", which a renderer might
display as "Creator" after capitalizing the first letter. The value node
ex:author1 has no rdfs:label in the data graph, so its label
falls back to the local name "author1". A renderer might further transform
this by splitting on the digit boundary and capitalizing, yielding "Author 1".
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 Getting Started with SHACL UI
TODO: Add a pattern describing how applications choose the initial node shape and focus node for rendering. This pattern should explain that applications may nominate one or more root node shapes for entry-point forms.
Add a pattern for conditional or dynamic sub-forms. Consider how the following constraints would work here. sh:class, sh:node, sh:or, sh:qualifiedValueShape.
Add a pattern for select widgets. This should cover common sources for option lists: sh:in, class-based instance selection, SKOS concepts, node expressions, and implementation-provided query services. It should distinguish static enumerations from dynamic lookups. Some of the UI meetings have discussed using node expressions, dynamic SHACL, and SPARQL with the SERVICE clause.
Static enumerations based on sh:in are rendered by the EnumSelectEditor,
while dynamic lookups of class instances are rendered by the AutoCompleteEditor.
Non-constraining suggestions can be provided with shui:suggestedValues.
This proposal allows someone to have federated references in their dataset and select/view those in a rich user interface.
Given that:
sh:inWe have:
ex:propertyCity
sh:path ex:city ;
sh:in [
sh:select """
select ?city where {
SERVICE <http://example.org/sparql> {
?city a ex:City .
}
}
""" ;
] . Notice:
A mechanism to fetch labels and possibly other properties of a resource.
ex:propertyCity
sh:path ex:city ;
sh:in ( ex:Amsterdam ex:Rotterdam ex:NewYork ) ;
shui:displayProvider ex:myDisplay ;
].
ex:myDisplay
a shui:DisplayProvider ;
sh:select """
select $value $label $depiction $description where {
$value rdfs:label $label .
optional { $value schema:depiction $depiction }
optional { $value schema:description $description }
}
""" .$value will be pre-bound with the value node of which the SHACL renderer needs to render a labelshui:EnumSelectEditor and the shui:AutocompleteEditor and other places where it might apply.shui:displayProvider is given the SHACL renderer may fall back to it's own label resolution algorithm.A mechanism to filter resources with a search term.
ex:propertyCity
sh:path ex:city ;
sh:in ( ex:Amsterdam ex:Rotterdam ex:NewYork ) ;
shui:resourceFilter ex:myFilter ;
].
ex:myFilter
a shui:ResourceFilter ;
sh:select """
select $value where {
$value rdfs:label ?label .
filter(contains(?label, $searchTerm))
}
""" .$value will be pre-bound with the value node of which the SHACL renderer needs to if it should be shown.$searchTerm will be bound with the search term the user is entering.shui:AutocompleteEditor and other places where it might apply.shui:resourceFilter is given the SHACL renderer may fall back to it's own resource filter. Which in turn can use the display provider if defined or the fallback label resolution algorithm.ex:propertyCity
sh:path ex:city ;
shui:displayProvider ex:myDisplay ;
shui:resourceFilter ex:myFilter ;
sh:in [
sh:select """
select ?city where {
SERVICE <http://example.org/sparql> {
?city a ex:City .
}
}
""" ;
] .
ex:myFilter
a shui:ResourceFilter ;
sh:select """
select $value where {
SERVICE <http://example.org/sparql> {
$value rdfs:label ?label .
$value ex:synonym ?synonym .
$value rdfs:comment ?description .
bind (concat(
?label, " ",
?synonym, " ",
?description
) as ?allText)
filter(contains(?allText, $searchTerm))
}
}
""" .
ex:myDisplay
a shui:DisplayProvider ;
sh:select """
select $value $label $depiction $description where {
SERVICE <http://example.org/sparql> {
$value rdfs:label $label .
FILTER(lang($label) = "en")
optional { $value schema:depiction $depiction }
optional { $value schema:description $description }
}
}
""" .bif:contains the end user could use that mechanism inside the shui:ResourceFilter select query.Currently, DASH forms provide ways to populate widgets such as the AutoCompleteEditor and ValueTableViewer by declaring shapes and constraints to describe the shape of the data. This works well, and SHACL UI should adopt this. However, this approach assumes all data resides in the data graph when in practice, most datasets are compartmentalised into named graphs for data management purposes. We could build on the work established in DASH forms by adding support for targeting named graphs when populating data for widgets.
SHACL UI could also enable data updates across multiple named graphs through a single form. Without named graph support in SHACL Core, however, this would be difficult to implement and may feel inconsistent. That said, widget-level named graph support could still function effectively. Because data retrieval for widgets is read-only (fetching data to populate them), any updates involving widget data would continue to be written only to the data graph.
Example: When a user is updating an address form, the drop-down list of Australian states and territories (code list) could be retrieved from a named graph separate from the main data graph. Selecting a state or territory from the drop-down would then write the chosen value to the data graph.
Is this a sensible proposal to support named graphs for widgets? And should we explore further on the idea of data updates working across multiple named graphs?
Related:
This section is normative, except for the part explicitly marked as non-normative below.
SHACL Renderers MUST determine the presentation order of property shapes and
property groups using the value of sh:order. At each level of rendering,
property groups and ungrouped property shapes MUST be treated as members of a single
ordered sequence. A property shape that specifies sh:group is not a member
of that sequence; it is rendered inside the referenced property group, where its
sh:order determines its position relative to the other members of that group.
A property group may specify a value for shui:parentGroup to indicate that it is
nested inside another property group. A property group MUST have at most one value for
shui:parentGroup, and that value MUST be a sh:PropertyGroup.
A renderer that supports nested property groups MUST render a nested property group inside its parent property group and
not as a member of any other sequence. Within the parent group, the nested property groups
and the property shapes of that group are treated as members
of a single ordered sequence. The same ordering rules MUST be applied recursively at each
level of nesting. A renderer that does not support nested property groups MUST ignore
shui:parentGroup, so that each property shape is rendered
in the property group it specifies, and property groups that contain no
property shapes directly are not rendered. If the chain of
shui:parentGroup values of a property group leads back to itself, renderers
MUST ignore the shui:parentGroup values of all property groups in that cycle.
Renderers SHOULD expose the structure of nested property groups in their output, for example by rendering each property group as a distinct element that can be identified by the IRI of the property group, or by another stable identifier if it is a blank node, so that the layout of a form or view can be controlled with technologies such as CSS.
A renderer renders the group "Personal details" containing first the nested group "Name",
with the fields for ex:firstName and ex:lastName, followed by the
field for ex:birthDate. Using CSS, the nested group "Name" could for example
be laid out horizontally so that the first and last name appear side by side.
The effective order of a property shape or
property group is the value of its sh:order. Where sh:order is not
specified, the effective order is the value of shui:defaultOrder in the
global configuration, if present. Otherwise, the property shape or property group has
no effective order.
Renderers MUST order the members of an ordered sequence by the ascending numeric value of their effective order. Members that have no effective order SHOULD be placed after all members that have one.
The global configuration property shui:defaultOrder declares the
effective order assumed for property shapes and property groups that do not
specify sh:order. Its value is a literal with datatype
xsd:decimal or xsd:integer, which are the datatypes that
sh:order permits.
Renderers SHOULD apply a deterministic tie-breaking algorithm whenever two or more members of an ordered sequence have the same effective order, or whenever two or more members have no effective order. Renderers SHOULD apply the following tie-breaking algorithm:
sh:order is defined, that is, its IRI or blank
node identifier.
Renderers MAY use an alternative tie-breaking algorithm.
The remainder of this section is non-normative.
Deterministic interoperability is guaranteed only when all property groups and property
shapes participating in an ordered sequence explicitly specify sh:order, or
when the shapes graph declares shui:defaultOrder.
Presenting property shapes and property groups without sh:order last reflects
the behaviour of existing renderers, which append properties that carry no ordering hint to
the end of the form. Shape authors who prefer a numeric default can declare one explicitly
with shui:defaultOrder. Setting shui:defaultOrder 0, for example,
allows authors to assign negative sh:order values to elements that should
always be rendered before otherwise unordered elements, while positive values can be used to
position elements after them. Because the global configuration is part of the
shapes graph, this choice travels with the shapes, so interoperability across
implementations is preserved.
The following example illustrates the interpretation of a missing sh:order
value.
No shui:defaultOrder is declared, so ex:name has no effective
order and is rendered last. The properties are rendered in the order
ex:identifier (effective order -10), ex:description (effective
order 5), and ex:name.
Adding this global configuration to the previous shapes graph gives
ex:name an effective order of 0, so the properties are rendered in the order
ex:identifier, ex:name, ex:description. This
demonstrates that assigning a negative sh:order value allows a property to be
rendered before properties that rely on the declared default.
In the SHACL 1.0 spec we have the chapter "2.3.2 Non-Validating Property Shape Characteristics" which contains sh:order and sh:group. I wonder if it would make sense to move these two to the shui namespace and deprecate them. Meanwhile we should recommend or require implementers of a spec compliant SHACL renderer to still support sh:order and sh:group. However going forward shui:order and shui:group would be the standard way to go.
Pro's
Cons
We need to think of who used these predicates and how they have been used.
Are there uses of sh:order and sh:group besides UI work?
Are they both used only in UI or is sh:group easier to move?
The section should explain that a single shapes graph may contain shapes used for different purposes, and implementations may need to distinguish validation shapes and UI rendering shapes.
We may need a more broader set of patterns documented for creating, updating, and deleting data via SHACL UI.
In our platform we have a property xy:defaultNS which stores the suggested default namespace for new resources in a given graph. It is attached to the home resource of the named graph (often an owl:Ontology). It is used whenever the user creates new instances which typically starts with entering the display label, from which the system will derive a suitable URI consisting of the label as local name, and the default namespace.
It would be great if such a property shui:defaultNamespace (datatype xsd:anyURI) could be added.
The pattern should describe how renderers may handle and display form errors, including validation errors and submission errors.
The task force discussed this topic and agreed that the SHACL UI document would benefit from a dedicated guidance section on form error handling for SHACL constraint violations, specifically on how implementations might map SHACL validation reports back to form fields.
This section should cover both client-side and server-side form validation, weighing the trade-offs of each approach. For instance, not all shapes are suitable for client-side validation: those containing SPARQL-based constraints require access to the full dataset, rather than the subset rendered in the form. For server-side validation, when either the data graph or the shapes graph contains blank nodes, implementations must use skolemisation whenever data crosses document boundaries, so that constraint violations in the validation report can be reliably traced back to the originating form field.
Below are some of the areas we intend to explore for the section:
SHACL UI should support a way to display alerts and messages in the form. These messages can be both positive and negative and potentially sourced via the validation report and provide a vocabulary to customise icons, styling, and colour of the message.
Discussion:
This sub-section should address the "Mapping validation results to the form" mentioned in ISSUE 823.
The pattern should describe how renderers may associate sh:ValidationResult entries with property UI components or node UI components,
using sh:focusNode, sh:resultPath, sh:value, sh:sourceShape, sh:resultSeverity, and sh:resultMessage. It should avoid defining when validation
runs or how an applications prevents malformed submissions.
This section defines shui:searchQuery, an optional property of a property shape
that lets shape authors provide a dedicated SPARQL SELECT query for retrieving candidate
value nodes from live, user-provided search input, for example within an
AutoCompleteEditor.
A well-formed value of shui:searchQuery is a literal of datatype
xsd:string, appearing directly on a property shape, and containing a SPARQL
SELECT query conforming to the constraints below. A property shape has at most
one value for shui:searchQuery.
When an end user enters or changes search input for a property rendered with a widget that consumes
candidate value nodes, a SHACL Renderer that supports shui:searchQuery MUST evaluate the query given by
shui:searchQuery to retrieve the candidate value nodes offered to the user, except where a
fallback to sh:in is permitted as described below.
Prior to evaluating shui:searchQuery, a SHACL Renderer MUST substitute
each occurrence of the following variables in the query string with a SPARQL
string literal holding the variable's value, escaped
according to the SPARQL grammar so that the value cannot alter the structure of the query.
Substitution, rather than pre-binding, is used so that the values also reach query patterns
that are evaluated elsewhere, such as inside a SERVICE clause.
| Variable | Description |
|---|---|
$searchTerm |
An xsd:string literal containing the current search input entered by the end user. |
$language |
An xsd:string literal containing the BCP47 language tag identifying the user's current
language preference, as determined by the language resolution mechanism.
Only the first entry of the language preference list is considered. If the language preference list is
empty, the value is the empty string "".
|
Implementations MAY substitute additional implementation-specific variables in the same way. Queries MAY also provide additional projected bindings.
Using the prefix handling rules, the SPARQL query derived
from the value of shui:searchQuery MUST project at least one variable in its SELECT
clause. A SHACL Renderer depends on the first variable of the SELECT clause's projection,
which represents the matching IRIs or literals for each candidate value node. The query MAY include a
LIMIT or OFFSET
solution modifier; if present, the renderer MAY use it to limit the number of candidate value nodes
returned to the user.
A property shape with a shui:searchQuery signals that a live search widget is
appropriate for that property, even without an explicit shui:editor statement. Accordingly, the
presence of shui:searchQuery raises the AutoCompleteEditor's
score, as described in its Score rules.
This specification does not define how property roles, such as
shui:LabelRole, are resolved or auto-injected into the search query. Renderers MAY combine
value filtering and label retrieval in a single query, using the additional bindings beyond the first
described above, or retrieve them via different mechanisms.
As the user types into the AutoCompleteEditor rendered for
ex:TaskShape's Assignee property, the renderer substitutes the typed text for
$searchTerm and the current language for $language, then evaluates
shui:searchQuery to query a local full-text index of ex:Person instances
by their rdfs:label, keeping only persons that have a label in the user's language.
A property shape's permissible value nodes can also be computed dynamically using a
select expression (sh:select) inside
sh:in, possibly including a SPARQL SERVICE clause against an external endpoint, as
described in Dynamic SHACL. Such a
select expression resolves the
full candidate set and cannot be parameterized with a user's live search input. A
shui:searchQuery, by contrast, receives the search input and can use vendor-specific full-text
search extensions to match it.
When a property shape combines sh:in with shui:searchQuery, a SHACL Renderer
that supports shui:searchQuery evaluates shui:searchQuery instead of the
sh:in select expression while the user is searching.
Before the user has entered any search input, the renderer MAY offer the candidates given by
sh:in instead of evaluating shui:searchQuery with an empty $searchTerm.
The renderer MAY also fall back to the sh:in select expression when evaluation of
shui:searchQuery fails. A renderer that does not support shui:searchQuery but does
support Dynamic SHACL uses the sh:in select expression as usual.
As the user types into the AutoCompleteEditor rendered for
ex:BookShape's Author property, the renderer substitutes the typed text for
$searchTerm and the current language for $language, then evaluates
shui:searchQuery to query the Apache Jena Text index via the SERVICE clause.
If the renderer does not support shui:searchQuery but does support Dynamic SHACL,
the baseline sh:select query is used instead, returning all instances of ex:Person.
Shape authors SHOULD write shui:searchQuery so that its result set, for any given
$searchTerm, is a subset of the value nodes permitted by the constraints on the
property shape. A shui:searchQuery that returns value nodes outside that set risks
offering end users candidate values that do not conform to the property shape.
A SHACL Renderer MAY validate the value nodes returned by shui:searchQuery against the
constraints of the property shape before offering them to the end user, for example using one of the
approaches described below. Value nodes that pass validation are offered as candidates; value nodes that
fail it MUST NOT be offered. If no validation is performed, or it cannot be completed, all returned value
nodes are offered. A value node selected by the end user
becomes a value of the property and is subject to the same validation as any other value, so any
non-conformance is reported through the regular validation results.
When shui:searchQuery retrieves value nodes from a remote endpoint, for example through a
SERVICE clause, the triples about those value nodes are often not in the local
data graph. Constraints that depend on such triples, such as sh:class, can then report
violations for value nodes that are in fact permitted. In that case, shape authors SHOULD express the
permitted value nodes using sh:in with a
select expression that queries the same endpoint, as in
the federated example above, instead of such constraints. A SHACL Renderer can then validate the returned
value nodes by evaluating that select expression with an added VALUES clause that restricts
its projected variable to those value nodes, together with the constraints that do not depend on remote
triples, such as sh:nodeKind or sh:pattern. Otherwise, the renderer can validate
the returned value nodes directly against the constraints of the property shape.
This section defines shui:suggestedValues, an optional property of a property shape
that lets shape authors provide suggested values to be offered to the end user by a widget.
Suggested values help users fill in common or recommended values quickly, without restricting
the set of values that may be entered.
A well-formed value of shui:suggestedValues is a SHACL list, appearing directly on a
property shape, whose members are IRIs or literals. Each member represents one
suggested value. A property shape has at most one value for shui:suggestedValues.
SHACL Renderers SHOULD ignore ill-formed values of shui:suggestedValues and list members that
are neither IRIs nor literals.
Support for shui:suggestedValues is optional. When rendering a widget for a property whose
property shape has a value for shui:suggestedValues, a SHACL Renderer SHOULD offer the
members of the list to the end user as suggestions. A renderer that offers suggestions SHOULD present them
in the order of the list. A suggestion does not constrain the values that may be entered:
shui:suggestedValues has no effect on validation, and the end user remains free to enter
values that are not among the suggestions.
When displaying a suggested value that is an IRI, a SHACL Renderer SHOULD display a label determined by Label Resolution rather than the IRI itself. When the suggested values include language-tagged literals, a SHACL Renderer SHOULD use Language Resolution to determine which of them to offer.
Shape authors SHOULD choose suggested values that are a subset of the value nodes permitted by the other
constraints on the property shape (such as sh:class, sh:datatype, or
sh:in). A suggested value outside that set risks offering end users values that do not
conform to the property shape. A suggestion does not relax any constraint of the
property shape. When an end user selects a suggested value that does not conform, it leads to the
same validation results as any other value that does not conform. A SHACL Renderer MAY leave out
suggestions that it knows would violate the constraints of the property shape, for example because
sh:maxCount has already been reached.
Suggested values can be used with any widget that lets end users choose or enter values. For example, an AutoCompleteEditor could list the suggested values before the end user has entered any search input, and a text field editor could offer them as quick choices. These widgets are only examples; this specification does not limit which widgets may use suggested values.
A renderer that supports shui:suggestedValues could offer ex:Netherlands,
ex:Belgium, and ex:Germany, in that order, as quick choices for the nationality of a person,
while still allowing the end user to search for and select any other instance of ex:Country.
This section enumerates the built-in widgets defined in the SHACL UI namespace. Additional widgets may be defined by the community; see Registries.
The following subsections enumerate the currently built-in instances of shui:Editor from the
SHACL UI namespace.
40 if the property indicates its preference for shui:AutoCompleteEditor using a shui:editor statement and has a sh:class constraint, and the value is an IRI.20 if the property has shui:searchQuery.10 if the property has a sh:nodeKind sh:IRI and a sh:class constraint.
Rendering:
An auto-complete field to enter the label of instances of the class specified for the property.
For example, if the sh:class of the property is ex:Country and the user starts
typing "Nig", then "Niger" and "Nigeria" would show up as possible choices.
ex:Person-bornIn
a sh:PropertyShape ;
sh:path ex:bornIn ;
sh:class ex:Country ;
...
Implementations may want to also support the combination of sh:class with sh:node
constraints to further narrow the set of valid values.
In this case, the component would filter out any instances of the class that do not conform to the specified node shape.
In the following example, the auto-complete would only show countries that have true as their value
for ex:sovereign.
ex:Person-bornIn
a sh:PropertyShape ;
sh:path ex:bornIn ;
sh:class ex:Country ;
sh:node [
sh:property [
sh:path ex:sovereign ;
sh:hasValue true ;
]
] ; ...
40 if the property indicates its preference for shui:BlankNodeEditor using a shui:editor statement, and the value is a blank node.1 if the value is a blank node.Rendering: A read-only editor that displays the blank node, similar to shui:BlankNodeViewer, yet allows the surrounding user interface to at least provide a delete button.
40 if the property indicates its preference for shui:BooleanEditor using a shui:editor
statement, and the value is an xsd:boolean literal.
20 if the value is an xsd:boolean literal.10 if the property has a sh:datatype xsd:boolean constraint.Rendering: A widget for editing boolean values, typically rendered as a checkbox, toggle switch, or select dropdown offering true and false, and, where the property is optional, optionally an additional control state representing the absence of a value.
The exact rendering of the BooleanEditor may vary between implementations depending on the complexity and
requirements of the use case. In particular, implementations should carefully distinguish between optional
and required boolean properties: for optional properties, the absence of a value is semantically different
from the value false, and an implementation may therefore render a select dropdown with three choices
(e.g., true, false, and none) where none represents no value; for required properties, where a value
must always be present, a checkbox or toggle switch may be appropriate. Implementations may choose the most
suitable rendering approach, provided this semantic distinction is preserved.
ex:Person-married
a sh:PropertyShape ;
sh:path ex:married ;
sh:datatype xsd:boolean ;
...
40 if the property indicates its preference for shui:DatePickerEditor using a shui:editor statement, and the value is an xsd:date literal.20 if the value is an xsd:date literal.10 if the property has a sh:datatype xsd:date constraint.Rendering: A calendar-like date picker.
ex:Person-dateOfBirth
a sh:PropertyShape ;
sh:path ex:dateOfBirth ;
sh:datatype xsd:date ;
...
40 if the property indicates its preference for shui:DateTimePickerEditor using a shui:editor statement, and the value is an xsd:dateTime literal.20 for xsd:dateTime literals.10 if the property has a sh:datatype xsd:dateTime constraint.Rendering: A calendar-like date picker including a time selector.
ex:Customer-lastVisitTime
a sh:PropertyShape ;
sh:path ex:lastVisitTime ;
sh:datatype xsd:dateTime ;
...
40 if the property indicates its preference for shui:DetailsEditor using a shui:editor statement, and the value is an IRI or a blank node.0 if the value is an IRI or a blank node.
Rendering:
Typically rendered as a nested form that allows editing the properties of the value node inline within the surrounding form.
The fields of the nested form are determined by the shape that applies to the value node.
This shape may be specified explicitly (e.g., via sh:node or other mechanisms that associate a shape with the value),
or implicitly via constraints such as sh:class.
Alternatively, nested fields may be defined directly on the surrounding property shape using sh:property.
When rendered as a nested form, the implementation recursively evaluates the applicable shape of the value node and renders its declared property shapes as sub-fields. Implementations may alternatively render the details in a separate dialog or dedicated view, provided that the editing semantics remain equivalent.
This editor is particularly useful for blank nodes or tightly coupled resources that are typically created and edited only in the context of their parent resource. However, it may also be used for IRIs referencing other resources.
ex:Product
a owl:Class ;
a sh:NodeShape ;
rdfs:label "Product" ;
rdfs:subClassOf owl:Thing ;
sh:property ex:Product-weight .
ex:Product-weight
a sh:PropertyShape ;
sh:path ex:weight ;
shui:editor shui:DetailsEditor ;
shui:viewer shui:DetailsViewer ;
sh:description "A blank node with a numeric field and a unit which is one of the QUDT mass units." ;
sh:maxCount 1 ;
sh:name "weight" ;
sh:node ex:ValueWithWeight ;
sh:nodeKind sh:BlankNode .
ex:ValueWithWeight
a sh:NodeShape ;
rdfs:label "Value with weight" ;
sh:property ex:ValueWithWeight-numericValue ;
sh:property ex:ValueWithWeight-unit .
ex:ValueWithWeight-numericValue
a sh:PropertyShape ;
sh:path ex:numericValue ;
sh:datatype xsd:decimal ;
sh:maxCount 1 ;
sh:minCount 1 ;
sh:name "numeric value" .
ex:ValueWithWeight-unit
a sh:PropertyShape ;
sh:path ex:unit ;
sh:class <http://qudt.org/schema/qudt/Unit> ;
sh:maxCount 1 ;
sh:minCount 1 ;
sh:name "unit" ;
sh:node [
rdfs:label "Permissible values must have quantity kind Mass." ;
sh:property [
sh:path <http://qudt.org/schema/qudt/hasQuantityKind> ;
sh:hasValue <http://qudt.org/vocab/quantitykind/Mass> ;
] ;
] .
This widget requires that the surrounding property (ex:weight, above) declares sh:nodeKind sh:BlankNode
and also has a sh:node constraint that points at a node shape that declares the properties that shall be editable.
40 if the property indicates its preference for shui:EnumSelectEditor using a shui:editor statement and has a sh:in constraint.30 if the property has a sh:in constraint.
Rendering:
A drop-down editor for enum fields (based on the sh:in list, in that order).
ex:AustralianAddressShape-addressRegion
a sh:PropertyShape ;
sh:path schema:addressRegion ;
sh:in ( "ACT" "NSW" "NT" "QLD" "SA" "TAS" "VIC" "WA" ) ;
...
40 if the property indicates its preference for shui:InstancesSelectEditor using a shui:editor statement and has a sh:class constraint, and the value is an IRI.0 if the property has a sh:class constraint.
Rendering:
A drop-down editor for all instances of the target class (based on sh:class of the property).
Typically only used for classes that have few instances.
ex:Person-homeCountry
a sh:PropertyShape ;
sh:path ex:homeCountry ;
sh:class ex:Country ;
shui:editor shui:InstancesSelectEditor ;
...
40 if the property indicates its preference for shui:IRIEditor using a shui:editor statement, and the value is an IRI.20 if the value is an IRI, and the property has a sh:nodeKind sh:IRI and no sh:class constraint.10 if the property has a sh:nodeKind sh:IRI constraint and no sh:class constraint.0 if the value is an IRI.
Rendering:
An input field to enter the IRI of a resource, e.g., as value of rdfs:seeAlso or to enter the URL of an image on the web.
ex:Thing-seeAlso
a sh:PropertyShape ;
sh:path rdfs:seeAlso ;
sh:nodeKind sh:IRI ;
shui:editor shui:IRIEditor ;
...
40 if the property indicates its preference for shui:NumberFieldEditor using a shui:editor
statement, and the value is an xsd:decimal, xsd:integer, xsd:double, or xsd:float literal.
20 if the value is an xsd:decimal, xsd:integer, xsd:double, or xsd:float literal.10 if the property has a sh:datatype xsd:decimal, xsd:integer, xsd:double, or xsd:float
constraint.
Rendering:
An input field to enter numeric values. The field should only allow entering valid numeric values according
to the specified datatype. If no sh:datatype constraint is specified, xsd:decimal is assumed to be the
default numeric datatype.
ex:Product-price
a sh:PropertyShape ;
sh:path ex:price ;
sh:datatype xsd:decimal ;
shui:editor shui:NumberFieldEditor ;
...
40 if the property indicates its preference for shui:RichTextEditor using a shui:editor statement, and the value is an rdf:HTML literal.20 if the value is an rdf:HTML literal.10 if the property has a sh:datatype rdf:HTML constraint.
Rendering:
A rich text editor to enter the lexical value of a literal and a drop-down to select language.
The selected language is stored in the HTML lang attribute of the root node in the HTML DOM tree.
ex:Concept-definition
a sh:PropertyShape ;
sh:path skos:definition ;
sh:datatype rdf:HTML ;
...
40 if the property indicates its preference for shui:SubClassEditor using a shui:editor statement and has a sh:rootClass constraint, and the value is an IRI.
Rendering:
This can be an auto-complete widget to select a class, a class hierarchy widget, or a combination thereof.
The permissible values are a given class or its subclasses, defaulting to rdfs:Resource.
This is typically used with sh:rootClass to allow the user to select a subclass of the given root class.
ex:Drug-impactedCell
a sh:PropertyShape ;
sh:path ex:impactedCell ;
sh:rootClass obo:CL_0000000 ;
shui:editor shui:SubClassEditor ;
...
Accept matcher: Offered only if the property does not have a sh:singleLine true constraint,
expressed with a shui:WidgetAcceptMatcher.
40 if the property indicates its preference for shui:TextAreaEditor using a shui:editor statement.30 if the value is an xsd:string literal and the property has a sh:singleLine false constraint.20 if the value is an xsd:string literal.5 if the property has xsd:string among the permissible datatypes.0 if the property has a sh:singleLine false constraint.Rendering: A multi-line text area to enter the value of a literal.
ex:Country-description
a sh:PropertyShape ;
sh:path ex:description ;
sh:datatype xsd:string ;
sh:singleLine false ;
...
Accept matcher: Offered only if the property does not have a sh:singleLine true constraint,
expressed with a shui:WidgetAcceptMatcher.
40 if the property indicates its preference for shui:TextAreaWithLangEditor using a shui:editor statement.30 if the value is an rdf:langString or rdf:dirLangString literal and the property has a sh:singleLine false constraint.20 if the value is an rdf:langString or rdf:dirLangString literal.5 if the property has rdf:langString or rdf:dirLangString among the permissible datatypes.0 if the property has xsd:string among the permissible datatypes.
Rendering:
A multi-line text area to enter the value of a literal and a drop-down to select a language.
For an rdf:dirLangString value, it also provides a base-direction selector.
ex:Country-description
a sh:PropertyShape ;
sh:path ex:description ;
sh:datatype rdf:langString ;
sh:singleLine false ;
...
Accept matcher: Offered only if the property does not have a sh:singleLine false constraint,
expressed with a shui:WidgetAcceptMatcher.
40 if the property indicates its preference for shui:TextFieldEditor using a shui:editor statement.30 if the value is an xsd:string literal.10 if the property has xsd:string among the permissible datatypes.0 if the property has a custom datatype (not from xsd or rdf namespaces but for example geo:wktLiteral), or if the property has a sh:nodeKind sh:Literal constraint.Rendering: An input field to enter the value of a literal, without the ability to change language or datatype.
ex:Country-code
a sh:PropertyShape ;
sh:path ex:code ;
sh:datatype xsd:string ;
...
Accept matcher: Offered only if the property does not have a sh:singleLine false constraint,
expressed with a shui:WidgetAcceptMatcher.
40 if the property indicates its preference for shui:TextFieldWithLangEditor using a shui:editor statement.30 if the value is an rdf:langString or rdf:dirLangString literal.10 if the property has rdf:langString or rdf:dirLangString among the permissible datatypes.1 if the property has xsd:string among the permissible datatypes.
Rendering:
A single-line input field to enter the value of a literal and a drop-down to select language,
which is mandatory unless xsd:string is among the permissible datatypes.
For an rdf:dirLangString value, it also provides a base-direction selector.
ex:Concept-prefLabel
a sh:PropertyShape ;
sh:path skos:prefLabel ;
sh:datatype rdf:langString ;
...
The following subsections enumerate the currently built-in instances of shui:Viewer from the SHACL UI namespace.
40 if the property indicates its preference for shui:BlankNodeViewer using a shui:viewer statement, and the value is a blank node.1 if the value is a blank node.Rendering: A human-readable label of the blank node. For example, if the blank node is an OWL restriction, then Manchester Syntax could be used. If the blank node is a SPIN RDF expression, then a SPARQL string could be produced. This rendering may include hyperlinks to other resources that can be reached from the blank node.
40 if the property indicates its preference for shui:DetailsViewer using a shui:viewer statement, and the value is an IRI or a blank node.0 if the value is an IRI or a blank node.
Rendering:
Displays the details of the value node as a nested, form-like structure within the surrounding view.
The properties shown are determined by the shape that applies to the value node.
This may be specified explicitly (e.g., via sh:node or other mechanisms that associate a shape with the value),
inferred via constraints such as sh:class,
or defined directly as nested sh:property declarations on the property shape.
When rendered as a nested display, the implementation recursively evaluates the applicable shape and presents its property shapes as structured subsections of the parent form. Implementations may vary in layout and visual styling, but the logical grouping and recursive traversal of the applicable shape SHOULD be preserved.
40 if the property indicates its preference for shui:HTMLViewer using a shui:viewer statement, and the value is an rdf:HTML or xsd:string literal.20 if the value is an rdf:HTML literal.
Rendering:
The literal parsed into HTML DOM elements.
Hyperlinks in the HTML may get redirected to select resources within the same application.
Also displays the language if the HTML has a lang attribute on its root DOM element.
40 if the property indicates its preference for shui:HyperlinkViewer using a shui:viewer statement, and the value is an xsd:anyURI or xsd:string literal.20 if the value is an xsd:anyURI literal.0 if the value is an xsd:string literal.Rendering: A clickable hyperlink to the specified URI/URL.
40 if the property indicates its preference for shui:ImageViewer using a shui:viewer statement.20 if the value is an IRI or a literal that has a case-insensitive recognized image file extension ending such as .png, .jpg, .jpeg, .gif, or .svg.
Rendering:
The image at the given URL, using <img> in HTML.
40 if the property indicates its preference for shui:IRIViewer using a shui:viewer statement, and the value is an IRI.1 if the value is an IRI.Rendering: As a hyperlink to that IRI. Also includes other ways of interacting with the IRI, such as opening a nested summary display.
40 if the property indicates its preference for shui:LabelViewer using a shui:viewer statement, and the value is an IRI.10 if the value is an IRI.
Rendering:
As a hyperlink to that URI based on the display label of the resource.
The display label is typically based on the most suitable rdfs:label or
skos:prefLabel for the current user, based on their language preferences.
Also includes other ways of interacting with the URI, such as opening a nested summary display.
40 if the property indicates its preference for shui:LangStringViewer using a shui:viewer statement.20 if the value is an rdf:langString or rdf:dirLangString literal.
Rendering:
As the text plus a language indicator (flag or language tag).
For an rdf:dirLangString value, the base direction is applied to the rendered text and indicated as well.
40 if the property indicates its preference for shui:LiteralViewer using a shui:viewer statement.1 if the value is a literal.Rendering: The lexical form of the value.
This is a Multi Viewer.
Score:40 if the property indicates its preference for shui:ValueTableViewer using a shui:viewer statement.
Rendering:
All values of the property at the focus node are rendered into a single (HTML) table that can be scrolled
and paged independently of the rest of the form.
Each value becomes one row.
The columns of the table are derived from the node shape specified using sh:node for the property,
in the order specified using sh:order, as defined in
Grouping, Ordering, and Layout Hints.
In this example, we have used a sh:values rule to infer the values of the first column.
In this case, the values are simply pointing back to the focus node of each row, using sh:this.
Note that sh:targetClass is needed to get this inference correctly.
skos:Concept
sh:property ex:Concept-broader-inverse .
ex:Concept-broader-inverse
a sh:PropertyShape ;
sh:path [ sh:inversePath skos:broader ] ;
sh:group skos:HierarchicalRelationships ;
sh:name "narrower (table)" ;
shui:viewer shui:ValueTableViewer ;
sh:node ex:ConceptTableShape .
ex:ConceptTableShape
a sh:NodeShape ;
sh:targetClass skos:Concept ;
rdfs:comment "A node shape defining the columns for a shui:ValueTableViewer." ;
rdfs:label "Concept table shape" ;
sh:property ex:ConceptTableShape-self ;
sh:property ex:ConceptTableShape-type ;
sh:property ex:ConceptTableShape-altLabel .
ex:ConceptTableShape-self
a sh:PropertyShape ;
sh:path ex:self ;
sh:description "This column is used to render the (narrower) concept itself." ;
sh:name "narrower concept" ;
sh:nodeKind sh:IRI ;
sh:order "0"^^xsd:decimal ;
sh:values sh:this .
ex:ConceptTableShape-type
a sh:PropertyShape ;
sh:path rdf:type ;
sh:description "The second column shows the type of each value." ;
sh:name "type" ;
sh:nodeKind sh:IRI ;
sh:order "1"^^xsd:decimal .
ex:ConceptTableShape-altLabel
a sh:PropertyShape ;
sh:path skos:altLabel ;
sh:description "The third column shows the alternative labels." ;
sh:name "alt labels" ;
sh:datatype ( xsd:string rdf:langString ) ;
sh:order "2"^^xsd:decimal .
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, descriptions, and other rendering properties.
This section introduces Property Roles for annotating SHACL property shapes, along with several built-in property roles defined in the SHUI namespace.
Property Roles are defined in the SHUI namespace and define the class shui:PropertyRole and the property shui:propertyRole.
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 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 is done, 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.
This example 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.
When multiple predicates serve the same role in the data but require a defined precedence, the qualified role annotation should be used.
If multiple property shapes share the same role, they must be sorted in ascending order of their sh:order values, and any
property shape using a qualified role annotation comes before a shape using a direct, unqualified role annotation. For roles that render
a single value, such as shui:LabelRole, this order determines precedence, and user interfaces should prefer the first shape
that yields a value. For roles that render all values, such as shui:ClassificationRole, all shapes contribute, and this order
only determines the display order of their values. The order of the values within a single shape is left to the implementation.
In both cases, this use of sh:order is unrelated to the presentation order defined in
Grouping, Ordering, and Layout Hints.
The following example demonstrates two property shapes with qualified role annotations ordered by sh:order.
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.
This example demonstrates two property shapes with qualified role annotations ordered by sh:order using RDF 1.2 triple annotations.
The following sections define the instances of shui:PropertyRole in the SHUI namespace. Additional property roles may be defined in other namespaces.
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.
When displaying a resource, SHACL Renderers SHOULD apply Label Resolution to the values of these properties and render a single label.
Properties marked with the property role shui:DepictionRole provide images that depict the individual resource, such as a photo of a person.
Common examples include schema:image and foaf:depiction. These depictions SHOULD be distinct for each resource.
Values SHOULD be IRIs or literals with datatype xsd:anyURI or xsd:string that hold the URL of an image,
with a case-insensitive recognized image file extension ending such as .png, .jpg, .jpeg,
.gif, or .svg.
SHACL Renderers SHOULD render a single depiction for a resource. When multiple values are available, the selection of the depiction to render is left to the implementation.
Depictions are typically rendered larger than icons and are not constrained to a square box. In contrast to
shui:IconRole, a depiction is expected to be specific to the individual resource rather than shared across instances.
This example illustrates a property shape directly annotated with shui:DepictionRole, indicating that its values are URLs of
images that depict the resource.
Properties marked with the property role shui:ClassificationRole indicate the kind or group that the resource belongs to.
Common examples of classification predicates include rdf:type, skos:inScheme, and schema:category.
User interfaces commonly render classification values near a resource's label, for example as a type badge.
SHACL Renderers SHOULD render all classification values of a resource.
This example illustrates a property shape directly annotated with shui:ClassificationRole, indicating that its rdf:type values
classify the resource.
This example illustrates a property shape annotated with shui:ClassificationRole, indicating that its skos:inScheme
values classify a SKOS concept by the concept scheme it belongs to.
Properties marked with the property role shui:DescriptionRole provide textual descriptions that typically summarize or introduce the resource.
Common examples include rdfs:comment, skos:definition, and schema:description.
Values SHOULD have datatype xsd:string, rdf:langString, rdf:dirLangString, or rdf:HTML.
SHACL Renderers SHOULD render a single description for a resource, selected using Language Resolution when multiple language-tagged values are available. When multiple candidate values remain, the selection of the description to render is left to the implementation.
This example illustrates a property shape directly annotated with shui:DescriptionRole, indicating that its values are
textual descriptions of the resource.
Properties marked with the property role shui:IconRole produce small images that may be displayed next to a resource's label,
for example in the corner of a card or to the left of a label in a tree view. Instances of the same class often share the same icon, which
may be computed using sh:values or supplied via sh:defaultValue.
Common examples include schema:logo and foaf:logo. Values SHOULD be IRIs or literals with datatype xsd:anyURI
or xsd:string that hold the URL of an image, with a case-insensitive recognized image file extension ending such as
.png, .jpg, .jpeg, .gif, or .svg.
SHACL Renderers SHOULD render a single icon for a resource.
Icons are typically rendered at small sizes and are often reused across many resources. Scalable formats such as SVG are therefore
usually a good choice. In contrast to shui:DepictionRole, icon values are not expected to be distinct per resource.
This example uses sh:defaultValue so that every instance of ex:Island without its own ex:islandIcon
value is represented by the same icon.
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.
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.
This section is non-normative.
SHACL UI is designed to be extensible. Beyond the built-in widgets, additional widgets may be published in community-maintained registries that continue to evolve after this specification has been published and the Working Group's charter has ended.
The community widget
registry collects additional viewers and editors that extend the built-in widgets. It is
hosted in the shacl-ui/ directory of the
w3c/shacl-resources repository, where it is
documented and maintained independently of this specification. Registered widgets are instances
of the widget classes defined here, identified in the shuic
namespace (http://www.w3.org/ns/shacl-ui-community/) to keep them separate from the built-in
shui namespace. Adding a widget requires no change to this specification.
Other extension points, such as property roles, may be organized into registries following the same approach.
This section is non-normative.
SHACL UI shares the security considerations of SHACL Core and, where SPARQL-based features are used, SHACL-SPARQL. The shapes graph, the scoring graph, and the data graph together determine what is rendered, which widgets are used, and which queries are evaluated, so any of these graphs from an untrusted source, for example submitted by end users, is a risk in itself.
SHACL UI does not define access control. Not rendering a property does not protect its values; access has to be enforced in the data layer.
rdf:HTML literals, rendered by the HTMLViewer, the
RichTextEditor, and the shui:DescriptionRole, can inject
scripts or event handlers when inserted as is. IRIs turned into links, for example by the
HyperlinkViewer, can use schemes such as javascript:.
Common mitigations are sanitizing HTML, sandboxing, restricting IRI schemes, and a Content Security
Policy [CSP3].
Search input is substituted as escaped string literals and cannot alter the structure of a
shui:searchQuery. The query itself, and select expressions, can contain a
SERVICE clause that sends requests to arbitrary endpoints. Implementations can restrict the
endpoints that may be queried or route requests through a proxy.
Shapes graphs from third parties can be used for denial of service: queries, complex property paths, node expressions, and recursive forms can cause excessive computation, and search queries may be evaluated on every keystroke. Implementations can limit this with timeouts, result limits, and debouncing.
Implementations may support widgets beyond the built-in widgets. How such custom widgets are loaded is up to the implementation, which is responsible for doing so safely, for example by only loading widgets that are trusted and necessary. Their matchers can also be computationally heavy and lead to denial of service.
This section is non-normative.
A SHACL Renderer does not itself collect data about the end user or their interactions, persist state across sessions, or access device sensors. It displays and edits the data handed to it by the application. The data graph may contain personally identifiable information; applications are advised to pass only the data the end user needs and is allowed to see, and to take applicable regulations such as GDPR into account.
Some features disclose information to third parties:
shui:searchQuery sends the search input, as it is typed, and the preferred language
to the endpoint evaluating it and to any endpoint in a SERVICE clause.
shui:DepictionRole and
shui:IconRole, and rendered HTML may load resources from IRIs in the data graph, revealing
the end user's IP address and viewing time to whoever controls the IRI. Implementations can load
such resources only after a user action, or through a proxy.
This specification does not require revealing the use of assistive technology.
This section is non-normative.
TODO
This section is non-normative.
Many people contributed to this document, including members of the RDF Data Shapes Working Group.
This section enumerates the SHACL Core syntax elements and links to their corresponding SHACL UI representations.
| Section used | |
|---|---|
| Shapes | |
| sh:NodeShape | |
| sh:PropertyShape | |
| Constraint Components | |
| Value Type Constraint Components | |
| sh:class | |
| sh:datatype | |
| sh:nodeKind | |
| Cardinality Constraint Components | |
| sh:minCount | |
| sh:maxCount | |
| Value Range Constraint Components | |
| sh:minExclusive | |
| sh:minInclusive | |
| sh:maxExclusive | |
| sh:maxInclusive | |
| String-based Constraint Components | |
| sh:minLength | |
| sh:maxLength | |
| sh:pattern | |
| sh:singleLine | |
| sh:languageIn | |
| sh:uniqueLang | |
| List Constraint Components | |
| sh:memberShape | |
| sh:minListLength | |
| sh:maxListLength | |
| sh:uniqueMembers | |
| Property Pair Constraint Components | |
| sh:equals | |
| sh:disjoint | |
| sh:subsetOf | |
| sh:lessThan | |
| sh:lessThanOrEquals | |
| Logical Constraint Components | |
| sh:not | |
| sh:and | |
| sh:or | |
| sh:xone | |
| Shape-based Constraint Components | |
| sh:node | |
| sh:property | |
| sh:someValue | |
| sh:qualifiedValueShape | |
| sh:qualifiedMinCount | |
| sh:qualifiedMaxCount | |
| sh:reifierShape | |
| sh:reificationRequired | |
| Other Constraint Components | |
| sh:closed | |
| sh:ignoredProperties | |
| sh:hasValue | |
| sh:in | |
| sh:rootClass | |
| Non-Validating Property Shape Characteristics | |
| sh:order | Grouping, Ordering, and Layout Hints |
| sh:group | Grouping, Ordering, and Layout Hints |
| sh:PropertyGroup | Grouping, Ordering, and Layout Hints |
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: