Welcome to this guide on how to setup the “Hello Sparnatural” page ! “Hello Sparnatural” is the tutorial page released with Sparnatural in each of the releases. This documentation will guide you on the necessary steps to work with this tutorial page, and start adapting it to your own knowledge graph. Once customized you can keep the tutorial page in your local machine or publish it online, provided that your SPARQL endpoint is also publicly available.

At the end of this tutorial, you will have a working HTML page demonstrating the feasibility of plugin Sparnatural on your own data. You can then explore further possibilities of configuring Sparnatural in the other guide “How to configure Sparnatural”, and adapt the look-and-feel of the page to match your website.

Prerequisites

In order to follow this guide, you need the following prerequisites:

You need to have your own SPARQL-accessible dataset. If you don’t have any SPARQL-accessible dataset, you can use the DBPedia dataset, accessible at https://dbpedia.org/sparql. GraphDB users can find their active repository SPARQL URL in the home page, in the “link” icon in the “Active repository” section:

You need to have a basic understanding of the structure of your dataset. More specifically you need to know the URI identifiers of 2 classes in your ontology, and one property linking these two classes. If you don’t know this information, try to find the documentation of your dataset, in the form of UML diagrams or documentation tables.
You need to have the Protégé OWL editor installed on your machine. To install Protégé, go to https://protege.stanford.edu/.
You need to have a basic understanding of HTML, and a basic text editor to edit an HTML page.

Structure of this guide

This guide will explain:

How to setup your local work environment
How to adjust the tutorial page to use your configuration file and your own SPARQL endpoint URL
How to setup a minimal configuration demonstrating how Sparnatural can work on your data
What are the next steps once you completed this tutorial

Setup the tutorial page

Get the tutorial page

The “Hello Sparnatural” tutorial page is included with each release of Sparnatural starting from 8.4.0. To get this tutorial page:

go to the latest release of Sparnatural
download the “hello-sparnatural.zip” file from the assets list
unzip it in a local folder on your computer

Content of the tutorial folder

The tutorial folder is based on a very simple Bootstrap HTML template, in which Sparnatural is inserted and integrated with the YasGUI SPARQL editor and query result viewer. While using YasGUI is an obvious choice, YasGUI is *not* a requirement of Sparnatural. You can choose to present query results differently than in YasGUI, and you may not want to display the raw SPARQL query to the user.

The tutorial folder is composed of the following files:

Files you will edit in this tutorial:

index.html: the main HTML page that you can open in a browser and that includes the Sparnatural component.
config.ttl: a Sparnatural configuration file. In this tutorial you will create your own new config file.
example-queries.js: sample queries that you can change after your configuration has been adapted.

Files you can further customize after this tutorial if you want to enhance your demo:

main.js: the Javascript code executed by index.html, containing Sparnatural event listeners as well as YasGUI initialization code.
styles.css: the specific CSS rules for the index.html page.

Files you will not have to edit:

sparnatural.js and sparnatural.css: the code of the Sparnatural component, with its CSS rules
sparnatural-yasgui-plugins.js: the code of the result table display plugin[1]
fa subfolder: folder containing the Fontawesome free icon set.

Setup your local working environment

Allow loading of local files in your browser

Open the file index.html page from the tutorial folder in your browser. You will see a blank page with Sparnatural not loading properly, and and error in your browser console [2]:

This is because browsers, for security reasons, disable by default the dynamic loading of other files from your local directory - in our case the Sparnatural configuration file. In order for this to work, we need to instruct the browser that it is safe to dynamically load local files. This is called “enabling CORS for local files”.

/!\ Don’t worry, changing these settings will not affect the other security restrictions in your browser, in particular related to CORS.

/!\ Of course, this is only in order to work with local files. Once deployed on a web server, this restriction is not applicable anymore, and normal users of your page will not have to set the same settings.

The procedure to enable CORS for local files depends on the browser:

Firefox

To make Firefox CORS-enabled for local files:

Open Firefox
Type “about:config” in the address bar
Accept security warning
Search for the config security.fileuri.strict_origin_policy
Set this config to “false”
Restart your browser to make sure this is taken into account

Chrome, Chromium or Edge

To make Chrome, Chromium or Edge CORS-enabled for local files :

Close Chrome
Open a command-line or a terminal
Re-run chrome with the flag “--allow-file-access-from-files”, e.g. on Ubuntu Linux “chromium --allow-file-access-from-files”
You can create a shortcut with this flag set, for example in Windows, create a shortcut to Chrome and modify the command being run in the shortcut properties:

Once you have configured this setting, try reopening the index.html page. You should see Sparnatural loaded correctly:

Ensure your SPARQL endpoint is CORS-enabled, or use a proxy

Why do we need CORS ?

CORS stands for Cross-Origin Resource Sharing. It is a mechanism by which a web client can retrieve resources from a different server from the one which it was originally loaded [3]. With CORS, servers can indicate that they allow clients loaded from another domain (or from certain other domains) to send them requests. Note that this restriction applies to client-server interactions, not to server-server interactions.

