Introduction

Working with shapes allows for creation of a customized Linked Data user interface.In addition to the standard PROPERTIES tab that shows all properties of a data resource, you can create custom “form”-like data interfaces. These configurable forms allow for a cleaner interface to view and author data resources. In addition, they enable integration of data from other resources that are linked to the current resource, creating a more concise view on your data.

Defining forms

You can define forms using SHACL rules. The rules state:

  1. What types of resources the form definition applies to. This is based on the rdf:type of a resource.
  2. What fields are shown in the form in which order. Field contents are retrieved from properties connected to the resource.
  3. Which other, linked resources are shown in the form. Linked resources can either be shown as links or as their full form.
  4. Which texts are used to name and describe fields, as well as the tab in the user interface.

Forms are defined in the CMEM Shapes Catalog graph. The graph URI is https://vocab.eccenca.com/shacl/.

Form definitions are twofold:

  1. The form itself is defined as so called NodeShape. NodeShapes define which types of resources the form applies to (the target class), the name of the tab in the interface (the Tab Name), and which fields are shown in the form (the Properties).
  2. The individual fields are defined as so called PropertyShape. PropertyShapes define which property is used to retrieve data for the field (the Path), the name of the field, a description, its cardinality (min and max count), its position in the form (the Order), and if it should always be shown. In case of object properties, it also defines the type of the linked resource (the class). The full list of features is described in Building a customized User Interface.

To define a new form, for example for foaf:Person resources, navigate to the CMEM Shapes Catalog graph and select NodeShape in Navigation. The list of existing NodeShapes is shown. Click  in the lower right to create a new NodeShape. Enter a name of the resource. An empty NodeShape resource is created and shown.

Create a new NodeShape

To create the initial definition, click  (Edit). A form is shown to you with input fields Name, Property, Target class and Tab name. The initial definition requires the name, the tab name and the target class. Fields themselves are attached to the form later. Target class in particular binds the form to the resources it should cover. The Target class field features an auto-complete that displays all classes stored in Corporate Memory. The example form should cover resources of type foaf:Person resources, so enter foaf:Person in the Target class field. Click SAVE to save the NodeShape.

Edit view for NodeShapes

You have now created an “empty” form that covers foaf:Person resources with tab name “Person”. Navigating to a foaf:Person resource, you see a new tab as defined. You can still see all properties of the resource in the PROPERTIES tab.

Empty Resource View

To define new fields, for example showing the email address of the person (defined as foaf:mbox), navigate to the CMEM Shapes Catalog graph and select PropertyShape in Navigation. The list of existing PropertyShapes is shown. Click CREATE NEW PROPERTYSHAPE in the upper right to create a new PropertyShape. Enter a name of the resource. An empty PropertyShape resource is created and shown.

Edit the form using . A form is shown with all relevant properties of a field definition. Required in this step are:

  1. The name of the field, which will be displayed left of the data content or input field in the form.
  2. The description, which will be displayed as tooltip on the question mark to the right of the name.
  3. The path, which states which property the field represents. In this example, it is foaf:mbox.
  4. The form the field should be shown in (Property of). The field provides an auto-complete, so just enter “Person” and select the NodeShape resource you defined in the previous step.

Click SAVE after filling out the required fields.

Edit view for PropertyShapes

You have now created a field named “Email” that displays the content of the foaf:mbox property. Navigating to a foaf:Person resource, you see a new field “Email” in the Person tab.

Resource list filled

NodeShapes

Node Shapes are resources of type shacl:NodeShape. They are used to define custom forms attached to resources of a specific type. The following NodeShape properties are supported:

In addition to these properties, the following non-standard properties from the eccenca SHACL UI extension are supported on Node Shapes:

Naming and Presentation

In this group, presentation and naming properties are collected. Most of the properties are straight forward to use.

Name

The name of the node is presented to the user only when he needs to distinguish between different shapes for the same resource.

Used Path: shacl:name

Description

The node description should provide context information for the user when creating a new resource based on this node.

Used Path: rdfs:comment

Tab Name (deprecated)

Name of the tab (deprecated, only interpreted until 20.06)

