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

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:

LabelExplanationPropertyType
NameDescribes the name of the form itselfshacl:nameString
Tab NameDescribes the name of the tab of the form in resource viewshui:tabNameString
Target classThe rdf:type of resources the form applies toshacl:targetClassowl:Class
PropertyA number of PropertyShape resources defining fields of the formshacl:propertyshacl:PropertyShape

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

LabelExplanationPropertyType
tab nameThe name to be used when presenting a user interface based on this node shape in a tab.shui:tabNameString
on update update

Links a SPARQL 1.1 Update to this node shape which should be executed when any statement of the shaped node is modified (information added, removed or modified).

It accepts the following placeholders:

  • {{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)
  • {{shuiGraph}} - the currently used graph.
shui:onUpdateUpdateshui:SparqlQuery
navigation list queryThis property links the node shape to a SPARQL 1.1 Query in order to provide a sophisticated user navigation list query e.g. to add specific additional columns (this is similar to activeColumn). The query should use {{FROM}} as a placeholder for the FROM section.shui:navigationListQueryshui:SparqlQuery

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:

LabelExplanationPropertyType
NameThe name of the field. It can be multiple for different languages.shacl:namelangString
DescriptionThe description of the field shown as tooltip on the question mark icon next to the field. It can be multiple for different languages.shacl:descriptionlangString
DatatypeThe datatype of the property.shacl:datatypeDatatype IRI, eg.g rdfs:Datatype
PathThe property the field representsshacl:pathrdf:Property
orderThe position of the field in the form.shacl:orderInteger
min countThe minimum cardinality of the field.shacl:minCountInteger
max countThe maximum cardinality of the field. No value is interpreted unlimited.shacl:maxCountInteger
ClassIn case the Path of the field is an ObjectProperty, this field defines the Class of objects linked by the Path.shacl:classowl:Class
NodeA NodeShape that is displayed with all its fields as a sub-form.shacl:nodeshacl:NodeShape
Node KindThe kind of the field, either IRIs or Literal. Used to define field content widget.shacl:nodeKindshacl:IRI / shacl:Literal
Group

Indicate that the shape belongs to a group of related property shapes which are grouped in the user interface. For each group, rdfs:label and a shacl:order need to be given.

shacl:groupshacl:PropertyGroup
Pattern (regex)An XPath regular expression (Perl like) that all value nodes need to match.shacl:patternString
Flags (regex)An optional string of flags for the regular expression pattern (e.g. 'i' for case-insensitive mode)shacl:flagsString

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

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

LabelExplanationPropertyType
inverse pathUse if the property should be an incoming link. The subject of the created triple will not be the resource the field is found in, but the one entered as field value, practically inverting the statement. Optional.shui:inversePathBoolean
Show alwaysThe annotated shape is always shown to the user (even if its optional only).shui:showAlwaysBoolean
read onlyPrevent the field from being edited.shui:readOnlyBoolean
Deny new resourcesPrevents the user from creating new resources. Affects property shapes of sh:nodeKind IRI only.shui:denyNewResourcesBoolean
Active ColumnWhen listing resources, the annotated shape is used to show an additional column which is visible per default.shui:activeColumnBoolean
ignore on copyThe shaped values will be ignored when the shaped resource is copied.shui:ignoreOnCopyBoolean
Use textareaEnables multiline editing capabilities of Literals.shui:textareaBoolean
UI queryIn addition to sh:class and other validation, this links a SPARQL 1.1 Query to this property shape in order to provide a sophisticated user interface query e.g. to return specific labels and descriptions. 

It accepts the following placeholders:

  • {{shuiMainResource}}: The resource that is being edited.
  • {{shuiResource}}: The resource to which a subproperty belongs, in case of a nested shape. Otherwise has the same value than shuiMainResource.
  • {{shuiGraph}}: The graph containing the values.
shui:uiQueryshui:SparqlQuery
on insert update

Links a SPARQL 1.1 Update to this property shape which should be executed when a statement matched by this property shape is inserted.

The following placeholders can be used:

  • {{shuiMainResource}}: The resource that is being edited.
  • {{shuiResource}}: The resource to which a subproperty belongs, in case of a nested shape. Otherwise has the same value than shuiMainResource.
  • {{shuiProperty}}: The path to the object value.
  • {{shuiObject}}: The value of the property.
  • {{shuiGraph}}: The graph containing the values.
shui:onInsertUpdateshui:SparqlQuery
on delete update

Links a SPARQL 1.1 Update to this property shape which should be executed when a statement matched by this property shape is deleted.

The following placeholders can be used:

  • {{shuiMainResource}}: The resource that is being edited.
  • {{shuiResource}}: The resource to which a subproperty belongs, in case of a nested shape. Otherwise has the same value than shuiMainResource.
  • {{shuiProperty}}: The path to the object value.
  • {{shuiObject}}: The value of the property.
  • {{shuiGraph}}: The graph containing the values.
shui:onDeleteUpdateshui:SparqlQuery
value query

(Beta) Use this relation to provide a tabular read-only report of a custom SPARQL 1.1 Query at the place where this property shape is used in the user interface. It accepts the following placeholders:

  • {{shuiMainResource}}: The resource that is being edited.
  • {{shuiResource}}: The resource to which a subproperty belongs, in case of a nested shape. Otherwise has the same value than shuiMainResource.
  • {{shuiGraph}}: The graph containing the values.
shui:valueQueryshui:SparqlQuery

Since they represent URIs, all the placeholders (except shuiObject in case that the PropertyShape is not IRI) need to be wrapped by < and > to work properly for all SPARQL 1.1 Update 

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.