W3C

SPARQL 1.1 Uniform HTTP Protocol for Managing RDF Graphs

W3C Working Draft 26 January 2010

This version:
http://www.w3.org/TR/2010/WD-sparql11-http-rdf-update-20100126/
Latest version:
http://www.w3.org/TR/sparql11-http-rdf-update/
Previous version:
http://www.w3.org/TR/2009/WD-sparql11-http-rdf-update-20091022/
Editor:
Chimezie Ogbuji, Cleveland Clinic Foundation ogbujic@ccf.org

Abstract

SPARQL provides a standard way to query RDF data. The SPARQL update language allows a user to update RDF graphs in an RDF dataset at various levels of granularity, including individual RDF statements. The protocol described here is meant to provide a minimal set of uniform, colloquial HTTP operations for managing a semantic web of network-manipulable RDF at a strictly large level of granularity.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a Working Draft.

Comments on this document should be sent to public-rdf-dawg-comments@w3.org, a mailing list with a public archive. Questions and comments about SPARQL that are not related to this specification, including extensions and features, can be discussed on the mailing list public-sparql-dev@w3.org, (public archive).

This document was produced by the SPARQL Working Group, which is part of the W3C Semantic Web Activity.

Change Summary

Text regarding the use of PUT without a payload has been added. HTTP POST can be used to send requests to a container-like resource (identified by the request or embedded uri) to create a new RDF graph and then return a newly minted URI associated with the graph using the 201 status code and Location header field.

Conditional requests are clarified and defined for all methods where it is valid to included conditions on requests. Additional, top-level sections are added (for example: security considerations). Various editorial changes from reviews by WG members were included. Most significantly, the form of the request URIs are constrained in order to support indirect graph identification. The protocol model diagrams are simplified and broken up into two parts in order to clarify the two ways in which a request can specify the URI for an RDF graph. The SPARQL Update snippets included to demonstrate the defined semantics have been clarified in many cases. Editorial notes were removed, updated, and added.

No Endorsement

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Patents

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.


Table of Contents

  1. Introduction
  2. Terminology
  3. Protocol Model
  4. Graph Identification
  5. 5 Graph Management Operations
  6. 6 Conditional Requests
  7. 7 Security Considerations
  8. 8 Conformance
  9. 9 References

1 Introduction

This specification applies the HTTP protocol semantics in managing and modifying RDF graphs. It emphasizes a clear separation between the RDF graph management actions performed from the networked body of RDF knowledge identified by a URI as the target of the actions, the lexical form of a Request URI, the URI of a graph in an RDF dataset, and the (optional) RDF delivered with the message. This specification relies on an intuitive interpretation of the underlying HTTP protocol semantics to determine how the RDF graphs are modified. Where the meaning of the operations are described, an SPARQL Update equivalent syntax is shown for clarity.

Editorial Note: Does this adequately appeal to the REST style?

One of the goals for this specification (from the WG) is to define a RESTful protocol for RDF. However, the editor has chosen to emphasize the tenants of REST as they apply to RDF graph management explicitly rather than use the term RESTful. It is not clear to the editor if the current text does this sufficiently

When this document uses the words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and RECOMMENDED, and the words appear as emphasized text, they must be interpreted as described in RFC 2119 [RFC2119].

2 Terminology

The following terminology is used in this document:

In this specification, the phrase "the resolvable URI of a graph" is shorthand for "a URI which, when dereferenced, is expected to produce a RDF graph representation".

3 Protocol Model

This protocol specifies the semantics of HTTP operations for managing network-manipulable RDF datasets. In particular, it provides operations for removing, creating, and replacing RDF graphs as well as for adding RDF statements to existing RDF graphs . The HTTP operations defined here use URIs to route native HTTP operations to a network-manipulable RDF dataset.

However, a compliant implementation of this specification MUST accept HTTP requests directed at its dataset that include an RDF/XML payload

Editorial Note: Allowed format for RDF payload

