Copyright © 2004 W3C® ( MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, and document use rules apply.
The SPARQL Query Lanuage [SQ] defines a query service's response to a valid SPARQL query. SPARQL clients use the SPARQL Protocol to communiate these queries to services and accept the responses. The W3C has specified a language, WSDL 2.0 [WB] which can be used to define the syntax of protocols. This document defines a protocol by defining its syntax in WSDL 2.0. The semantics of the arguments are defined in this document.
This documents experiments by the author. It is not endorsed by the W3C Team or Membership. It is hoped that the work described here will be useful to the Data Access Working Group.
SPARQL Protocol is a simple practical protocol for transporting SPARQL queries. It uses HTTP GET for the transport, a fixed character encoding of utf-8, and is described as a Web service with a WSDL 2.0 service description. This protocol defines a single message parameter, query, and a small numer of responses indicating successful processing or encountered errors. A query on a service is expressed as a URL. For example, a query:
SELECT * WHERE (?s ?p ?o)
on the service http://rdf.example/svc/ will be encoding with this URL:
http://rdf.example/svc/?query=SELECT%20%2A%20WHERE%20%28%3Fs%20%3Fp%20%3Fo%29
XForms [XF] defines a syntax for constructing a query URL from an {http location} (service URI) and a set of query parameters. This syntax is familiar to many web developers as it is practically identical to CGI parameters constructed by HTML forms. WSDL 2.0 uses the XForms syntax and defines a syntax for transporting message parameters and defining the response. Query services supporting SPARQL protocol can be described with WSDL 2.0.
Implementors of this protocol need only follow the query URI construction rules included in this document. They do not need to support any further XForms or WSDL processing. This document attempts to keep the implementation burden to a minimum by including the critical normative text from the referenced specifications.
This document introduces a small number of terms, defined here, to describe the mechanics of this protocol. For compatibility and clarity, some terms are adopted from other specifications (WSDL and XForms) and included here.
an absolute or relative URI as defined by [IETF RFC 2396]. The value of this property specifies a template for the relative portion of the request URI for an operation. This URI is combined with the base URI specified in the {address} property of the endpoint element to form the full URI for the HTTP request to invoke the operation. It MUST contain an absolute or a relative URI, i.e. it MUST NOT include a fragment identifier in the URI.
This syntax of this protocol is defined as the protocol that is compatible with the SPARQL-P service description, which is excerpted and explained here:
<description targetNamespace='...SPARQL-WSDL2.xml' ...>
<interface name='SPARQL'>
<operation name='query'
pattern='http://www.w3.org/2004/08/wsdl/in-out'
style='http://www.w3.org/2004/08/wsdl/style/uri'>
<input element='sl:query'/>
<output element='xr:sparql rdf:RDF'/>
</operation>
</interface>
<binding name='httpSparqlBinding'
interface='SPARQL'
type='http://www.w3.org/2004/08/wsdl/http'>
<fault name="MalformedRequest" whttp:code='400'>
<fault name="UnsupportedOperation" whttp:code='501'>
<operation ref='sl:query'
whttp:method="GET" >
</operation>
</binding>
</description>
This defines a service identified by http://.../SPARQL-WSDL2.xml which has a single input parameter called query (see X.0 Input). The XML Schema type [XS] of that parameter is xs:string. The response for a successfully processed request is an XML document with either a <result/> or <rdf:RDF/> root element. The meaning of these documents are described in X.0 Result Set Response and X.0 RDF Response respectively. The binding operation specifies a GET method. This is defined in X.0 HTTP Binding. The service description does not identify a particular {HTTP Location}. Different services will publish different {HTTP Locations}. These services may advertise the {HTTP Locations} via any conventional (e.g. via a complete WSDL 2.0 description, see X.0 SPARQL WSDL Service Description) or emergent means (e.g. via an RDF service description).
The SPARQL Query string is byte-encoded in utf-8 and then url-encoded by the WSDL URL construction rules::
Element nodes selected for inclusion are encoded as
EltName=value{sep}, where=is a literal character,{sep}is the separator character from theseparatorattribute onsubmission,EltNamerepresents the element local name, andvaluerepresents the contents of the text node. Note that contextual path information is not preserved, nor are namespaces or namespace prefixes. As a result, different elements might serialize to the same name.
The encoding of
EltNameandvalueare as follows: space characters are replaced by+, and then non-ASCII and reserved characters (as defined by [RFC 2396] as amended by subsequent documents in the IETF track) are escaped by replacing the character with one or more octets of the UTF-8 representation of the character, with each octet in turn replaced by%HH, whereHHrepresents the uppercase hexadecimal notation for the octet value and%is a literal character. Line breaks are represented as "CR LF" pairs (i.e.,%0D%0A).
If the value of the {http location} property does not contain a "?" (question mark) character, one is appended. If it does already contain a question mark character, then an "&" separator character is appended. Each parameter pair is separated by the "&" separator character.
The choice of character encoding was motivated by the following guidelines from the Character Model specification [CM]:
C015 [S] Specifications MUST either specify a unique character encoding, or provide character encoding identification mechanisms such that the encoding of text can be reliably identified.
C016 [S] When designing a new protocol, format or API, specifications SHOULD require a unique character encoding.
C018 [S] When a unique character encoding is required, the character encoding MUST be UTF-8, UTF-16 or UTF-32.
SPARQL Query [SQ] defines queries and identifies the response formats for successfully processed queries.
<description targetNamespace='...SPARQL-WSDL2.xml' ...>
<interface name='SPARQL'>
<operation name='query'
pattern='http://www.w3.org/2004/08/wsdl/in-out'
style='http://www.w3.org/2004/08/wsdl/style/uri'>
<input element='sl:query'/>
<output element='xr:sparql rdf:RDF'/>
</operation>
</interface>
...
</description>
SPARQL Query also identifies two error responses. These are identified with the faults UnsupportedOperation and MalformedRequest.
SPARQL queries of the forms SELECT ... and ASK ... [SQ] yields tabular XML results [SR], represented by xr:sparql in the WSDL description.
<sparql xmlns="http://www.w3.org/2001/sw/DataAccess/rf1/result">
<head><variable name="s"/>
<variable name="p"/>
<variable name="o"/></head>
<results>
<result><s bnodeid="b1">
<p uri="http://xmlns.com/foaf/0.1/name"/>
<o xml:lang="en">Bob</o></result>
<result><s bnodeid="b1">
<p uri="http://xmlns.com/foaf/0.1/mbox"/>
<o uri="mailto:bob@example.com"/></result>
</results>
</sparql>
This is indicated by xr:sparql in the WSDL 2.0 description.
SPARQL queries of the forms CONSTRUCT ... and DESCRIBE ... [SQ] yield RDF/XML results [RX], represented by rdf:RDF in the WSDL description.
<rdf:RDF xmlns="http://xmlns.com/foaf/0.1/"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description>
<name>Bob</name>
<mbox rdf:resource="mailto:bob@example.com"/>
</rdf:Description>
</rdf:RDF>
This is indicated by rdf:RDF in the WSDL 2.0 description.
Errors resulting of SPARQL queries result in HTTP errors with a string containing an error description (in sl:faultDetails). The HTTP error code is specified by the whttp:code attribute.
<UnsupportedOperation> <faultDetails>http://my.example/functions#even</faultDetails> <UnsupportedOperation>
The reference service description asserts that there is a GET operation for transporting SPARQL queries. A service with an {http location} http://rdf.example/svc/ and a SPARQL Query "SELECT * WHERE (?s ?p ?o)" will have the following bytes on the wire:
GET /svc/?query=SELECT%20%2A%20WHERE%20%28%3Fs%20%3Fp%20%3Fo%29 HTTP/1.1 Host: rdf.example
A Service that uses WSDL 2.0 to describe this service would use:
<description ...
xmlns:generic='http://lists.w3.org/Archives/Public/public-rdf-dawg/2005JanMar/att-0205/SPARQL-WSDL2.xml'>
<import namespace='http://lists.w3.org/Archives/Public/public-rdf-dawg/2005JanMar/att-0205/SPARQL-WSDL2.xml'
location='http://lists.w3.org/Archives/Public/public-rdf-dawg/2005JanMar/att-0205/SPARQL-WSDL2.xml'/>
<binding name='httpSparqlBinding'>
interface='generic:SPARQL'
<operation ref='sl:query' whttp:location="query"
whttp:method="GET" >
</operation>
</binding>
<service>
<endpoint name='EP'
binding='sl:httpSparqlBinding'
address='http://rdf.example/svc/'>
</endpoint>
</service>
</description>Different services may publish variants of the binding in order to add information that they need for processing. This is defined by WSDL but repeated here. A service may, for instance, offer a parser that supports more than one language. This service is free to define a binding with an additional parameter to identify the language:
<description ...
xmlns:generic='http://lists.w3.org/Archives/Public/public-rdf-dawg/2005JanMar/att-0205/SPARQL-WSDL2.xml'>
<import namespace='http://lists.w3.org/Archives/Public/public-rdf-dawg/2005JanMar/att-0205/SPARQL-WSDL2.xml'
location='http://lists.w3.org/Archives/Public/public-rdf-dawg/2005JanMar/att-0205/SPARQL-WSDL2.xml'/>
<binding name='httpSparqlBinding'
interface='generic:SPARQL'>
<operation ref='sl:query' whttp:location="query?lang=sparql"
whttp:method="GET" >
</operation>
</binding>
<service>
<endpoint name='EP'
binding='sl:httpSparqlBinding'
address='http://rdf.example/svc/'>
</endpoint>
</service>
<interface>
<description>A client calling this service will see follow the WSDL URL construction rules, producing a query as such:
GET /svc/?lang=sparql&query=SELECT%20%2A%20WHERE%20%28%3Fs%20%3Fp%20%3Fo%29 HTTP/1.1 Host: rdf.example
While the service is defined by WSDL, the client need not process WSDL. A client may learn about a query service from an RDF service description or a user interface. The {http location} of a service is the concatonation of the operation location to the endpoint address. For example the above has a {http location} of the above interface is:
http://rdf.example/svc/?lang=sparql