Ontology Modeling with SHACL: Defining Forms for Instance Data

The previous articles of this series, such as Getting Started, have introduced SHACL as a language for representing structural constraints on (knowledge) graphs: classes, attributes, relationships and shapes. These language features describe the formal characteristics that valid instances need to have, in a machine-readable syntax.

Yet, most well-designed ontologies also contain information aimed at human users, such as the display names of properties and their textual descriptions. For example, the property that represents the square of a chess Piece from the first article was defined as follows:

shess:Piece-square
    a sh:PropertyShape ;
    sh:path shess:square ;
    sh:name "square" ;
    sh:description "For example a1 for the lower left corner." ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:pattern "^[a-h][1-8]$" .        

Different tools will use different bits of such SHACL declarations. A pure data validation tool will focus on constraints such as sh:minCount and sh:pattern and ignore the sh:name or sh:description statements. Yet, SHACL property shapes provide a natural framework for grouping information together that somehow belongs together. For example when we change the sh:pattern syntax rules for shess:square above we also want to update the description. Formal definitions and informal hints go hand in hand.

In this spirit, SHACL includes various built-in properties for describing not only what certain data shapes mean but also how they should be rendered by user interface tools. Let's introduce the SHACL vocabulary for defining user interface Forms.

Property Groups and Ordering

In order to illustrate these SHACL features, we introduce a couple of new classes to our running Chess example ontology since the previously defined classes for games and pieces are not really suitable for form-based rendering. We introduce an "abstract" base class Player and two subclasses for Computer-controlled players and Human players:

shess:Player
    a dash:ShapeClass ;
    dash:abstract true ;
    rdfs:label "Player" ;
    rdfs:subClassOf owl:Thing ;
    sh:property shess:Player-eloRating .

shess:ComputerPlayer
    a dash:ShapeClass ;
    rdfs:label "Computer Player" ;
    rdfs:comment "A Player that is controlled by software." ;
    rdfs:subClassOf shess:Player .

shess:HumanPlayer
    a dash:ShapeClass ;
    rdfs:label "Human Player" ;
    rdfs:comment "A Player that is a human being." ;
    rdfs:subClassOf shess:Player ;
    sh:property shess:HumanPlayer-dateOfBirth ;
    sh:property shess:HumanPlayer-depiction ;
    sh:property shess:HumanPlayer-familyName ;
    sh:property shess:HumanPlayer-givenName ;
    sh:property shess:HumanPlayer-wikidataPerson .        

Here is a sample instance of HumanPlayer:

ex:MagnusCarlsen
    a shess:HumanPlayer ;
    shess:eloRating "2829"^^xsd:decimal ;
    shess:familyName "Carlsen" ;
    shess:givenName "Magnus" ;
    shess:wikidataPerson wd:Q106807 ;
    rdfs:label "Magnus Carlsen" .        

A default rendering of such an instance could look as below, simply listing the properties from top to bottom:

A better rendering would be this, with properties arranged in dedicated groups:

In order to achieve this, only two additional SHACL properties are needed:

• sh:group links a property shape with a sh:PropertyGroup.
• sh:order defines the relative order of a property within its group. Typically the property on the top would have order 0 and the next one would be 1 etc. The relative order of sh:PropertyGroups is also defined using sh:order.

Using these two properties, here are the definitions for the properties in the "Names" group:

shess:NamesPropertyGroup
    a sh:PropertyGroup ;
    rdfs:label "Names" ;
    sh:order "0"^^xsd:decimal .

shess:HumanPlayer-givenName
    a sh:PropertyShape ;
    sh:path shess:givenName ;
    dash:singleLine true ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
    sh:minLength 1 ;
    sh:name "given name" ;
    sh:group shess:NamesPropertyGroup ;
    sh:order "0"^^xsd:decimal .

shess:HumanPlayer-familyName
    a sh:PropertyShape ;
    sh:path shess:familyName ;
    dash:singleLine true ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
    sh:minLength 1 ;
    sh:name "family name" ;
    sh:group shess:NamesPropertyGroup ;
    sh:order "1"^^xsd:decimal .        

TopBraid provides a dedicated panel for designing such form layouts using drag and drop to re-arrange the order of properties:

This information is enough to not just render instance data but to also produce data entry (editing) forms:

User Interface Widgets