Used Path: shui:tabName

Navigation list query

This property links the node shape to a SPARQL 1.1 Select Query in order to provide a sophisticated user navigation list query e.g. to add specific additional columns.

Used Path: shui:navigationListQuery

Vocabulary

In this group, the affected vocabulary classes as well as the used property shapes are managed.

Property

Properties of this node

Used Path: shacl:property

Target class

Class this NodeShape applies to.

Used Path: shacl:targetClass

Processing

In this group, all shape properties are managed, have an effect on how new or existing resources are processed or created.

URI template

A compact sequence of characters for describing a range of URIs through variable expansion.

Used Path: shui:uriTemplate

Target Graph Template

Graph templates can be used to enforce writing statement in specific graphs rather than into the selected graph. Graph templates can be added to node and property shapes. A template on a property shape is used only for overwriting a template on a node shape (without a node shape graph template, they do not have an effect).

Used Path: shui:targetGraphTemplate

On update update

A query executed when any value of the resource is added, changed or removed.

Used Path: shui:onUpdateUpdate

Statement Annotation

Statement Annotations provide a way to express knowledge about statements. This group is dedicated to properties which configure the Statement Annotation feature.

Enable

A value of true enables visualisation and management capabilities of statement annotations (reification) for all statements which are shown via this shape.

Used Path: shui:enableStatementLevelMetadata

Provide as Shape

A value of true enables this node shape to be applied as statement annotation (reification).

Used Path: shui:isApplicableAsStatementLevelMetadata

PropertyShapes

Property Shapes are resources of type shacl:PropertyShape. They are used to specify constraints and UI options that need to be met in the context of a Node Shape. The following Property Shape properties of SHACL are supported:

Name and Description are displayed using the configuration of titleHelper. See Deploy and Configure → Configuration → DataManager for more details.


Naming and Presentation

In this group, presentation and naming properties are collected. Most of the properties are straight forward to use, other properties provide more complex features, such as table reports.

Name

This name will be shown to the user.

Used Path: shacl:name

Description

This text will be shown to the user in a tooltip. You can use new and blank lines for basic text structuring.

Used Path: shacl:description

Query: Table Report

Use this property to provide a tabular read-only report of a custom SPARQL query at the place where this property shape is used in the user interface. The following placeholder can be used in the query text of the sparql query: {{shuiMainResource}} - refers to the main resource rendered in the starte node shape of the currently displayed node shape tree (only relevant in case of sub-shape usage) ; {{shuiResource}} - refers to the resource which is rendered in the node shape where this property shape is used (maybe a sub-shape) ; {{shuiGraph}} - the currently used graph.

Used Path: shui:valueQuery

Query: Table Report (hide header)

If set to true, the report table will be rendered without header (in case you expect only a single value).

Used Path: shui:valueQueryHideHeader

Query: Table Report (hide footer)

If set to true, the report table will be rendered without footer (in case you expect only a single value or row).

Used Path: shui:valueQueryHideFooter

Order

Specifies the order of the property in the UI. Ordering is separate for each group.

Used Path: shacl:order

Group

Group to which the property belongs to.

Used Path: shacl:group

Show always

Default is false. A value of true let optional properties (min count = 0) show up by default.

Used Path: shui:showAlways

Read only

Default is false. A value of true means the properties are not editable by the user. Useful for displaying system properties.

Used Path: shui:readOnly

Vocabulary

In this group, property paths as well cardinality restrictions are managed.

Property of

The node shape this property shape belongs to.

Used Path: shacl:property

Path

The datatype or object property used in this shape.

Used Path: shacl:path

Node kind

Type of the node.

Used Path: shacl:nodeKind

Min count

Min cardinality, 0 will show this property under optionals unless 'Show always = true'

Used Path: shacl:minCount

Max count

Max cardinality

Used Path: shacl:maxCount

Datatype Property Specific

In this group, all shape properties are managed, which only have effects on datatype properties.

Datatype

The datatype of the property.

Used Path: shacl:datatype

Use textarea

Default is false. A value of true enables multiline editing capabilities for Literals via a textarea widget.

Used Path: shui:textarea

