[UI] Add widget score definitions

[edmondchuc]

This PR adds the widget scores and shapes for SHACL UI.

Some notes:

• The null value originally defined in DASH forms is now 0
• With the original DASH forms' 0 case, I've crossed it out in the doc for now with the <s> tag. We'll keep these rules around for reference until we've implemented the widget scores confirmed they're not needed

• See this document rendered online here

[edmondchuc]

Leaving in draft until all widget scores have been added.

[smessie]

I’m marking this PR as ready for review.
However, please be aware that the current approach for handling the shui:editor statement to indicate the preferred editor is still under discussion in our TF.
Nevertheless, all other aspects of the PR are ready for review, allowing us to move on.

[robsyc]

Not sure if this is the right place to bring this up but DetailsViewer references a "Nested forms" section that doesn't exist and for which I cannot find an open issue.

The dash draft did have a section on nesting and marks that:

Using dash:DetailsViewer as the dash:viewer ... instructs a form engine to recursively "walk" into the linked resource and show its values as a sub-form of the surrounding form. The value of sh:node tells the form engine which selection of properties to display, and in which order.

I find the current descriptions and scoring functions for components related to nested shapes (BlankNodeEditor/Viewer and DetailsEditor/Viewer) a bit too indecisive and have the following questions:

• How is a form-builder to interpret a property with sh:node ex:MyNestedNodeShape but without an explicit UI hint or sh:datatype - simply ignore it?
• If the sh:node constraint is so integral to the rendering of subforms, why is it not part of the scoring function, e.g., score 1 if the property has sh:node - I do see this may be problematic in respect with example 7 where sh:node is strictly used to narrow down the search space of the AutoCompleteEditor's options

[smessie]

Not sure if this is the right place to bring this up but DetailsViewer references a "Nested forms" section that doesn't exist and for which I cannot find an open issue.

The dash draft did have a section on nesting and marks that:

Using dash:DetailsViewer as the dash:viewer ... instructs a form engine to recursively "walk" into the linked resource and show its values as a sub-form of the surrounding form. The value of sh:node tells the form engine which selection of properties to display, and in which order.

Thank you for your feedback. I have updated the DetailsEditor and DetailsViewer sections in 53a33ee to incorporate an extra clarification on nested forms directly and removed the link to the non-existing nested forms section.

I find the current descriptions and scoring functions for components related to nested shapes (BlankNodeEditor/Viewer and DetailsEditor/Viewer) a bit too indecisive and have the following questions:

• How is a form-builder to interpret a property with sh:node ex:MyNestedNodeShape but without an explicit UI hint or sh:datatype - simply ignore it?

I assume you mean having a shui:editor/shui:viewer property as an explicit UI hint?

If there’s no data in the data graph and no constraint on the property shape, the renderer and scoring system can’t determine what to render, resulting in no matching widget scores.
However, if there’s matching data in the data graph for that property, it can base its scoring on that and assign a score of 0 to the DetailsEditor and the IRIEditor.
By design, if you want a nested form, you’ll need to attach the shui:editor shui:DetailsEditor statement to your property shape. This ensures that only if desired, a nested form will render, preventing accidental recursive shapes.
Note, the widget scoring algorithm is being developed and will be included in a subsequent PR. This will provide further insights into how to use these widget scores.

• If the sh:node constraint is so integral to the rendering of subforms, why is it not part of the scoring function, e.g., score 1 if the property has sh:node - I do see this may be problematic in respect with example 7 where sh:node is strictly used to narrow down the search space of the AutoCompleteEditor's options

Because sh:node is only one way to have a nested form, e.g. in SHACL 1.2 Node Expressions, we will have sh:nodeByExpression.
Could you please rephrase the issue you’re facing with example 7?

[robsyc]

Thanks for the clarification.

My main concern is to do with how rendering of nested forms can be reached. The current scoring for DetailsEditor:

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

As I see it, an implementation can only render a subform iff a value (IRI or BlankNode) is present in the data graph. Say we have the following shapes graph with a basic nested shape:

ex:OrganizationShape a sh:NodeShape ;
  sh:targetClass ex:Organization ;
  sh:property [
  sh:path ex:headquarters ;
    sh:name "Headquarters" ;
    sh:description "Main office address (single nested shape)" ;
    sh:node ex:AddressShape ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] .

ex:AddressShape a sh:NodeShape ;
  rdfs:label "Address" ;
  sh:targetClass ex:Address ;
  sh:property [
    sh:path ex:street ;
    sh:name "Street" ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:order 0
  ] , [
    sh:path ex:city ;
    sh:name "City" ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:order 1
  ] , [
    sh:path ex:country ;
    sh:name "Country" ;
    sh:in ( "US" "CA" "UK" "DE" "FR" "NL" "AU" "JP" ) ;
    sh:maxCount 1 ;
    sh:order 2
  ] .

If there is no value yet, such as when the dataGraph is empty, it doesn't even matter whether an explicit shui:editor hint is provided because the spec expects a value either way. I think this is problematic because the AddressShape is required (sh:minCount 1 on the property in OrganizationShape) and so a form-builder has to either:

• not follow the spec and render the empty sub-form anyway, creating a new blank-node
• create a form that lacks the subform, leading to form-submissions that generate non-validating data

I think there needs to be either

• more permissible scoring for DetailsEditor that lends itself to supporting an empty data graph e.g., "40 if the property indicates its preference for shui:DetailsEditor using a shui:editor statement, and the v̶a̶l̶u̶e̶ sh:nodeKind is an IRI or a blank node."
• an explicit section on nested forms support and guidance on when to render buttons that trigger the creation of new blank/named nodes in the datagraph for properties that could have a nested form

[smessie]

As I see it, an implementation can only render a subform iff a value (IRI or BlankNode) is present in the data graph.

Incorrect. The scoring system that I mentioned will define that, if there is no data in the data graph for the property shape, it will ignore the shui:dataGraphShape, and in that case, it will only consider widget scores that do have at least one value for the shui:shapesGraphShape.

[robsyc]

I don't understand, what does it mean to "only consider widget scores that have at least one value for the shui:shapesGraphShape" ?

You don't agree that the current scoring definition for DetailsEditor leaves no room for assigning a score to the widget in the absence of a dataGraph? Perhaps I'm misunderstanding the notion of "value" in the scoring definitions, I see it as field values or a dataGraph that is the result of submitting a SHACL-based form. That which is validated against the shape and can be used to pre-populate the form.

[edmondchuc]

All looks good to me. I can't approve the PR since I opened it, but here's a green tick anyway. ✅

[bergos]

I think all the shui:prefers* and related widget scores aren't required. Also, we should consider merging the scores into a single file.

Both changes can be done in a separate PR.