The shapes from the ontology should contain enough information to help the user interface builder select suitable input widgets. For example, the "elo rating" property shape states that its values must have sh:datatype xsd:decimal, for which the UI would typically provide a simple input field. And the sh:maxCount 1 tells the form builder that the user cannot add a second row for that property:

shess:Player-eloRating
    a sh:PropertyShape ;
    sh:path shess:eloRating ;
    sh:datatype xsd:decimal ;
    sh:maxCount 1 ;
    sh:name "elo rating" ;
    sh:group shess:ChessPlayerCharacteristicsPropertyGroup ;
    sh:order "0"^^xsd:decimal .

shess:ChessPlayerCharacteristicsPropertyGroup
    a sh:PropertyGroup ;
    rdfs:label "Chess Player Characteristics" ;
    sh:order "1"^^xsd:decimal .        

In some cases, a user interface may have different widgets to choose from. For example, a property that only declares sh:datatype xsd:string may be rendered as a (single-line) text field or a (multi-line) text area. As humans we intuitively know that the given name of a person is usually a single-line value, but we need to teach this to the computer.

For this particular case, the DASH namespace implements two techniques:

• Set dash:singleLine to true. This is elegant because it will be used both for validation purposes and can be picked up by the user interface builder.
• Use dash:editor and dash:viewer to explicitly select widgets. This is a more general approach based on an extensible library of widgets.

Let's use the second technique to switch the given name property to a text area instead of a text field:

shess:HumanPlayer-givenName
    a sh:PropertyShape ;
    sh:path shess:givenName ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
    sh:minLength 1 ;
    sh:name "given name" ;
    dash:editor dash:TextAreaEditor ;
    sh:group shess:NamesPropertyGroup ;
    sh:order "0"^^xsd:decimal .        

This would be rendered as follows:

The DASH widget library declares stable identifiers for all kinds of frequently needed widgets that any SHACL-based rendering engine can reuse, including dash:AutoCompleteEditor and dash:RichTextEditor. These widgets are connected to a scoring mechanism that explains under which conditions they shall be preferred over others.

Summary and Outlook

This article has introduced two new properties sh:group and sh:order that can be placed in SHACL property shapes to suggest how user interface engines should render instances of the classes that the shapes describe. Usually, SHACL shapes contain enough information to also select widgets for specific properties, but the DASH vocabulary can be used for even finer-grained control.

These features of SHACL mean that ontology designers have pretty good control over how their classes and properties will be used. User interface tools can use SHACL to discover how to best handle a given knowledge graph based on purely declarative means - nothing is hard-coded here. In our product, TopBraid, we even use shapes to declare the layout of sh:NodeShape, sh:PropertyShape and classes, with essentially the whole user interface being driven by SHACL shapes.

Appendix

Here are the definitions of the three remaining properties, for completeness sake. Note that dateOfBirth and depiction are "fetched" from Wikidata through SHACL property path expressions. Therefore only the link to the Wikidata human needs to be asserted in the graph and the other values are "inferred" automatically.

shess:HumanPlayer-wikidataPerson
    a sh:PropertyShape ;
    sh:path shess:wikidataPerson ;
    sh:class wikidash:Human ;
    sh:maxCount 1 ;
    sh:name "wikidata person" ;
    sh:nodeKind sh:IRI ;
    sh:group shess:AdditionalInformationPropertyGroup ;
    sh:order "0"^^xsd:decimal .

shess:HumanPlayer-dateOfBirth
    a sh:PropertyShape ;
    sh:path ( shess:wikidataPerson wdt:P569 ) ;
    sh:maxCount 1 ;
    sh:name "date of birth" ;
    sh:or (
        [ sh:datatype xsd:date ]
        [ sh:datatype xsd:dateTime ]
    ) ;
    sh:group shess:AdditionalInformationPropertyGroup ;
    sh:order "1"^^xsd:decimal .

shess:HumanPlayer-depiction
    a sh:PropertyShape ;
    sh:path ( shess:wikidataPerson wdt:P18 ) ;
    dash:propertyRole dash:DepictionRole ;
    sh:maxCount 1 ;
    sh:name "depiction" ;
    sh:nodeKind sh:IRI ;
    sh:group shess:AdditionalInformationPropertyGroup ;
    sh:order "2"^^xsd:decimal .

shess:AdditionalInformationPropertyGroup
    a sh:PropertyGroup ;
    rdfs:label "Additional Information" ;
    sh:order "2"^^xsd:decimal .