Home > How-to configure Sparnatural in SHACL
You can also read the PDF version of this guide.
Make sure you have followed the “Hello Sparnatural setup tutorial” before learning the configuration options. The files related to this tutorial can be downloaded from the same directory in the source.
How-to configure Sparnatural in SHACL
date: 2024-09
Sparnatural version: 9.5.0
Structure of the example ontology 5
Setup the configuration spreadsheet 6
How-to use the spreadsheet and the Excel-2-RDF converter 6
Setup for a Google spreadsheet 7
Setup for a local spreadsheet 8
Declare properties and entities 9
Adjust the configuration URI and the prefixes 9
Configure value selection widgets 15
Disable optional or negative queries on some properties 17
Hide properties or entities 20
Datasources : populate lists and autocomplete fields 21
Indicate the default label property for each entity 21
Default datasource behavior 22
Use a predefined query with your own property 26
Create datasources from custom SPARQL 28
Map properties to the underlying knowledge graph 32
Query a sequence of properties (using a shortcut) 32
Query multiple properties in a single criteria 35
Query a property recursively 37
Map classes to the underlying knowledge graph 38
Entities without any mapping / targets 40
Create a multilingual configuration 41
Multilingual labels and tooltips 41
Multilingual default label properties 42
Create a hierarchical configuration 43
Display labels in the result table 45
Advanced configuration : create custom SPARQL datasources 47
Advanced configuration : debug custom datasources 49
Advanced configuration : setup tree widget datasource 51
Annex : View the Sparnatural configuration in SHACL Play 53
Annex : Generate SHACL automatically from an RDF Knowledge Graph 55
Introduction
Welcome to this guide on how to configure Sparnatural !
The Sparnatural SHACL configuration reference documentation lists the available annotations and axioms available to configure Sparnatural. In this documentation you will learn how to use these annotations concretely in an Excel spreadsheet to define the entities, properties, widgets and datasources in order to make your Sparnatural explorer as appealing as possible for your users.
Conventions
URIs are indicated like this.
Headers in the spreadsheet are indicated like this.
Important : this is an important note, pay attention !
Advanced note: this is explaining something advanced. Don’t worry if you don’t understand all the details at first.
Tip: this is a useful and practical tip.
Prerequisites
Make sure you have followed the introductory “Hello Sparnatural” guide to setup your environment to point Sparnatural to your triplestore and adjust the browser security settings.
You must have a local spreadsheet editor, like Microsoft Excel, or use Google spreadsheet
Although not absolutely required, it is good if you have a basic understanding of SHACL specifications[1]. To go further with SHACL, you will also discover in annex of this manual how you can generate a documentation based on your Sparnatural SHACL configuration
For configuring your own datasource queries, you need to be proficient with SPARQL. This is described in annex.
Documentation files
This guide comes with a set of files that you should have ready. Click on the links to download them:
car.ttl : a sample OWL ontology describing car diagnostics.
car_instances.ttl : a few manually crafted instances of the sample ontology. Although not strictly required, you should load these instances into your triplestore if you want to follow along and test the example configuration against the dataset.
sparnatural-car-configuration-shacl.xlsx : the example Sparnatural Excel config file
sparnatural-car-configuration.ttl : the result of converting the Excel config file with the Excel-2-RDF converter (explanations below). This is the actual Sparnatural configuration file to pass in the “src” attribute of the sparnatural HTML element, if you want to test it to see the final result (but this is not required to follow this documentation).
Structure of the example ontology
For the purpose of this documentation we will use an example ontology, defined in the file car.ttl, and described in the following diagram:
This is a simplistic representation of “On-board diagnostic” systems of cars : Vehicles, identified by their Vehicle Identification Number (VIN) have a Manufacturer; Diagnosis (“Diagnostics”) are made on given vehicles at a certain date and a certain place, and can yield Errors. An Error has a code, and a flag indicating if the error was already detected on the same vehicle. Error codes are associated with Symptoms (“Engine Misfire” or "Transmission Slipping") and Components (“Engine”, “Transmission”, “Brakes”). Components are hierarchically organized.
The ontology uses the prefix “odb” associated with the URI http://example.com/ontology/odb#.
Disclaimer : this “car” ontology sample is a fictitious one, which has only been created for the purpose of testing maximum Sparnatural different functionalities. This ontology is not suitable for a real car diagnostic industrial context !
Setup the configuration spreadsheet
How-to use the spreadsheet and the Excel-2-RDF converter
Sparnatural can be configured by a SHACL specification, and the “Hello Sparnatural” guide explains how to use a simple Excel spreadsheet to start creating a SHACL config for Sparnatural.
The configuration spreadsheet can be edited in a local file or in an online (Google) spreadsheet. Both options are described below. Whether local or online, the conversion of the spreadsheet into SHACL requires a conversion using the Excel-2-RDF converter before it can be read by Sparnatural :
The code of the Excel-2-RDF converter is open-sourced in the xls2rdf Github repository. The Excel-2-RDF converter is available in different packagings:
an online form where you can upload your file
a Java library file to be integrated into your application
All these “packagings” behave the same way for the conversion of the spreadsheet in RDF. For the purpose of following this documentation, we suggest either using an online Google spreadsheet and rely on the online conversion service, or simply use a local file and upload it through the online form, and save the resulting SHACL file.
The detailed behaviour of the Excel-to-RDF converter as to how the Excel file is interpreted is out of scope of this guide, and is documented in the online converter service.
Setup for a Google spreadsheet
Using a Google spreadsheet has the following advantages:
The configuration is “live” : while in the test phase, you can edit your spreadsheet, refresh your Sparnatural HTML page, and it will be updated automatically.
Multiple persons can collaborate on the same configuration.
To initialize your configuration spreadsheet:
Make a copy of the configuration template
Your spreadsheet needs to be publicly visible. You need to share it with the "Anyone with the link = Viewer" option. To do this, select the option Share.
In the next window, click the "General access" button. Select the "Anyone with the link" option and press the "Done" button.
After you close the window, copy the URL of the spreadsheet in your browser's address bar.
Copy this URL in the cell B2 of the configuration file. Make sure the URL does not end with “/edit#gid=xxxxxxx”, remove this part of the URL manually. The URL should look like https://docs.google.com/spreadsheets/d/xxxxxxxxxx”
Save the content of cell B3 (in red) : this is the configuration URL that you can pass to the “src” attribute of the <spar-natural> HTML element. You see it starts with https://xls2rdf.sparna.fr : this is the online Excel-2-RDF conversion service that takes the Google spreadsheet URL as a parameter. Each time your Sparnatural page will load, it will call this URL of the converter, which will in turn trigger the conversion of the Google spreadsheet. The page is connected “live” to the spreadsheet.
Important : once your configuration is ready, do NOT leave Sparnatural pointing to the live spreadsheet, otherwise your page will depend on the availability of the online converter. Instead, save the result of the conversion to a local file “sparnatural-config.ttl”, and adjust the “src” attribute of the <spar-natural> HTML element to point to the local file.
Setup for a local spreadsheet
Relying on Google services might not be applicable in every context. It is also possible to design the configuration in a local spreadsheet, and convert it to a SHACL file. The configuration is not live in that case, and you will have to reconvert the file every time you make a change in it.
To start a fresh configuration template:
Download the configuration spreadsheet template.
Edit the content as necessary
Go to the online converter at https://skos-play.sparna.fr/play/convert
Upload the file in the field “in a local file on my computer”:
Check the box “Ignore SKOS post-processings on the data”:
Click on Convert.
Save the resulting file in the same folder as your Sparnatural page.
Adjust the “src” attribute of the <spar-natural> HTML element to point to this local file.
Reconvert the file the same way every time you make a change in it.
Declare properties and entities
In this documentation we will work with a local spreadsheet. Download the spreadsheet configuration template and save it in a local file. You will be working on this local file.
Each column header corresponds to one configuration property as detailed in the SHACL configuration reference page. The header line does not need to be at a fixed line; it is automagically detected, so don’t worry if you add or delete lines before this one.
|
|
Adjust the configuration URI and the prefixes
You first need to adjust the URI of your configuration, as well as enter the prefixes used in your knowledge graph. The prefixes will be used in the rest of the configuration.
Configuration IRI
Make sure you are on the “Entities” tab of the configuration template, and edit the content of cell B1. This cell needs to contain the URI of your configuration. It is not very important, unless you plan to share your configuration later. It is typically set to something like “https://data.mydomain.com/sparnatural-config” or to a URL where Sparnatural will be deployed, like “https://mydomain.com/sparnatural-page/sparnatural-config”.
Metadata cleanup
Cells B2 and B3 are only useful when working with online Google spreadsheets, so that the configuration is converted and refreshed everytime the Sparnatural page is reloaded. We don’t need that in a local file, so simply delete the content of cells B2 and B3. Keep them if you work with a Google spreadsheet.
Prefixes
You need to add additional prefixes from your configuration. Some prefixes are already declared in the “Prefixes” tab. Leave them as they are there, and add additional prefixes if necessary, by adding new lines. The column A always needs to contain the keyword PREFIX, column B is the prefix name, and column C is the complete URI associated with the prefix.
Important : Note also that a special prefix, “this” is declared in the “Entities” tab. It is set automatically from the Configuration IRI in cell B1. Leave it as it is. It is a special prefix that you will use to declare your entities and properties.
Example
Following the above, in our example configuration we set the configuration IRI to https://data.mydomain.com/ontologies/sparnatural-config, delete the content of cells B2 and B3 in the “Entities” tab, and in the “Prefixes” tab, add our prefix “odb” on line 8, corresponding to the URI http://example.com/ontology/odb#
|
Declare simple entities
You need to declare the entities that will be listed in the selector for the subject as well as for the object of each query criteria. Don’t hesitate to read the guidelines in the green line above the body of the table to get additional information about the content of each columns. This are the basic columns you need to fill in:
always use the "this" prefix in the "URI" column to give a meaningful identifier to your entity. You will refer to this identifier later when configuring properties.
in the sh:targetClass column, enter the URI of the corresponding class from your knowledge graph ontology.
in column sh:order^^xsd:integer set the display order of the entity to sort the items in Sparnatural’s interface. The value must be an integer.
the volipi:iconName column is where you can copy-paste the code of a Font Awesome free icon you will choose on the website (e.g. “fa-solid fa-car”).
in the rdf:type column set sh:NodeShape as the value for every entity ; this is a fixed value that never changes.
In the sh:nodeKind column, always set sh:IRI (except when dealing with literal values, see below).
then add the label of the entity, in the rdfs:label@xx column (this is the label that will appear in the user interface).
Advanced note: You can change the language of the label by editing the header row. By default the template enables labels in English (rdfs:label@en), and French (rdfs:label@fr). You can adjust the language code after the “@” sign. All the labels in a given column will be tagged with this language. Make sure the language you use matches the “lang” parameter of Sparnatural in your web page. More on this in the section about multilingual configuration.
if you need some, you can also add tooltips in the sh:description@en column. This is not mandatory. Depending on the use-case, the tooltip may provide more contextual information to the user than only the definition from the ontology (e.g. “Select this entry if you want to search on xxx or yyyy”).
Similar to labels, you can adjust the language code of the tooltips by editing the language code after the “@” symbol in the header line.
Tip: HTML markup is supported in tooltips.
Tip: By using the labels combined with the order, you can group your Entities in a meaningful way, for example by setting a label that contains a hierarchy, such as “Actor > Person” and “Actor > Organization”, and setting those 2 classes next to each other with their order.
Example
Here in the example we have chosen to list all the existing Entities of the model (you could choose to have only some classes of your model, and not all). We took the same URIs as the ones in the data model and added order, icons, labels and tooltips :
Note also that, at the end of the list, we have a few lines that don’t correspond to classes from the ontology, but are entities that correspond to literal values : this:TrueFalse or this:Search. More on this later.
We decided that “Vehicle” was an important entry point and set its order to 1. Following this, we can see it appears first in the query builder :
Note how the tooltip displays the definition from the configuration. |
Declare simple properties
Now you need to declare the properties that link together the entities from your configuration. For this, move to the “Properties” tab of the spreadsheet.
Tip: We suggest you organize the “Properties” table by sections, each section corresponding to the specification of the properties attached to one given entity in your configuration. Make a colored line for each section, with the name of the entity as the title. In general you are free to arrange the spreadsheet as you want and use any formatting/color option you want. Lines that do no contain a URI in column A will be ignored.
In this tab you need to enter:
URI column : The URI of the configuration property. This should not be confused with the URI of the property itself. We suggest to use the following syntax for the identifier:
the « this » prefix from your configuration ;
then concatenate the entity local name from column ^sh:property ;
add an underscore for better readability ;
and finally the property local name from your ontology from the sh:path column
Which gives us for example : this:Vehicle_VIN.
the sh:path column is for the actual URI of the property from your ontology, using your ontology namespace, for example odb:VIN.
the ^sh:property column contains the entity URI to which the property is assigned (the « subject » of an RDF predicate). It is a reference to one of the Entities URI from the Entities tab, using the « this » prefix.
in the sh:name@en column set the label of the property to be shown in the interface.
adjust the language code of the labels by editing the language code after the “@” symbol in the header line.
if needed you can add a tooltip in the sh:description@en column ;
adjust the language code of the tooltips by editing the language code after the “@” symbol in the header line.
the sh:node column contains the identifier of a Sparnatural entity to which the property points to (the “object” of an RDF predicate). This is the identifier of an entity from the first tab;
Advanced note: Sparnatural can also read sh:class SHACL constraints that point to a class that is itself the sh:targetClass of an entity in the config
the dash:searchWidget column is used to configure the way the values can be selected in the query builder (see “widget” section below) : when you start designing your configuration we suggest using core:ListProperty to obtain simple populated lists using the data ; you can then refine this to other more appropriate values after.
Advanced note: it is possible that a single property has more than one entity as its domain. You can specify more than one entity identifier in the ^sh:property column, by separating them with a comma.
Advanced note: min and max cardinalities (sh:minCount and sh:maxCount) are currently not used by Sparnatural. However they are an important part of any SHACL specification, and they could by used by Sparnatural in the future. Hence they are included in the configuration template columns.
Example
Note how the table is organized with one section per entity; note also how each property refers to the entity to which it is attached in the ^sh:property column (in each “section” the ^sh:property is always the same), and the entity to which it refers to in the sh:node column, for most of them.
As a result we can see - when index.html is refreshed - the object properties in italic appear in the interface, between the Entities items :
The tooltip of the property is displayed if it was added before in the configuration file.
We see a dropdown list appears when the range of the query (i.e. the “object” entity of the assertion) is chosen. As explained before, the way the selected values are to be displayed depends on the type (dash:searchWidget) of the property, also referred to as the “widget” of the property.
|
Configure value selection widgets
Each property needs to be associated with a value selection widget (although Sparnatural has some default behavior is none is indicated, we recommend to always set it explicitely). The value selection is how the user will enter a search value for this criteria.
To set a value selection widget, enter one of the following predefined values in the dash:searchWidget column.
Widget type (dash:searchWidget) | Description |
core:ListProperty | dropdown list widget, useful for list of values < 500 |
core:AutocompleteProperty | autocomplete search field, useful when the list of values is larger |
core:TreeProperty | tree browsing widget, useful with some tree-shaped values, typically SKOS hierarchies, part-of hierarchies, etc; |
core:MapProperty | map selection widget (GeoSPARQL queries) |
core:SearchProperty, core:StringEqualsProperty, core:GraphDBSearchProperty | string search widget, searched as regex or as exact string |
core:TimeProperty-Date, core:TimeProperty-Year | date range widget (date or year precision) |
core:BooleanProperty | boolean widget (true/false, yes/no values…) |
core:NonSelectableProperty | no value selection (useful for 'intermediate' Entities whose values don’t need to be displayed) |
core:NumberProperty | Numeric range widget |
All of them are already fully documented in the reference documentation for Sparnatural widgets.
The choice of the widget is driven by how we want the user to select a value, and how many different values are available (e.g. lists are good only when the values are relatively small, typically less than 500 distinct values).
Tip: lists and autocomplete can work for both object properties (having IRIs as their values) and datatype properties (having literals as their values).
Example
Note how the properties in our configuration use different kinds of widgets:
|