The SPARQL Service Interface

Dan Connolly
This Version
live draft: $Id: prot26.html,v 1.20 2005/02/27 07:13:33 connolly Exp $


The SPARQL service interface is a contract between RDF data access producers and consumers.

Status of this document

input to the RDF Data Access WG


The SPARQL service interface is a contract between RDF data access producers and consumers. RDF Data Access Use Cases and Requirements[UCR] discusses examples such as searching for email addresses from a personal information management service. To look at a similar, more concrete example, suppose such a service is available at http://pim.example/data. Then, using SPARQL query language[QL], we write the question where is Johnny Lee Outlaw's blog? as...

PREFIX foaf: <>
  (?who foaf:name "Johnny Lee Outlaw")
  (?who foaf:weblog ?pg)

And we encode the query in a URI in the conventional way:


We expect results such as the following:

<sparql xmlns="">
    <variable name="pg"/>
      <pg uri="http://blog.outlaw.example/"/>

This is one example. The general case is specified in the following sections. The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC2119].

Encoding Queries

A service target IRI[IRI] t is combined with a SPARQL query string qs using the conventional encoding, using query as the parameter name. The exact algorithm for encoding the query is given in section 11.6 Serialization as application/x-www-form-urlencoded of [XForms] and the algorithm for combining the encoded parameters with t is given in section 11.9 The get Submit Method.

The server should make available representations of the resource identified by the resulting IRI; in the case of an HTTP IRI, for example, responding to GET requests with 200 OK responses (or redirection 3xx or authentication/payment 4xx responses leading to 200 OK responses).

The server may respond to POST requests with parameters in the body similarly, to allow for queries that exceed practical IRI length limitations.

Datasets and Expected Results

The results of a query are determined by an RDF Dataset chosen by the server in combination with the query supplied in the request. Note the WITH and FROM clauses in section 9 Specifing RDF Datasets of [QL]:

The WITH clause gives URIs that the query processor can use to create the background graph and the FROM clause can be used to specify named graphs. A query processor may use these URIs in any way to associate an RDF Dataset with a query. For example, it could use URIs to retrieve documents, parse them and use the resulting triples as one of the graphs; alternatively, it might only service queries that specify URIs of graphs that it already has stored.

See also [SADDL@], a vocabulary for describing services, including the RDF Datasets they use.

Result Formats

To dereference the URI from the example above, a consumer may send this HTTP 1.1 request (cf section 5 HTTP Request of [HTTP]):

GET /data? HTTP/1.1
Host: pim.example

and the result should be:

200 OK
Content-Type: application/xml

<sparql xmlns="">
    <variable name="pg"/>

In cases like this, where the client does not specify acceptable content types:

If the query uses the SELECT or ASK query forms,
the response should be in the SPARQL variable binding format[VBR], labelled with the application/xml media type. (really? or do we want a more specific media type?)
If the query uses the CONSTRUCT or DESCRIBE query forms,
the results should be in RDF/XML[RDFX], labelled with the application/rdf+xml media type.

The client may specify other acceptable content types, such as turtle[@@ref], using the Accept: header (cf section 14.1 Accept of [HTTP]) and the server should use the highest quality acceptable type in response.

Note that the server may return 406 (not acceptable) or it may return 200 OK using a type that the client did not specify as acceptable.

Bad Requests

If the value of the query parameter is not a correct SPARQL query, the server must not return 200 OK; it should give a 400 (bad request) response.

A server may relay warnings using the Warning header specified in section 14.46 Warning of [HTTP].

Problems Servicing Requests

A server may respond with any of the 5xx HTTP responses: 500 Internal Server Error, 501 Not Implemented, 502 Bad Gateway, 503 Service Unavailable, etc.

Limiting Results

The client may specify a limit parameter, which is a sequence of digit characters that represent a non-negative integer. The server should include no more than the limited number of solutions in its response.

This is an alternative to specifying a LIMIT clause in the query. If both a limit parameter and a LIMIT clause are given, the server should use the lower limit. or should the protocol param override? kinda arbitrary



Key words for use in RFCs to Indicate Requirement Levels RFC 2119 S. Bradner March 1997
Hypertext Transfer Protocol -- HTTP/1.1 R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee RFC2616 June 1999
XForms 1.0, R. Merrick, L. L. Klotz, T. V. Raman, M. Dubinko, Editors, W3C Recommendation, 14 October 2003, . Latest version available at .
RDF/XML Syntax Specification (Revised) , D. Beckett, Editor, W3C Recommendation, 10 February 2004, . Latest version available at .
SPARQL Variable Binding Results XML Format, D. Beckett, Editor, W3C Working Draft (work in progress), 21 December 2004, . Latest version available at .
Internationalized Resource Identifiers (IRIs) M. Duerst, M. Suignard, eds. Internet Proposed Standard January 2005
SPARQL Query Language for RDF, A. Seaborne, E. Prud'hommeaux, Editors, W3C Working Draft (work in progress), 17 February 2005, . Latest version available at .


RDF Data Access Use Cases and Requirements, K. Clark, Editor, W3C Working Draft (work in progress), 12 October 2004, . Latest version available at .

fodder for the Bibliography generator: