The SPARQL Service Interface
- Editor
- Dan Connolly
- This Version
- live draft: $Id: prot26.html,v 1.20 2005/02/27 07:13:33 connolly Exp $
Abstract
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
Introduction
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: <http://xmlns.com/foaf/0.1/>
SELECT ?pg
WHERE
(?who foaf:name "Johnny Lee Outlaw")
(?who foaf:weblog ?pg)
And we encode the query in a URI in the conventional way:
http://pim.example/data?query=PREFIX+foaf%3A+%3Chttp%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2F%3E%0D%0ASELECT+%3Fpg%0D%0AWHERE%0D%0A++%28%3Fwho+foaf%3Aname+%22Norm+Walsh%22%29%0D%0A++%28%3Fwho+foaf%3Aweblog+%3Fpg%29%0D%0A
We expect results such as the following:
<sparql xmlns="http://www.w3.org/2001/sw/DataAccess/rf1/result">
<head>
<variable name="pg"/>
</head>
<results>
<result>
<pg uri="http://blog.outlaw.example/"/>
</result>
</results>
</sparql>
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?query=PREFIX+foaf%3A+%3Chttp%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2F%3E%0D%0ASELECT+%3Fpg%0D%0AWHERE%0D%0A++%28%3Fwho+foaf%3Aname+%22Norm+Walsh%22%29%0D%0A++%28%3Fwho+foaf%3Aweblog+%3Fpg%29%0D%0A HTTP/1.1
Host: pim.example
and the result should be:
200 OK
Content-Type: application/xml
<sparql xmlns="http://www.w3.org/2001/sw/DataAccess/rf1/result">
<head>
<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
References
Normative:
- RFC2119
- Key words for
use in RFCs to Indicate Requirement Levels RFC 2119
S. Bradner March 1997
- HTTP
- 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
- XForms
1.0, R. Merrick, L. L. Klotz, T. V. Raman, M. Dubinko,
Editors, W3C Recommendation, 14 October 2003,
http://www.w3.org/TR/2003/REC-xforms-20031014/ . Latest version available at
http://www.w3.org/TR/xforms/ .
- RDFX
- RDF/XML
Syntax Specification (Revised) , D. Beckett, Editor, W3C
Recommendation, 10 February 2004,
http://www.w3.org/TR/2004/REC-rdf-syntax-grammar-20040210/ . Latest version
available at http://www.w3.org/TR/rdf-syntax-grammar .
- VBR
- SPARQL
Variable Binding Results XML Format, D. Beckett, Editor,
W3C Working Draft (work in progress), 21 December 2004,
http://www.w3.org/TR/2004/WD-rdf-sparql-XMLres-20041221/ . Latest version
available at http://www.w3.org/TR/rdf-sparql-XMLres/ .
- IRI
- Internationalized Resource
Identifiers (IRIs) M. Duerst, M. Suignard, eds. Internet
Proposed Standard January 2005
- QL
- SPARQL
Query Language for RDF, A. Seaborne, E. Prud'hommeaux,
Editors, W3C Working Draft (work in progress), 17 February 2005,
http://www.w3.org/TR/2005/WD-rdf-sparql-query-20050217/ . Latest version
available at http://www.w3.org/TR/rdf-sparql-query/ .
Informative:
- UCR
- RDF Data
Access Use Cases and Requirements, K. Clark, Editor, W3C
Working Draft (work in progress), 12 October 2004,
http://www.w3.org/TR/2004/WD-rdf-dawg-uc-20041012/ . Latest version
available at http://www.w3.org/TR/rdf-dawg-uc/ .
fodder for the Bibliography generator:
UCR http://www.w3.org/TR/2004/WD-rdf-dawg-uc-20041012/
QL http://www.w3.org/TR/rdf-sparql-query/
VBR http://www.w3.org/TR/2004/WD-rdf-sparql-XMLres-20041221/
XForms http://www.w3.org/TR/2003/REC-xforms-20031014/