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.
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:
spin:constraint
can be used to attach a logical
constraint or test condition with a class, so that all
instances of that class must meet the constraint.
The Constraint checking
feature can be used to verify those conditions at edit timespin:constructor
can be used to initialize
instances of certain classes with default valuesspin:rule
makes it possible to attach executable
rules with classes
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.
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.
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.