Editing SPIN Queries

Assuming that your model imports the spin namespace, you will see a number of new properties in the Properties View. Notable properties are spin:query and its sub- properties. spin:query can be used to attach SPARQL/SPIN queries to any resource in your model.

The value range of spin:query is sp:Query which is the root class that is used by SPIN to represent SPARQL queries. While SPARQL itself only defines a textual notation of queries, SPIN introduces the sp: namespace that can be used to store SPARQL queries as RDF triples. There are numerous advantages of this approach over storing SPARQL queries as text:

There are some consequences of using SPIN (in its default settings) to store SPARQL queries in your model.

Note that there are various preference settings related to SPIN that can be used to customize the way that TopBraid will store SPIN queries. This includes an option to include a textual representation of each query in the RDF model, helping with human-readability. If you select the verbatim mode there, then you will be able to store comments and arbitrary layout information for editing. However, the system will internally still use the RDF notation to create the queries that are used for inferencing etc.

As of TopBraid 4.2, SPIN engines no longer make the use of the SPIN RDF triples mandatory, if sp:text triples are present. Some users of external tools may prefer sp:text so that they can more easily hand-edit SPIN files in Turtle and other formats. If you encounter files from external tools that only contain the sp:text triples, then you can add SPIN RDF triples using Model > SPIN RDF Syntax Conversion > Ensure that both SPIN RDF and sp:text exists or Switch to SPIN RDF triples (no sp:text). If you want to publish your SPIN files without the SPIN RDF, then you can use Model > SPIN RDF Syntax Conversion > Switch to sp:text triples (no SPIN RDF). Our recommendation is to use the SPIN RDF Syntax only as long as you are inside of TopBraid, and to publish files with both SPIN RDF and sp:text triples when you share your files with tools that do not support the full SPIN RDF syntax.

Entering SPIN/SPARQL queries on forms

Whenever one of the sub-properties of spin:query appears on a form, its values must be SPIN queries. Although you edit the values as SPARQL expression strings (without prefix declarations), the queries themselves are stored as SPIN data structures under the hood. SPIN queries have a star icon to the left of them to indicate that they are not just plain strings. Most query types are displayed by a yellow/brownish star icon, CONSTRUCT queries in purple as shown below.

Three sub-properties of spin:query have a dedicated meaning in SPIN:

In all those properties, the variable ?this has a special meaning, as it represents the "current" instance. For example, if you attach a CONSTRUCT query as a spin:rule to a class Person, then the rule will be executed for all instances of Person where ?this will be bound to each instance. The rules can then use the instance in the WHERE clause or the CONSTRUCT templates.

Using SPIN Templates

Any property with sp:Query as its value range (including spin:query) can also hold SPIN Template calls. This allows you to reuse existing query templates instead of having to type in SPARQL directly. To use templates, open the drop down menu to the right of the property name and select Create from SPIN template.... This will open a dialog as shown in the following screenshot:

The SPIN template call dialog lists all available templates in the left part of the screen. Some default templates are always available, including those from the spl: namespace. Other templates are collected from the .spin. files in your workspace. Additionally, all templates in the currently open file will also be visible in the dialog. Note that the system will only list templates with matching query type. For example, if you are adding a template call to spin:rule the dialog will only display templates of type CONSTRUCT.

Another and often quicker way of instantiating SPIN templates is via drag and drop. For example, you can drag a property from the Properties View over the label of the spin:constraint property. This will open a template dialog that only lists matching templates where one of the arguments is an rdf:Property. Those values will already be pre-populated in the template dialog's form.

Once you have instantiated a template, the template call will be displayed with yellow background on forms.

Templates typically define a spin:displayTemplate which is used by TopBraid Composer to display template calls in human-readable form. The arguments of a template call are displayed in bold face.

Getting an Overview of SPIN rules

Since SPIN recommends distributing SPARQL rules and constraints all over a model, it is sometimes difficult to get an overview of the classes that have rules and constraints attached to them. There is a menu item Model > Display SPIN rules and constraints that will open a tabular view of the currently open model, showing all those classes, together with the SPARQL queries and the link property (e.g. spin:rule). This table is derived using the SPIN template spl:SPINOverview defined in spl.spin.rdf. You can set up similar queries yourself, e.g. to include additional information such as the ordering or iteration counts defined in the model, and then use those queries via Model > Run SPARQL query from SPIN Template...

Another mechanism is to make spin:rule the selected resource and then find references with the corresponding button in the tool bar.