It is not clear which of the various RDF notation will be allowed or required as RDF payload in addition to RDF/XML. Other examples include (but are not limited to): RDFa, Turtle, Notation 3, and GRDDL. In the case of the latter (GRDDL) there are also security considerations as well. See: 8. Security considerations

4 Graph Identification

4.1 Direct Graph Identification

We recall from [SPARQL] that IRIs for RDF graphs in SPARQL queries identify a resource, and the resource is represented by a graph (or, more precisely: by a document that serializes a graph)

Consider the following HTTP request to a server that implements this protocol:

   GET /rdf-graphs/employees HTTP/1.1
   Host: example.com
   Accept: application/rdf+xml
   

Per [RFC2616], the most common usage of a Request-URI is to identify a resource on an origin server or gateway. In our example, the corresponding request URI (http://example.com/rdf-graphs/employees) is meant to identify RDF triples on the example.com server that describe employees. In addition, the request specifies the GET operation, which (intuitively) means that a representation of these triples should be returned. In this case the preferred representation format is application/rdf+xml

In this way, an HTTP request can route operations towards a named graph in an RDF dataset via its URI(s). However, in using URIs in this way, we are not directly identifying the RDF graphs but rather the networked RDF knowledge they represent.

The diagram below attempts to emphasize this distinction. This diagram illustrates the most basic kind of operation where the request URI identifies the networked RDF knowledge being manipulated over the protocol

Protocol model diagram

4.2 Indirect Graph Identification

Despite the convenience of using the request URI to identify networked RDF knowledge for manipulation, it is often the case that the naming authority associated with the URI of an RDF graph in a dataset is not the same as the server managing the identified RDF content, the naming authority is not available, or the URI is not dereferencable (i.e., it is not a resolvable URI). As discussed in [RFC3986], query components are often used to carry identifying information in the form of key / value pairs where the value is another URI. This protocol leverages this convention and provides a specific interface whereby a URI with a query component of the form:

   ..?graph=http://www.example.org/other/graph
   

can be used to indirectly identify RDF triples to manipulate, via an embedded, percent-encoded URI [RFC3986]. Any server that implements this protocol and receives a request URI in this form SHOULD invoke the indicated operation on the networked RDF knowledge identified by the URI embedded in the query component where the URI is the result of percent-decoding the value associated with the graph key.

Protocol model diagram for indirect manipulation

5 Graph Management Operations

This section describes the use of the HTTP verbs to determine the operations performed on Networked RDF knowledge. Where an equivalent SPARQL Update operation is given, <graph_uri> is understood to be either the request URI or the URI indirectly specified via the query component as described above.

5.1 HTTP PUT

The HTTP PUT method SHOULD be used to store the enclosed RDF payload as networked knowledge . It SHOULD be considered a native implementation of the following sequence of SPARQL Update operations

    DROP SILENT GRAPH <graph_uri>
    CREATE SILENT GRAPH <graph_uri>
    INSERT DATA [ INTO <graph_uri> ] { .. RDF payload .. }
   

Note that the DROP and CREATE expressions are only necessary if the networked RDF knowledge does not already exist in the server.

Either the request or the encoded URI (embedded in the query component) identifies the RDF payload enclosed with the request as networked RDF knowledge. The server MUST NOT attempt to apply the request to some other resource. If the identified RDF knowledge already exists, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the identified knowledge does not exist and that URI is capable of being defined as new networked knowledge by the requesting user agent, the origin server can create the knowledge with that URI in the associated network-manipulable dataset.

If the identified networked RDF knowledge does not already exist, then a PUT request with an empty payload SHOULD be used to indicate the creation of an empty graph and is considered a native implementation of the following SPARQL Update operation:

    DROP SILENT GRAPH <graph_uri>
    CREATE SILENT GRAPH <graph_uri>   
   

Editorial Note: Empty or non-existent graphs - ISSUE-20

The behavior of this operation is at risk and dependent on the outcome of ISSUE-20

5.2 HTTP DELETE

The HTTP DELETE method SHOULD be used to delete the RDF knowledge identified by either the request or encoded URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location.

It is equivalent to:

DROP [ GRAPH <graph_uri> ]

5.3 HTTP POST

The HTTP POST method SHOULD be used to request that the origin server incorporate the RDF payload enclosed in the request with the networked RDF knowledge identified by the request or encoded URI.

    CREATE [ SILENT ] GRAPH <graph_uri>
    INSERT [ INTO <graph_uri> ] { .. RDF payload .. }
    

The HTTP POST method SHOULD also be used to request that the origin server accept the RDF payload enclosed as a request for the container resource identified by the request or encoded URI to create a new RDF graph comprised of the statements in the payload. The server SHOULD return the URI associated with the new graph via the Location HTTP header in a 201 Created response and distinguish such a request from the insertion use case on the basis of whether or not the request URI identifies networked RDF knowledge managed by the server.

This document describes updating and fetching RDF data from RDF datasets over HTTP in the REST style. It is a companion to the use of SPARQL/Update over the SPARQL protocol which uses HTTP POST to transmit a SPARQL/Update request. Both protocols specify different operations performed via the HTTP POST method.

5.4 HTTP GET

The HTTP GET method SHOULD be used to retrieve a graph representation of the networked RDF knowledge identified by the Request-URI.

This is equivalent to the following SPARQL query:

CONSTRUCT { ?s ?p ?o } WHERE { GRAPH <graph_uri> { ?s ?p ?o } }

The response to a GET request on networked RDF knowledge SHOULD be made cacheable wherever possible

6 Conditional Requests

The semantics of an invocation of any of the operations in this protocol is conditioned on an additional set of criteria if the request message includes an If-Modified-Since, If-Unmodified-Since, If-Match, If-None-Match, or If-Range header field that indicate this criteria. Such an invocation SHOULD be used to request that the operation be performed only under the circumstances described by the conditional header field(s). For example, a conditional GET requests that the graph representation be transferred only under the circumstances described by the conditional header field(s) (see [RFC2616] for more information on this) and is intended to reduce unnecessary network usage by allowing cached entities to be refreshed without requiring multiple requests or transferring data already held by the client.

7 Security Considerations

As with any protocol that is implemented as a layer above HTTP, implementations SHOULD take advantage of the many security-related facilities associated with it and are not required to carry out requested graph management operations that may be in contradistinction to a particular security policy in place. For example, when faced with an unauthenticated request to replace system critical RDF statements in a graph through the PUT method, applications may consider responding with the 401 status code (Unauthorized), indicating that the appropriate authorization is required. In cases where authentication is provided fails to meet the requirements of a particular access control policy, the 403 status code (Forbidden) can be sent back to the client to indicate this failure to meet the access control policy.

8 Conformance

@@Additional input is needed regarding whether specific language (beyond describing the expected behavior) is needed to determine levels of conformance

9 References

9.1 Normative References

RFC2119
RFC 2119: Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner, 1997. (See http://www.ietf.org/rfc/rfc2119.txt)
RFC3986
Uniform Resource Identifier (URI): Generic Syntax, Berners-Lee, Fielding, Masinter, January 2005.
RFC2616
Hypertext Transfer Protocol - HTTP/1.1. J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, June 1999. Available at http://www.ietf.org/rfc/rfc2616.txt.
WEBARCH
Architecture of the World Wide Web, Volume One , N. Walsh, I. Jacobs, Editors, W3C Recommendation, 15 December 2004, http://www.w3.org/TR/2004/REC-webarch-20041215/ . Latest version available at http://www.w3.org/TR/webarch/ .
RFC3987
Internationalized Resource Identifiers (IRIs), Duerst, Suignard, January 2005.
RDF-MT
RDF Semantics , P. Hayes, Editor, W3C Recommendation, 10 February 2004, http://www.w3.org/TR/2004/REC-rdf-mt-20040210/ . Latest version available at http://www.w3.org/TR/rdf-mt/ .

8.2 Informative References

REST
Representational State Transfer (REST) , R. Fielding, Ph.D. dissertation, 2000, Latest version available at http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm .

CVS History

 
$Log: Overview.html,v $
Revision 1.1  2010/01/27 16:24:13  bertails
sparql

Revision 1.38  2010/01/25 17:26:47  apollere2
changed status linki for IPP.

Revision 1.37  2010/01/25 16:55:45  apollere2
changed pointer to WG.

Revision 1.36  2010/01/25 16:48:19  apollere2
Changed URI to example.org.

Revision 1.35  2010/01/25 16:46:28  apollere2
changed link to WG.

Revision 1.34  2010/01/25 16:35:14  apollere2
fixed small validation error.

Revision 1.33  2010/01/25 16:34:25  apollere2
Added mentions of the group, requests for feedback, etc.

Revision 1.32  2010/01/25 15:31:14  bertails
~ fix based on Ian's suggestion (re: pubrules checker)

Revision 1.31  2010/01/24 15:16:23  apollere2
fixed broken anchor.

Revision 1.30  2010/01/24 15:12:39  apollere2
Fixed last validation error.

Revision 1.29  2010/01/23 03:17:20  cogbuji
- Final updates in preparation for publication (summary of updates, toc, etc..)

Revision 1.28  2010/01/22 02:17:46  apollere2
Added no-endorsement and patents boilerplate.

Revision 1.27  2010/01/22 02:12:04  apollere2
Made the date concrete.

Revision 1.26  2010/01/19 15:08:26  cogbuji
XHTML validation fixes

Revision 1.25  2010/01/19 15:00:57  cogbuji
Fix to make consistent use of language regarding URIs resolvable and otherwise that are request uris or embedded.  Updated diagrams, added a diagram for indirect reference via embedded URI

Revision 1.24  2010/01/12 15:10:11  cogbuji
references to percent-encoding and percent-decoding for new query component interface

Revision 1.23  2010/01/12 13:37:34  cogbuji
Added clause to also describe non-dereferencable URIs as motivation for the ?graph=.. interface

Revision 1.22  2010/01/12 07:04:08  cogbuji
From Lee's review
- editorial clarifications
- fixes to samples

Revision 1.21  2010/01/12 06:26:15  cogbuji
Incorporated changes suggested in review (http://lists.w3.org/Archives/Public/public-rdf-dawg/2009OctDec/0660.html) - mostly related to use of ?graph=uri, and fixes to SPARQL Update language snippets.

Revision 1.20  2009/12/14 20:16:51  cogbuji
updates to address comments from Leigh Dodds

Revision 1.19  2009/10/21 01:52:56  lfeigenb
fixed link

Revision 1.18  2009/10/21 01:37:45  lfeigenb
more pubrules prep

Revision 1.17  2009/10/21 01:34:53  lfeigenb
pubrules prep

Revision 1.16  2009/10/16 20:58:07  cogbuji
css validation icon

Revision 1.15  2009/10/16 20:56:48  cogbuji
more pubrules fixes

Revision 1.14  2009/10/16 20:51:32  cogbuji
validation icon added to bottom

Revision 1.13  2009/10/16 20:49:53  cogbuji
move pub-rules fixes (XHTML WFormedness)

Revision 1.12  2009/10/16 20:48:44  cogbuji
XHTML strict profile fixes

Revision 1.11  2009/10/16 20:40:32  cogbuji
various pub-rules related fixes

Revision 1.10  2009/10/16 20:25:10  cogbuji
well-formedness issueas

Revision 1.9  2009/10/16 19:54:46  cogbuji
added references, fixed a few things

Revision 1.8  2009/10/12 16:50:11  cogbuji
incorporated comments from  DAWG members regarding proxies, and POST semantics

Revision 1.7  2009/10/06 16:09:51  cogbuji
Updates per feedback from AndyS: http://lists.w3.org/Archives/Public/public-rdf-dawg/2009OctDec/0004.html

Revision 1.6  2009/09/29 01:50:43  cogbuji
updated model diagram and updated use of terminology

Revision 1.5  2009/09/28 22:27:04  cogbuji
updated language regarding granularity

Revision 1.4  2009/09/28 22:25:29  cogbuji
no-op to test log directive

  

Valid XHTML 1.0 Strict

Valid CSS!