Regex Pattern

A XPath regular expression (Perl like) that all literal strings need to match.

Used Path: shacl:pattern

Regex Flags

An optional string of flags for the regular expression pattern (e.g. 'i' for case-insensitive mode)

Used Path: shacl:flags

Languages allowed

This limits the given Literals to a list of languages. This property works only in combination with the datatype rdf:langString. Note that the expression for this property only allows for '2 Char ISO-639-1-Codes' only (no sub-tags).

Used Path: shui:languageIn

Languages Unique

Default is false. A value of true enforces that no pair of Literals may use the same language tag.

Used Path: shacl:uniqueLang

Object Property Specific

In this group, all shape properties are managed, which only have effects on object properties.

Class

Class of the connected IRI if nodeKind == sh:IRI.

Used Path: shacl:class

Query: Selectable Resources

This query allows for listing selectable resources in the dropdown list for this property shape.

Used Path: shui:uiQuery

Inverse Path

Default is false. A value of true inverts the expected / created direction of a relation.

Used Path: shui:inversePath

Deny new resources

A value of true disables the option to create new resources.

Used Path: shui:denyNewResources

Node shape

The shape of the linked resource.

Used Path: shacl:node

Processing

In this group, all shape properties are managed, have an effect on how new or existing resources are processed or created.

URI template

A compact sequence of characters for describing a range of URIs through variable expansion.

Used Path: shui:uriTemplate

Ignore on copy

Disables reusing the value(s) when creating a copy of the resource.

Used Path: shui:ignoreOnCopy

Query: On insert update

This query is executed when a property value is added or changed.

The following placeholder can be used in the query text of the sparql query: {{shuiMainResource}} - refers to the main resource rendered in the start node shape of the currently displayed node shape tree (only relevant in case of sub-shape usage) ; {{shuiResource}} - refers to the resource which is rendered in the node shape where this property shape is used (maybe a sub-shape) ; {{shuiGraph}} - the currently used graph.

Used Path: shui:onInsertUpdate

Query: On delete update

This query is executed when a value is changed or removed.

The following placeholder can be used in the query text of the sparql query: {{shuiMainResource}} - refers to the main resource rendered in the start node shape of the currently displayed node shape tree (only relevant in case of sub-shape usage) ; {{shuiResource}} - refers to the resource which is rendered in the node shape where this property shape is used (maybe a sub-shape) ; {{shuiGraph}} - the currently used graph.

Used Path: shui:onDeleteUpdate

Target Graph Template

Graph templates can be used to enforce writing statement in specific graphs rather than into the selected graph. Graph templates can be added to node and property shapes. A template on a property shape is used only for overwriting a template on a node shape (without a node shape graph template, they do not have an effect).

Used Path: shui:targetGraphTemplate

Statement Annotation

Statement Annotations provide a way to express knowledge about statements. This group is dedicated to properties which configure the Statement Annotation feature.

Enable

A value of true enables visualisation and management capabilities of statement annotations (reification) for all statements which are shown via this shape.

Used Path: shui:enableStatementLevelMetadata

Provided Shapes

Instead of providing all possible statement annotation node shapes for the creation of new statement annotations, this property will limit the list to the selected shapes only.

Used Path: shui:provideStatementLevelMetadataShapes

Using forms

Once a Node Shape is created for a specific class, you are able to use the specified entry form in the Explore component of Corporate Memory.

Editing existing resources

While browsing your knowledge graph, you will always see your shape in action, when you click on a resource which is an instance of the class which is linked with shacl:targetClass from your Node Shape.

The next images demonstrate this behaviour:

Node Shape definition for instances of the SPARQL Query Class (exists in the Shape Catalog)

Instance of the class SPARQL Query (exists in the Query Catalog)

Creating new resources

You can also create new resources by using a shaped form. One way to achieve this, is to select the class in the navigation tree on the lower left part in the Explore component and then click the Floating Action Button at the bottom or use the context menu on upper right side.

The next images demonstrate this behaviour:

Use the context menu, then Create ..., or the FAB button to create a new resource.

New resources are created with the same shape-defined form, but as a popup-window.