In the case of Sparnatural, it is the HTML page that sends the SPARQL query directly to a SPARQL service. This SPARQL service thus needs to allow clients/webpages to send queries to it even if they are loaded from another domain, otherwise the query will simply fail with a security warning, and you can see security errors in the requests of your browser console.

You thus need to make sure that the SPARQL endpoint you want to query with Sparnatural is CORS-enabled, unless in your target architecture the Sparnatural page will be served from the same domain as the SPARQL endpoint.

Check CORS

In case the SPARQL endpoint you want to query is public, the website https://www.test-cors.org/ can allow you to check if CORS is enabled. Most of the large SPARQL services already allow CORS, e.g. DBpedia, Wikidata, etc.

Allow CORS on your triplestore

The procedure to allow CORS from your triplestore varies depending on the tool.

GraphDB

To enable CORS on GraphDB, you need to set some specific runtime properties. Please refer to the GraphDB documentation at https://graphdb.ontotext.com/documentation/10.2/directories-and-config-properties.html?highlight=cors#workbench-properties

Virtuoso

To enable CORS on Virtuoso, follow the documentation at https://vos.openlinksw.com/owiki/wiki/VOS/VirtTipsAndTricksCORsEnableSPARQLURLs

…or use Sparnatural SPARQL proxy

Sometimes you can’t modify the triplestore parameters, or your security policy would not allow it. In that case we provide a SPARQL proxy that is CORS-enabled and that will forward the request to a target SPARQL endpoint, just acting as a bridge between Sparnatural and the target SPARQL endpoint. This SPARQL proxy is deployed at https://proxy.sparnatural.eu and documented in the Sparnatural documentation.

/!\ Of course this is only a temporary workaround, and you must not use the online proxy server in a production environment. You should deploy your own SPARQL proxy in that case. The code of the SPARQL proxy server is open-source in its own Github repository, just in case.

Point the tutorial page to your SPARQL service

Now that you have 1. adjusted the security settings of your browser and 2. enabled CORS on your triplestore (or used a proxy), it is time to point the tutorial page to your endpoint !

To do this, edit the index.html file, and search for the “<spar-natural” HTML element name (around line 68) and set the “endpoint” configuration attribute to your SPARQL endpoint URL (or to the proxy URL):

<spar-natural

src="config.ttl"

endpoint="https://localhost:7200/repositories/myRepo"

lang="en"

defaultLang="en"

distinct="true"

limit="1000"

debug="true"

></spar-natural>

Now the tutorial page is configured to point to your endpoint. Reload the page in your browser and you should see the endpoint URL displayed:

Create your first Sparnatural configuration

Setup your configuration ontology in Protégé

Now that the Sparnatural tutorial page points to your SPARQL endpoint, it is time to configure the query builder following your data structure. All this can be done via the configuration ontology you need to construct in Protégé.

Open Protégé, and start a new config ontology of yours (keep the provided config.ttl from the tutorial folder apart).

Import Sparnatural ontologies

Sparnatural comes with 2 ontologies that need to be imported (through owl:imports) in your own configuration ontology :

A core configuration ontology at http://data.sparna.fr/ontologies/sparnatural-config-core
A datasource configuration ontology at http://data.sparna.fr/ontologies/sparnatural-config-datasources

Import the 2 Sparnatural configuration ontologies in your ontology ;

To import these ontologies in Protégé use section under “Imported Ontologies > Direct imports” and then in the dialog select “Import an ontology contained in a document located on the web”, and then enter the URI of an ontology above. Repeat the process for the other one.

Once both ontologies are loaded in Protégé, check in the Classes and Object Properties tab of Protégé that you see now you can see imported classes and properties from Sparnatural base ontologies.

Specify your configuration ontology URI

Back in the “Active Ontology” tab, in the Ontology IRI field above the screen, write the https address where your configuration ontology is theoretically to be published (ex : https://data.mydomain.com/ontologies/sparnatural-config)

You are now ready to populate the existing structure with the entities (« Classes ») and the relations (« Object properties ») of your knowledge graph.

Create 2 classes

We will suppose in this tutorial that the knowledge graph data model consists of FOAF Persons and Organizations, with respective URI foaf:Person and foaf:Organization, linked with a property foaf:member. You will need to adapt the identifiers with your own URI identifiers.

First you need to create a class for each kind of entity : Organization and Person. Switch to the “Classes” tab for this.

Selec the “SparnaturalClass” in the class tree, and click the button to add a subclass under it. In the dialog you can directly type in the « Name » field of the dialog the real URI of the FOAF class you want to add; we will start with foaf:Person http://xmlns.com/foaf/0.1/Person .

Once created, edit the attributes of the new class by clicking the “+” button next to the « Annotations » label:

First add an « rdfs:label » annotation, in language “en”, with value “Person”.
Note that you can create labels in as many languages as needed as the Sparnatural component can switch languages, but for the moment let’s stick to English.