The Sparnatural OWL 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 and define the classes, 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.
You need to have a basic understanding of OWL ontologies.
For configuring your own datasource queries, you need to be proficient with SPARQL. This is described in annex.

In addition, you can have the Protégé OWL editor installed, only if you want to browse the ontology in Protégé, but this is not a requirement.

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.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. 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 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; 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 might not be fully exact nor complete in a real car diagnostic industrial context ! [1]

Configuration spreadsheet

Protégé vs. spreadsheet

Sparnatural can be configured by an OWL ontology, and the “Hello Sparnatural” guide explains how to use the Protégé OWL editor to start creating an OWL config ontology for Sparnatural.

Although configuration in Protégé offers navigation and edition UI in trees of classes and properties, and although semantic web practitioners are familiar with it, we must admit it ain’t the fastest editing solution 😊

No worries then ! Spreadsheet configuration we present in this document is faster and easier to go and the result is the same : an OWL file that Sparnatural can read. The config can even be edited live in case of online spreadsheets !

When using Protégé, you directly edit an OWL file:

The conversion of the spreadsheet into OWL relies on a generic Excel-to-RDF converter. While when using a spreadsheet, the Excel-2-RDF converter is used:

The Excel-2-RDF converter

The code of the converter is open-sourced in the xls2rdf Github repository. The Excel-2-RDF converter is available in different packagings:

an online REST service
an online form where you can upload your file
a command-line converter with its documentation
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 OWL file.

The detailed behavior 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.

If you use 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 config spreadsheet.

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.

If you use 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 an OWL 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.

Filling-in the configuration spreadsheet

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.

Important : throughout this documentation, we are referring to the columns of the spreadsheet by their header name. The header is the green line in bold:

Each column header corresponds to one configuration property as detailed in the Sparnatural OWL configuration reference documentation. 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.

Adjusting the ontology URI and the prefixes

You first need to adjust the URI of your ontology, as well as enter the prefixes used in your knowledge graph.

Ontology IRI

Make sure you are on the “classes” tab of the configuration template, and edit the content of cell B1. This cell needs to contain the URI of your configuration ontology. 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 can be automated. 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 ontology. Some prefixes are already declared : “this”, “core” and “datasources”. Leave them as they are, and add prefixes in the same way in the lines below. 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.

Don’t hesitate to add new lines if you need to add many prefixes.

Example

Following the above, in our example configuration we set the Ontology IRI to http://example.com/sparnatural-page/sparnatural-config, delete the content of cells B2 and B3, and add our prefix “odb” on line 10, corresponding to the URI http://example.com/ontology/odb#

Declaring classes

Now you can start filling in the table with the classes of your ontology. Don’t hesitate to read the guidelines in the green line above the body of the table.

use the prefix you declared first to write down the URIs you have in the URI column ;
then in the rdf:type column set owl:Class as the value of all your classes items ;
set all your classes as core:SparnaturalClass in the column rdfs:subClassOf.
then add the label of your classes, in the rdfs:label@xx column (these will appear as the coloured named “blocks” in the query builder).

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 webpage. More on this in the section about multilingual configuration.

Next two columns allows to customize the display of the classes in the query builder :

the core:faIcon (as for “FontAwesome icon”) 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”) ;
if you need some, you can also add tooltips in the core:tooltip@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.

In column core:order^^xsd:integer set the display order of each entry to sort the items in Sparnatural’s interface. The value must be an integer.

Tip: By using the labels combined with the order, you can group your classes 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 classes 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 labels, icons, tooltips and order :

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

Declaring properties

Same process then to set the relations between the classes : jump to the “Properties” tab, 2nd of the spreadsheet.

Tip: We suggest you organize this table by sections, each section corresponding to the specification of the properties attached to one given class in your configuration. Make a colored line for each section, with the name of the class as the title. Generally 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 will enter:

URI column : URI of your property, typically using a prefix from your ontology ;
in the rdf:type column always set the value to owl:ObjectProperty ;

Advanced note: even when configuring properties that actually correspond to datatype properties, you always have to use owl:ObjectProperty, as for Sparnatural the property needs to have a domain and a range that are classes.

in the “rdfs:label@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.
the rdfs:subPropertyOf 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.
if needed a tooltip in the core:tooltip@en column ;
adjust the language code of the tooltips by editing the language code after the “@” symbol in the header line.

And in order to relate each property to its domain class and its range class:

the rdfs:domain is the Class to which the property is assigned (as the “subject” of the assertion in an RDF graph) ;
the rdfs:range is the Sparnatural Class to which the property points to (the “object” of an RDF predicate);

These 2 columns must refer to a URI of a class from the first tab of your configuration spreadsheet.

Advanced note: it is possible that a single property has more than one class as its domain or its range. You can specify more than one class identifier in the rdfs:domain or rdfs:range column, by separating them with a comma.

Example

Note how the table is organized with one section per class; note also how each property refers to the class to which it is attached in the rdfs:domain column (in each “section” the rdfs:domain is always the same), and the class to which it refers to in the rdfs:range column.

As a result we can see - when index.html is refreshed - the object properties in italic appear in the interface, between the classes 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” class of the assertion) is chosen. As explained before, the way the selected values are to be displayed depends on the type (rdfs:subPropertyOf) of the property, also referred to as the “widget” of the property.

Selecting property types (widgets)

For now Sparnatural offers the following ways of selecting a value for a criteria :

Widget type (rdfs:subPropertyOf)	Description
core:ListProperty (or core:LiteralListProperty which is deprecated)	dropdown list widget
core:AutocompleteProperty	autocomplete search field
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)

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

Example

Note how the properties in our configuration uses different kinds of widgets: