Copyright © 2011 by the Submitting Members.
This document is available under the W3C Document License. See the W3C Intellectual Rights Notice and Legal Disclaimers for additional information.
This document describes the SPIN SPARQL Syntax, an RDF representation of the semantic web query language SPARQL. The SPIN SPARQL Syntax provides an alternative representation of SPARQL queries that goes beyond the textual format. The main benefit of this syntax is that it makes it possible to consistently store SPARQL queries together with the domain model. All resources from the domain model are represented as proper RDF resource references instead of only having them as strings. Having a triple-based SPARQL representation makes it easier to maintain hybrid models in which RDF/OWL definitions are mixed with SPARQL expressions.
SPIN has originally evolved as a specification developed by TopQuadrant. As of February 2011, SPIN has been published by W3C as a member submission. TopQuadrant may continue to improve SPIN in the future and make changes that will be published here. As of January 2013, this version is almost identical to the official W3C submission, except that we have lifted the requirement of using the SPIN RDF syntax for the definition of queries and update commands if (and only if) sp:text triples are present. Accordingly, we have changed the RDF source code of some examples in the SPIN Modeling Vocabulary document, to make them easier to read.
The design of the SPIN SPARQL Syntax was motivated by the need to have a machine-readable notation of SPARQL queries so that they can be stored together with other domain models and ontologies in RDF format. The main goal is to enable SPIN compliant software tools to convert SPIN RDF data structures into valid SPARQL query strings, so that they can be processed for various purposes. Editing tools would go the other direction and turn a SPARQL query into an RDF structure.
For example, the SPARQL query
# must be at least 18 years old
ASK WHERE {
?this my:age ?age .
FILTER (?age < 18) .
}
can be represented by a blank node in the SPIN RDF Syntax in Turtle as
[ a sp:Ask ;
rdfs:comment "must be at least 18 years old"^^xsd:string ;
sp:where ([ sp:object sp:_age ;
sp:predicate my:age ;
sp:subject spin:_this
] [ a sp:Filter ;
sp:expression
[ sp:arg1 sp:_age ;
sp:arg2 18 ;
a sp:lt
]
])
]
Alternatively, the property sp:text can be used within the
surrounding blank node, creating a more human-readable notation:
[ a sp:Ask ;
sp:text """
# must be at least 18 years old
ASK WHERE {
?this my:age ?age .
FILTER (?age < 18) .
}"""
]
In a typical scenario, each SPARQL query is stored as a (tree) structure
of blank nodes. Syntax rules specify which elements can be nested into
each other. The top-level blank node of a query is an instance of one
of the subclasses of sp:Query, such as sp:Ask.
Queries typically have a WHERE clause, encoded as a value of the
sp:where property. The elements in the WHERE clause are
represented as instances of subclasses of sp:Element
(or plain rdf:Lists for element lists).
Some element types such as sp:Filter may point to an
Expression. This document introduces the various types of
expressions, then the elements and finally the query objects and
SPARQL UPDATE language requests.
The URL of the SPIN SPARQL Syntax schema is http://spinrdf.org/sp. It currently covers all standard SPARQL language elements as well as parts of the evolving SPARQL 1.1 language including SPARQL Update.
Expressions are used, among others, as conditions in FILTER elements and in BIND assignments. Three kinds of expressions are supported by SPIN: Constants, Variables and Function calls.
Constants are simply represented by a URI resource or a literal.
Variables are represented by resources that have a string value for
the sp:varName property. In many cases, these resources may
be untyped blank nodes, but there is also a marker class
sp:Variable that can be used to make variables
better visible. However, only sp:varName is used
to distinguish variables from other types of expressions.
The following example represents a variable called ?x.
[ sp:varName "x"^^xsd:string
]
Function calls are blank nodes that have the function's URI as
their rdf:type. All other properties of the blank node
are interpreted as arguments.
By default, the arguments are stored as values of the
pre-defined system properties sp:arg1,
sp:arg2, etc.
However, any other property can be used as well.
When a function call is serialized back to SPARQL textual syntax,
then the argument properties are ordered by their local names,
and the built-in properties sp:arg1 etc appear at
their designed position, e.g. sp:arg4 will always
appear as forth argument. Any other properties are filling in
the remaining spots, not occupied by the built-in properties.
Note that a function call cannot have a value for sp:varName
because this would turn it into a variable.
The following example represents the function call
ex:getMaximum(42, 43):
[ a ex:getMaximum ;
sp:arg1 42 ;
sp:arg2 43
]
The SPIN RDF Syntax provides standard URIs for the built-in functions
and operators of the SPARQL language. For example, sp:gt
represents the > operator.
SPARQL 1.1 introduces the ability to use EXISTS and
NOT EXISTS in SPARQL expressions. The SPIN RDF Syntax represents
those as blank nodes of type sp:exists and sp:notExists.
Those nodes point to a list of elements via the sp:elements property.
SPARQL query elements are the main entities mentioned in WHERE clauses, including triple patterns and FILTER clauses.
A blank node that has exactly one value for the properties
sp:subject, sp:predicate and
sp:object represents a triple pattern.
Optionally, the blank node may have the rdf:type
sp:TriplePattern.
Example:
?this ex:age 42 .
Represented in SPIN Syntax as:
[ sp:subject spin:_this ;
sp:predicate ex:age ;
sp:object 42
]
Note that the properties sp:subject etc are similar to the built-in
system properties rdf:subject. SPIN does not use the latter to avoid
potentially confusing overlaps with the RDF reification vocabulary.
Triple paths are similar to triple patterns, but have a path
expression instead of a predicate. SPIN represents triple
paths as blank nodes with a value of sp:path,
as well as sp:subject and sp:object values.
The blank node may also have sp:TriplePath as
its rdf:type.
Various types of paths are supported, based on what is currently implemented in the Jena ARQ API:
sp:SeqPath represents a sequence of two
nested sub-paths, specified by sp:path1 and
sp:path2.
sp:AltPath represents a union between two
alternative paths, specified by sp:path1 and
sp:path2.
sp:ModPath represents a modified path such
as path* or path{n,m}. The nested
path is stored as sp:subPath, and
sp:modMin and sp:modMax are used
to store the min and max values.
sp:ReversePath represents a path in the inverse
direction. The property sp:subPath is used to
point to the path that is to be reversed.
Example:
?this ex:father/ex:age 42 .
Represented in SPIN Syntax as:
[ a sp:TriplePath ;
sp:subject spin:_this ;
sp:path [ a sp:SeqPath ;
sp:path1 ex:father ;
sp:path2 ex:age
] ;
sp:object 42
]
Filter elements are stored as blank nodes that have
sp:Filter as their rdf:type.
The blank node must have exactly one value for the property
sp:expression, pointing to an expression that
can be evaluated to true or false.
Example:
FILTER (?age >= 18) .
Represented in SPIN Syntax as:
[ a sp:Filter ;
sp:expression
[ a sp:ge ;
sp:arg1 [ sp:varName "age"^^xsd:string ] ;
sp:arg2 18
]
]
The BIND keyword was introduced by SPARQL 1.1
to assign a computed value to a variable in the middle of a
pattern. The computed value can then be used in other
patterns, CONSTRUCT templates etc.
The SPIN SPARQL Syntax introduces the class sp:Bind to
represent BIND assignments. Instances of this class must be blank
nodes with one value for sp:variable to point at the
variable on the right side of the assignment. The property
sp:expression is used to point to the root of the expression
tree that delivers the computed value.
Example:
BIND (2008 - ?birthYear AS ?age) .
Represented in SPIN Syntax as:
[ a sp:Bind ;
sp:variable [ sp:varName "age"^^xsd:string ] ;
sp:expression
[ a sp:sub ;
sp:arg1 2008 ;
sp:arg2 [ sp:varName "birthYear"^^xsd:string ]
]
]
Note: Earlier versions of SPIN were using sp:Let instead of sp:Bind.
Lists of other elements are used in various places in SPARQL,
for example as root of the WHERE clause. SPIN represents
them as plain rdf:Lists, where each list member
must be another element.
Optional element blocks are instances of
sp:Optional where the property
sp:elements is used to point to the list of
optional elements (stored as rdf:List).
Example:
OPTIONAL { ?this ex:firstName ?value }
Represented in SPIN Syntax as:
[ a sp:Optional ;
sp:elements ([ sp:subject spin:_this ;
sp:predicate ex:firstName ;
sp:object [ sp:varName "value"^^xsd:string ]
])
]
The UNION operator in SPARQL can be used to specify a
graph pattern that matches if one out of several sub-elements
matches. SPIN represents UNIONs as blank nodes of type
sp:Union, where sp:elements
points to an rdf:List of nested element
lists (themselves rdf:Lists).
Example:
{
?this ex:age 42
}
UNION
{
?this ex:age 43
}
Represented in SPIN Syntax as:
[ a sp:Union ;
sp:elements ( ([ sp:subject spin:_this ;
sp:predicate ex:age ;
sp:object 42
])
([ sp:subject spin:_this ;
sp:predicate ex:age ;
sp:object 43
]))
]
Blank instances of the class sp:NamedGraph
represent named graph elements in a query. The property
sp:graphNameNode stores the URI resource of
the named graph, or a variable. sp:elements
links the blank node with an rdf:List
containing the elements in the named graph.
Example:
GRAPH <http://example.org> {
?this ex:firstName ?value
}
Represented in SPIN Syntax as:
[ a sp:NamedGraph ;
sp:graphNameNode <http://example.org> ;
sp:elements ([ sp:subject spin:_this ;
sp:predicate ex:firstName ;
sp:object [ sp:varName "value"^^xsd:string ]
])
]
Blank instancef of the class sp:SubQuery
represent sub-queries that are nested in the body of another
query. The property sp:query points to the
nested query.
Example:
SELECT ?y
WHERE {
?class a rdfs:Class .
{
SELECT ?y
WHERE {
?class rdfs:label ?y .
}
} .
}
Represented in SPIN Syntax as:
[ a sp:Select ;
sp:resultVariables (_:b2) ;
sp:where ([ sp:object rdfs:Class ;
sp:predicate rdf:type ;
sp:subject _:b1
] [ a sp:SubQuery ;
sp:query
[ a sp:Select ;
sp:resultVariables (_:b2) ;
sp:where ([ sp:object _:b2 ;
sp:predicate rdfs:label ;
sp:subject _:b1
])
]
])
]
SPARQL 1.1 will provide keywords for negation.
One of the proposals (implemented in Jena's ARQ engine) is to use
the NOT EXISTS keyword.
In SPIN, NOT EXISTS blocks are represented as instances of
sp:NotExists where the property
sp:elements is used to point to the list of
negative elements (stored as rdf:List).
Example:
NOT EXISTS { ?this ex:firstName ?value }
Represented in SPIN Syntax as:
[ a sp:NotExists ;
sp:elements ([ sp:subject spin:_this ;
sp:predicate ex:firstName ;
sp:object [ sp:varName "value"^^xsd:string ]
])
]
In addition to NOT EXISTS, SPARQL 1.1 will also introduce the keyword MINUS.
In SPIN, MINUS blocks are represented as instances of
sp:Minus where the property
sp:elements is used to point to the list of
negative elements (stored as rdf:List).
Example:
MINUS { ?this ex:firstName ?value }
Represented in SPIN Syntax as:
[ a sp:Minus ;
sp:elements ([ sp:subject spin:_this ;
sp:predicate ex:firstName ;
sp:object [ sp:varName "value"^^xsd:string ]
])
]
The SERVICE keyword can be used to match a sub-query against a remote SPARQL end point.
SPIN RDF Syntax represents such SERVICE calls with instances of
sp:Service where the property
sp:elements is used to point to the list of
optional elements (stored as rdf:List), and the property
sp:serviceURI points to the URI of the SPARQL end point.
Example:
SERVICE <http://dbpedia.org/sparql> {
?this ex:firstName ?value }
Represented in SPIN Syntax as:
[ a sp:Service ;
sp:serviceURI <http://dbpedia.org/sparql>
sp:elements ([ sp:subject spin:_this ;
sp:predicate ex:firstName ;
sp:object [ sp:varName "value"^^xsd:string ]
])
]
The VALUES keyword can be used to pre-bind variables with given RDF nodes.
Example:
SELECT ?country ?code
WHERE {
VALUES (?country ?code) {
(ex:Germany "de")
(ex:Norway "no")
(ex:Endor UNDEF)
} .
}
Represented in SPIN Syntax as:
[ a sp:Select ;
sp:resultVariables (
[ sp:varName "country"^^xsd:string ]
[ sp:varName "code"^^xsd:string ] ) ;
sp:where (
[ a sp:Values ;
sp:bindings (
( ex:Germany "de" )
( ex:Norway "no" )
( ex:Norway sp:undef )
) ;
sp:varNames ( "country"^^xsd:string "code"^^xsd:string )
] )
]
VALUES clauses can also be used on queries, in which case the query object must
point to an sp:Values blank node via sp:values.
Queries are the top-level objects in the SPIN metamodel.
Queries are instances of the subclasses of sp:Query:
sp:Ask, sp:Select, sp:Describe
and sp:Construct. Queries might be blank nodes,
and in most cases they will be blank nodes that are only linked
to the rest of a model via properties such as spin:rule
or spin:constraint.
Common to all query types is that they may have a WHERE clause.
The WHERE clause is an element list stored as value of the
sp:where property on the query instance.
Other common properties are sp:from and
sp:fromNamed which can be used to link a query instance
with FROM and FROM NAMED URIs, respectively.
Queries can have an rdfs:comment to capture a comment
string. In the textual notation of SPARQL, those comments would
show up in the lines above the query, behind # characters.
SPIN currently does not support comments that are placed elsewhere in
the query, because many SPARQL parsers do not preserve this information.
Queries may have the textual form in the original SPARQL syntax
stored as a string using sp:text. This may contribute
to readability and may be useful for tools that cannot parse the full
SPIN SPARQL syntax.
Note that while the textual notation of SPARQL supports explicit
prefix declarations, these are not needed in SPIN. The prefixes declared
by the RDF model itself will be used in addition to those defined in the
sp:text.
Implementations should support both syntaxes, but if no full SPIN RDF
parser is available, the engines may only use the sp:text
triple. In order to parse those, a system should prepend the prefix
declarations from the surrounding RDF graph, to make the sp:text
valid for parsing.
The following sections provide some details on the various types of queries.
The class sp:Ask is used to represent ASK queries.
Example:
# must be at least 18 years old
ASK WHERE {
?this ex:age ?age .
FILTER (?age >= 18) .
}
Represented in SPIN Syntax as:
[ a sp:Ask ;
rdfs:comment "must be at least 18 years old"^^xsd:string ;
sp:where ([ sp:object _:b1 ;
sp:predicate ex:age ;
sp:subject spin:_this
] [ a sp:Filter ;
sp:expression
[ a sp:ge ;
sp:arg1 _:b1 ;
sp:arg2 18
]
])
]
Note that in the above example, the blank node _:b1
points to the variable ?age elsewhere in the model.
The class sp:Select is used to represent
SELECT queries.
If a SELECT query has a
DISTINCT
keyword, then its value of
sp:distinct is set to true. Similarly,
the REDUCED
keyword is mapped into sp:reduced.
For SELECT queries that do not have the star (*) format, the property
sp:resultVariables points to an rdf:List
of the variables or aggregations behind the SELECT keyword.
This property is left empty in the case of SELECT *.
The following types of aggregations are supported right now:
| SPARQL Aggregation | SPIN Class |
|---|---|
| AVG | sp:Avg |
| COUNT | sp:Count |
| MAX | sp:Max |
| MIN | sp:Min |
| SUM | sp:Sum |
| GROUP_CONCAT | TODO |
| SAMPLE | TODO |
For example, each COUNT expression is a blank node of type sp:Count
which can have an expression in its sp:expression property.
Each of those nodes can have a boolean flag sp:distinct to support
the SPARQL DISTINCT keyword inside of an aggregation.
SELECT queries may have solution modifiers. A
LIMIT
keyword is mapped into an integer value of sp:limit.
Similarly, OFFSET
is stored with sp:offset.
If an ORDER BY
statement is present in a query, then the SPIN query object will have a
property sp:orderBy that points to an rdf:List.
The members of this list are either expressions, or blank nodes of type
sp:Asc or sp:Desc which have the expression stored
as value of the sp:expression property.
Example:
SELECT COUNT(?object)
WHERE {
?this ?arg1 ?object
}
Represented in SPIN Syntax as:
[ a sp:Select ;
sp:resultVariables ([ a sp:Count ;
sp:expression sp:_object
]) ;
sp:where ([ sp:object sp:_object ;
sp:predicate spin:_arg1 ;
sp:subject spin:_this
])
]
The class sp:Describe is used to represent DESCRIBE
queries. Comparable to SELECT queries, the property
sp:resultNodes is used to link to the list of
described variables.
Example:
DESCRIBE ?value
WHERE {
?this ex:uncle ?value
}
Represented in SPIN Syntax as:
[ a sp:Describe ;
sp:resultNodes (sp:_value) ;
sp:where ([ sp:object sp:_value ;
sp:predicate ex:uncle ;
sp:subject spin:_this
])
]
The class sp:Construct is used to represent CONSTRUCT
queries. Beside the usual sp:where clauses, the
property sp:templates links to an rdf:List
of template triples. Each of these template triples is a blank
node with values for sp:subject, sp:predicate
and sp:object.
Example:
# infer grandParent relationship
CONSTRUCT {
?this ex:grandParent ?grandParent .
}
WHERE {
?parent ex:child ?this .
?grandParent ex:child ?parent .
}
Represented in SPIN Syntax as:
[ a sp:Construct ;
rdfs:comment "infer grandParent relationship"^^xsd:string ;
sp:templates ([ sp:object sp:_grandParent ;
sp:predicate ex:grandParent ;
sp:subject spin:_this
]) ;
sp:where ([ sp:object spin:_this ;
sp:predicate ex:child ;
sp:subject sp:_parent
]
[ sp:object sp:_parent ;
sp:predicate ex:child ;
sp:subject sp:_grandParent
])
]
The SPARQL UPDATE language is currently evolving as part of the SPARQL 1.1 working group. Many UPDATE operations share the same syntax as SPARQL queries in the WHERE clause. INSERT and DELETE operations are also similar to CONSTRUCT queries. A major difference however is that the heads of the INSERT and DELETE queries allow nested GRAPH elements, in addition to triple patterns.
The class sp:InsertData represents INSERT DATA operations.
The values of sp:data must be rdf:Lists with blank nodes
as members - either triples or sp:NamedGraph elements.
Note that this syntax is slighly more general than what the SPARQL 1.1 standard
allows (either a named graph or a triples block), but the SPIN syntax is consistent
with how similar blocks are represented in INSERT/DELETE operations and elsewhere.
Example:
INSERT DATA {
GRAPH <http://example.org> {
owl:Nothing a owl:Nothing .
}
}
[ a sp:InsertData ;
sp:data ([ a sp:NamedGraph ;
sp:elements ([ sp:object owl:Nothing ;
sp:predicate rdf:type ;
sp:subject owl:Nothing
]) ;
sp:graphNameNode <http://example.org>
])
]
DELETE DATA operations are encoded similar to INSERT DATA, but with
sp:DeleteData instead of sp:InsertData.
The class sp:Modify is used to represent DELETE/INSERT requests.
Example:
WITH <urn:example:graph>
DELETE {
:Thing rdfs:label ?oldLabel .
}
INSERT {
:Thing rdfs:label "New label" .
}
WHERE {
:Thing rdfs:label ?oldLabel .
}
Represented in SPIN Syntax as:
[ a sp:Modify ;
sp:graphIRI <urn:example:graph> ;
sp:deletePattern ([ sp:object _:b1 ;
sp:predicate rdfs:label ;
sp:subject :Thing
]) ;
sp:insertPattern ([ sp:object "New label" ;
sp:predicate rdfs:label ;
sp:subject :Thing
]) ;
sp:where ([ sp:object _:b1 ;
sp:predicate rdfs:label ;
sp:subject :Thing
])
]
The values of sp:deletePattern and sp:insertPattern
must be rdf:Lists with blank nodes
as members - either triples or sp:NamedGraph elements.
The properties may point to an empty list (rdf:nil) to make sure that
the operation will print an empty DELETE or INSERT block, resp.
The optional WITH clause is encoded using sp:graphIRI.
sp:using and sp:usingNamed may point to zero or more
named graphs (not stored as lists but individual triples).
The WHERE clause is encoded similar to other queries, using sp:where.
The class sp:DeleteWhere represents DELETE WHERE operations.
The WHERE clause is encoded similar to other queries, using sp:where.
The class sp:Load represents LOAD operations.
sp:document points to the document to load.
The property sp:into may point to the optional target graph.
Example:
LOAD <http://example.org> INTO GRAPH <http://target.org>
Represented in SPIN Syntax as:
[ a sp:Load ;
sp:document <http://example.org> ;
sp:into <http://target.org>
]
The class sp:Clear represents CLEAR operations.
The SILENT option is represented using sp:silent set to "true"^^xsd:boolean.
The target is represented with either sp:graphIRI (pointing to a IRI resource),
or boolean flags sp:default, sp:named or sp:all set to true.
The class sp:Create represents CREATE operations.
The SILENT option is represented using sp:silent set to "true"^^xsd:boolean.
The target is represented with sp:graphIRI (pointing to a IRI resource).
The class sp:Drop represents DROP operations.
The SILENT option is represented using sp:silent set to "true"^^xsd:boolean.
The target is represented with either sp:graphIRI (pointing to a IRI resource),
or boolean flags sp:default, sp:named or sp:all set to true.
The SPIN SPARQL Syntax schema can be found at http://spinrdf.org/sp.