[UI] Define the SHACL UI feature set

[smessie]

Addresses the first open point of #1164 — the feature set itself: what the features are and where the boundaries fall — discussed in the 18 August task-force meeting and proposed by @edmondchuc as the next step.

This is a proposal for discussion, not settled text.

What it does

Replaces the TODO in the Conformance section of shacl12-ui/index.html with:

• Conformance defined in terms of named features. An implementation records which features it supports, and a claim always states what it covers — no unqualified "conforms to SHACL UI".
• Interpretation vs presentation. Features constrain interpretation (which fields, order, grouping, labels, widget, value handling) and are defined so conformance is checkable from machine-readable output. Presentation (styling, layout) is unconstrained.
  This checkability depends on [UI] Decision: should the specification define a rendering model separate from presentation? #1165 — whether the specification defines an abstract rendering model, distinct from presentation, as the basis for conformance testing. If that model is not defined, the machine-readable output these features are checked against is not specified.
• Cross-cutting contracts: no silent omission, fallback on unknown widget IRIs, extensibility beyond any required set, and presentation left unconstrained.
• A feature catalogue: a single index table (number · feature · what supporting it means · specification sections · suggested conformance level). The authoritative behaviour of each feature stays in the linked sections; the table does not restate the normative requirements, so a section and its feature entry are not kept in sync separately (single source of truth).

Granularity principle

One rule decides the boundaries: a behaviour graded SHOULD or MAY gets its own feature, so it is independently reportable and can be marked not-required, rather than being bundled with a stronger requirement. This lets an implementation's list of supported features tell a user precisely what to expect.
Property paths are split by path kind and by view/edit mode, so a read-only viewer and an editor report path support separately.

What is in the document vs. in this PR

• In the specification: the feature index table (number, feature, behavioural description, section mapping, suggested-level column), the cross-cutting contracts, and editor's-note / issue-box markers for provisional or not-yet-defined areas. The behavioural definition of each feature lives in the linked sections, not in the table.
• In this PR body: the proposal framing, the granularity principle above, the boundary rationale below, and the open questions — the material meant for task-force discussion rather than the published draft.

Proposed features (26)

Feature	Suggested level
Language preference via sh:languageIn	Required
Application and browser language preference	Recommended
Cross-language fallback	Optional
Label resolution	Required
Local name humanization	Recommended
Direct role annotation	Required
Qualified role annotation	Recommended
Explicit sh:order	Required
Default order configuration (shui:defaultOrder)	Required
Unordered-member fallback	Recommended
Deterministic tie-breaking	Required
Standard tie-breaking algorithm	Recommended
Grouping (sh:group)	Required
Nested groups	Recommended
Built-in widgets	Required
Widget scoring	Required
Default widget selection	Recommended
Declared widgets (shui:editor/shui:viewer)	Required
Widget switching	Optional
Value preservation	Required
Predicate and inverse paths — view	Required
Predicate and inverse paths — edit	Required
Alternative paths — view	Recommended
Alternative paths — edit	Recommended
Complex paths — view	Recommended
Complex paths — edit	Optional

Boundary rationale

• Language is split into sh:languageIn (MUST → Required), application/browser preference (SHOULD → Recommended) and cross-language fallback (MAY → Optional), so an implementation without browser context can report only what it does.
• Label resolution keeps the property and value-node chains together (both MUST) but separates local name humanization (SHOULD).
• Property roles separate direct (Required) from qualified precedence (SHOULD, incl. the RDF 1.2 triple-annotation form).
• Ordering follows the normative lines of [UI] Decision: what behaviour is defined when sh:order is absent? #1162: explicit sh:order and shui:defaultOrder (Required), unordered-member fallback (Recommended — [UI] Decision: what behaviour is defined when sh:order is absent? #1162 proposes MUST → SHOULD, dependency noted in the draft), deterministic tie-breaking (Required) split from the specific label-then-identifier algorithm (Recommended).
• Grouping separates flat membership (Required) from nested groups (Recommended; the draft already makes nesting optional).
• Widgets separate scoring (Required) from default selection (SHOULD → Recommended), declared widgets (Required), and switching (MAY → Optional).
• Value preservation is distinct from the no-silent-omission contract: the contract covers properties an implementation cannot handle at all; the feature covers not dropping values for properties it does handle.
• Property paths are split by kind and mode so viewing and editing are reported independently.

