SHACL-DASH for user input forms and data validation

[jsheunis]

I am investigating the use of SHACL and DASH, specifically starting from the draft document: Form Generation using SHACL and DASH. I will collect notes in this issue.

prefixes:
   dash:https://datashapes.org/dash
   shacl:https://www.w3.org/TR/shacl/

---

Notes

Some basics on SHACL and RDF graphs

Graphs have nodes:

Nodes in an RDF graph that are subclasses, superclasses, or types of nodes in the graph are referred to as SHACL class.

Nodes have properties:

A property is an IRI. An RDF term n has a value v for property p in an RDF graph if there is an RDF triple in the graph with subject n, predicate p, and object v. The phrase "Every value of P in graph G ..." means "Every object of a triple in G with predicate P ...".

A SHACL graph contains shapes that define the validation specifics of nodes and of properties: i.e. node shapes and property shapes.

A shape has a target class sh:targetClass.

The sh:targetClass statement tells a system that this shape applies to all instances of the [provided] target class that are managed by this data graph and application. This means that all instances of that class (and its subclasses) must fulfill the constraints defined for the shape

Regarding property shapes:

The sh:datatype constraint states that the values of this property must be literals with datatype xsd:string. All of our example fields are strings, yet typical other choices are xsd:boolean, xsd:integer, xsd:decimal (for floating point values), rdf:langString for language-tagged strings and rdf:HTML for rich text fields. Or use sh:class or sh:node to state that values can be resources with certain types and structures.

SHACL constraints for forms

• sh:order and sh:group can aid in the construction of form layouts, for example to state that a street address field should be showing up in an Address section and above the city and postal code, while contact phone numbers should show up in a different section.
• sh:order is interpreted such that properties and groups with lower values show up on top of those with higher values. Properties that have no sh:order should be placed at the bottom, and then sorted alphabetically for consistency. Note that sh:order values are xsd:decimal literals, and fraction digits can be used to squeeze entries in between existing properties. This makes it possible for other shape graphs to insert additional fields into a shape definition.
• Property groups are simple stand-alone objects that primarily define display label and possibly a description (rdfs:comment) helping users what needs to be entered in the contained properties. The sh:order field is used to determine the relative order of property groups.
• sh:description field can be used to display instructions to users
• sh:in to enumerate all permitted values of a property. The presence of sh:in can be used by a form builder to display a selection box with exactly those options.
• sh:minCount and sh:maxCount for items in a list/array
• sh:minLength and sh:maxLength for the amount of characters/digits of a property
• sh:pattern for a regular expression
• When a shape specifies multiple data types or classes, use sh:or with a list of types/classes. The user interface should then provide the user with the option of selecting any type/class from the list before completing the form property.

SHACL path expressions

• https://www.w3.org/TR/shacl/#property-paths
• A common use of path expressions is to walk a property in the inverse direction. Consider the schema:address property, which is modeled to point from a person (as subject) to an address (as object). There might be multiple persons with the same address, for example. To achieve this, a property shape using an sh:inversePath expression can be used. With this solution, the values of schema:address can appear on different forms, supporting viewing and editing from multiple directions.
• SHACL path expressions make it possible to define the characteristics of values that may be one or more steps away from the focus node. In the following example, the data from the person and the address resource are combined into a single, "flattened" form:

  sh:property [
   	a sh:PropertyShape ;
                sh:path (
   		schema:address
   		schema:streetAddress
   	) ;
  

• We have seen above that SHACL path expressions can be employed to collect values that may not be stored as "direct" values of a focus node. The concept of inferred values takes this one step further, and provides means to dynamically compute values and then render them on forms. The inferencing aspects of SHACL are covered by the document SHACL Advanced Features. For example:

  aushapes:AustralianAddressShape
   ...
   sh:property [
   	a sh:PropertyShape ;
   	sh:path aushapes:numberOfResidents ;
   	sh:datatype xsd:integer ;
   	sh:group aushapes:ResidentsPropertyGroup ;
   	sh:name "number of residents" ;
   	sh:values [
   		sh:count [
   			sh:path [
   				sh:inversePath schema:address ;
   			] ;
   		] ;
   	] ;
   ] .
  

Useful DASH namespace properties

• dash:editor links a property shape with an instance of dash:Editor such as dash:TextAreaEditor. Examples here.
• dash:singleLine: an alternative to dash:editor in this case is to declare a constraint dash:singleLine false. A constraint violation would be reported if a property is marked dash:singleLine true yet has line breaks. In the case of false, a form builder can infer that the values are explicitly allowed to have multiple rows, and therefore a text area should be preferred over a text field.
• DASH readily provides lists of multiple data types/classes that can be used in sh:or declarations:
  • dash:StringOrLangString: xsd:string or rdf:langString
  • dash:HTMLOrStringOrLangString: rdf:HTML or xsd:string or rdf:langString
  • dash:DateOrDateTime: xsd:date or xsd:dateTime
• Using dash:DetailsViewer as the dash:viewer (or dash:DetailsEditor as the dash:editor) 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.
• The property dash:defaultViewForRole can be used to state which view shape should be used for which type of users. E.g.: dash:defaultViewForRole dash:all ; indicates that this view shape shall be used to render a node for all users.

Suggestions to users for fixing validation errors

DASH Suggestions Vocabulary: https://datashapes.org/suggestions.html