Open questions

• Granularity. How finely to divide the feature set is open. I favour a more granular set: the finer the features, the more clearly and precisely an implementation can state what it supports, which is the whole point of reporting features. This PR therefore leans fine-grained — property paths, for example, are split into six features by kind and by view/edit mode. The open question is whether we find any of these too fine and want them merged. Resolving it also informs the profiles question ([UI] Decision: what does a conformance claim guarantee, and do claims name what they cover? #1164 third open point), since we can only see how features cluster once the set exists.
• Required set. The suggested levels are only suggestions ([UI] Decision: what does a conformance claim guarantee, and do claims name what they cover? #1164 second open point).
• Widget switching is reported as a capability but is hard to check from output; it may be better treated as an affordance than a feature.
• RDF 1.2 support is a SHOULD (RDF Abstract Model Compatibility). It is kept in that section rather than added as a feature; whether it should also be a reportable feature is open.
• Recording and publishing feature support ([UI] Decision: what does a conformance claim guarantee, and do claims name what they cover? #1164 fourth open point) is out of scope here.

Related: #1083, #1162, #1165, #1146, #1160, #1142, #823.

---

• See this document rendered online here

[danielbeeke]

I like this very much, thanks for making (a start of) the list of features.

I think it is a good start!

[danielbeeke]

Looks good, some request for changes

[edmondchuc]

I'm wondering whether this should be recommended rather than required. We could perhaps split this so that a small set of widgets capable of handling IRIs, blank nodes, and literals are required and can be selected by the scoring system as fallbacks, while all other widgets are recommended.

The idea is that this small set of required widgets would still allow a SHACL Renderer to be functional without requiring implementations to support every widget defined by the specification.

[danielbeeke]

@edmondchuc what are your thoughts on #1173 (comment)? There is a somewhat smaller set of required widgets and only the outcome is defined and not the exact IRI of the widget that must be implemented. This gives implementers freedom for example, to create an editor that handles both blank nodes and IRIs so that you can give the possibility to change a blanknode to an IRI.

[smessie]

Thanks for the feedback, both! I've now applied @danielbeeke's suggestion from the linked comment to define the expected behavior with linked conformance levels, rather than defining the expected widget implementations to be supported.

[danielbeeke]

What if we would record outcomes instead of specific widgets?
Also we could group them together something like:

Feature	What supporting it means	Specification sections	Conformance level
Editor for IRIs	Edit an IRI value.	shui:IRIEditor	Required
Editor for Blank nodes	Edit a value that is a blank node via its nested shape.	shui:BlankNodeEditor	Required
Editors for xsd:boolean, xsd:date, xsd:dateTime, xsd:integer, xsd:double, xsd:float, xsd:decimal, xsd:string	It is possible to edit literals that have these data types.	shui:BooleanEditor, shui:DatePickerEditor, shui:DateTimePickerEditor, shui:NumberFieldEditor, shui:TextFieldEditor and shui:TextAreaEditor	Required
Editors for rdf:langString	It is possible to edit literals with language and set the language.	shui:TextAreaWithLangEditor and shui:TextFieldWithLangEditor	Required
Editor for rdf:HTML	It is possible to edit literals that have these data types.	shui:RichTextEditor	Recommended

[smessie]

Yes, I like this suggestion! I've applied it in c4a0222 and have also taken into account the viewers.

[bergos]

I think the feature list would be useful as a matrix mapped against use cases, to help identify profiles.

It should not become part of the specification. It's unnecessarily complex, and there are already established ways to define varying conformance within a single specification, such as profiles, conformance levels, or conformance classes. I don't see the point of introducing something new.

[nicholascar]

@bergos

I think the feature list would be useful as a matrix mapped against use cases, to help identify profiles.

The Use Cases the UI Task Force has defined are informal - not registered in any way with the W3C - so they are helpful for this TF's work but they cannot be quoted in the document. I'm not sure if you were suggesting that or just a comparison of Features & Use Cases in this PR discussion.

I suggest that you, and other UI UCR authors, compare the list of Features to your Use Cases and see if you can identify any collisions, perhaps in the UCR Issues. Having the Features listed should make this easy.

Regarding Profiles:

If Features can be easily identified and their Conformance levels known, there will be no need for this specification to also articulate Profiles as well - that's another mechanism. The Required Features will make a Core, which you could think of as a Core Profile if you like but it need not be described beyond just the set of Required Features.

Others could do that after this specification's publication, for other purposes.

It should not become part of the specification.

I think it, or something like it, should. The major issue currently seems to be what things are mandatory and what are not. A listing of Features with conformance imperatives - Required, Recommended, Optional as above - would make this clear. The set of Required Features would make the Core of this specification.

It's unnecessarily complex, and there are already established ways to define varying conformance within a single specification, such as profiles, conformance levels, or conformance classes. I don't see the point of introducing something new.

I don't think this is complex: it's just a listing of the parts of SHACL UI and the level of requirement for them to be implemented.

It's true there are different ways of implementing conformance things within a specification - Conformance Classes, Profiles etc - but feature listing with imperatives is a reasonable way of doing this and it reveals the Core, as indicated above.

My only suggestion is that the features should be able to be ordered in their table based on their Conformance Level so that the Core - those with level Required - are able to be grouped easily.

I recommend that this PR be merged and the discussion about what is and isn't mandatory to be implemented be piked up per-Feature, noting that elsewhere I've suggested that data preparation for an implementing engine could likely handle at least one of your Use Cases (#1142).

[bergos]

@nicholascar

The Use Cases the UI Task Force has defined are informal - not registered in any way with the W3C - so they are helpful for this TF's work but they cannot be quoted in the document. I'm not sure if you were suggesting that or just a comparison of Features & Use Cases in this PR discussion.

I was proposing that we use the current list of features to compare against the use cases, and then shape the concepts based on that outcome. Since that's not part of this PR, it probably shouldn't happen here.

Regarding Profiles:

If Features can be easily identified and their Conformance levels known, there will be no need for this specification to also articulate Profiles as well - that's another mechanism. The Required Features will make a Core, which you could think of as a Core Profile if you like but it need not be described beyond just the set of Required Features.

Others could do that after this specification's publication, for other purposes.

I agree with that. I made the same point with different wording here: #1164 (comment). I wanted to continue the discussion in the issue I created for that topic, as requested, but no feedback has come through yet.

If we agree to work with concepts, we also agree on profiles. Otherwise, structuring the specification into concepts does not make sense. The set of concepts an implementation supports would already be a profile, at a very low level. I hope we can agree on profiles at a higher level of abstraction.

It should not become part of the specification.

I think it, or something like it, should. The major issue currently seems to be what things are mandatory and what are not. A listing of Features with conformance imperatives - Required, Recommended, Optional as above - would make this clear. The set of Required Features would make the Core of this specification.

The features, as currently structured, can't be traced back to their actual definitions. A single feature may correspond to just part of a sentence, or to an entire paragraph within a section. For example, look at the features listed for Grouping, Ordering, and Layout Hints, then compare them against that section itself.

It's unnecessarily complex, and there are already established ways to define varying conformance within a single specification, such as profiles, conformance levels, or conformance classes. I don't see the point of introducing something new.

I don't think this is complex: it's just a listing of the parts of SHACL UI and the level of requirement for them to be implemented.

What I actually requested — and this is why I use the term "concepts" to distinguish them from "features" — is a list where each entry maps to a clearly defined, discrete part of the specification.