W3C

SPARQL 1.1 Uniform HTTP Protocol for Managing RDF Graphs

W3C Working Draft 1 June 2010

This version:
http://www.w3.org/TR/2010/WD-sparql11-http-rdf-update-20100601/
Latest version:
http://www.w3.org/TR/sparql11-http-rdf-update/
Previous version:
http://www.w3.org/TR/2010/WD-sparql11-http-rdf-update-20100126/
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

Added clarification regarding the difference between the POST method in this protocol and the SPARQL Update protocol. Updated POST semantics to better distinguish the insert and 'add to container' usecases. Added editor's note about knowing network-manipulable dataset URI a priori. Added section Resolving Relative References regarding resolution of relative URIs against a Base URI. Added references to other specifications. Updated and clarified terminology section adding: Graph Store, and Graph IRI. Updated protocol model diagram and clarified relationship between graph IRI, networked RDF knowledge, RDF document, and RDF graph. Fixed broken SPARQL Update examples.

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. Graph Management Operations
  6. Conditional Requests
  7. Security Considerations
  8. References

1 Introduction

This specification applies the HTTP protocol semantics in managing and modifying RDF graphs. It emphasizes a clear separation between a RDF graph management action from the networked body of RDF knowledge identified as the target of the action, 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.

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].

This document is closely related to the following specifications:

2 Terminology

The following terminology is used in this document:

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. A compliant implementation of this specification SHOULD accept HTTP requests directed at its dataset and handle them as specified by this protocol with the exception of security considerations such as those discussed in section 7 and others (DOS attacks, etc.)

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 has a representation that serializes that graph (or, more precisely: by an RDF document of the 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 a URI in this way, we are not directly identifying an RDF graph but rather the networked RDF knowledge that is represented by an RDF document, which serializes that graph. Intuitively, the interpetation [RDF-MT] of the RDF graph serialized by the RDF document can be thought of as the networked RDF knowledge itself.

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
Figure 1: A diagram of the protocol model for direct graph references.

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., when dereferenced, it does not produce a RDF graph representation). 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 graph IRI can be embedded within the query component of the request URI:

   GET /rdf-graphs/employees?graph=http%3A//www.example.org/other/graph HTTP/1.1
   Host: example.com
   Accept: application/rdf+xml
   

In the example above, the embedded graph IRI (http://www.example.org/other/graph) is percent-encoded [RFC3986], indirectly identifying RDF triples to manipulate. 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. The diagram below illustrates this.

Protocol model diagram for indirect manipulation
Figure 2: A diagram of the protocol model for indirect graph references.

4.3 Resolving Relative References

[RFC3986] defines the process of resolving a relative URI reference within a context. Implementations of this protocol MUST obey the rules specified there regarding the resolution of relative URI references. So, for example, the following HTTP request will result in a response with the RDF document that serializes the RDF graph whose graph IRI is http://example.com/rdf-graphs/employee/1:

   GET /rdf-graphs/service?graph=employee/1  HTTP/1.1
   Host: example.com
   

This is a result of the fact that the next applicable level of precedence designates the base URI to be the URI used to retrieve the representation (5.1.3 Base URI from the Retrieval URI) [RFC3986].

Similarly, the following HTTP request would trigger the update of the graph whose graph IRI is http://example2.com/rdf-graphs/employee/1:

    PUT /rdf-graphs/service/?graph=1  HTTP/1.1
    Host: example.com
    <?xml version='1.0' encoding='UTF-8'?>
      <rdf:RDF
        xml:base='http://example2.com/rdf-graphs/employees/' 
        xmlns:rdf='...'>
        ...
    </rdf:RDF>   
    

This is a result of the fact that the next applicable level of precedence designates the base URI from within the embedded RDF/XML document (indicated in bold)

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. For operations involving a payload (PUT and POST), the server MUST parse the RDF payload according to media type specified in the Content-Type header (if provided in the request).

Developers of implementations of this protocol should refer to [RFC2616] for additional details of appropriate behavior beyond those specified here. This section only serves to emphasize the behavior specific to the manipulation af networked RDF knowledge.

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 GRAPH <graph_uri>;
    CREATE GRAPH <graph_uri>;
    INSERT DATA { GRAPH <graph_uri> { .. RDF payload .. } }
   

Note that the DROP expression is not 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 SHOULD 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 GRAPH <graph_uri>
    CREATE GRAPH <graph_uri>   
   

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.

    INSERT DATA { GRAPH <graph_uri> { .. RDF payload .. } }
    

Alternatively, if the request URI identifies the underlying network-manipulable RDF dataset, the origin server SHOULD create a new RDF graph comprised of the statements in the RDF payload and return a designated graph IRI associated with the new graph. The new graph IRI should be specified in the Location HTTP header along with a 201 Created code.

This scenario is useful for situations where the requesting agent either does not want to specify the graph IRI of a new graph to create (via the PUT method) or does not have the appropriate authorization to do so. If the graph IRI does not identify either a networked-manipulable RDF dataset or networked RDF knowledge, the origin server should respond with a 404 Not Found.

How would a client come to discover the URI of the network-manipulable RDF dataset?

In order for a client to be able to leverage this alternative behavior of the POST method, it would need need to know the URI of the network-manipulable RDF dataset a priori. The Service Description document provides an RDF vocabulary term (sd:Dataset) that can be used in statements about a SPARQL Dataset, however, it is not clear what URI the client can use to request such a service description that provides the URI of the network-manipulable RDF dataset (typed as an instance of sd:Dataset)

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 References

8.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 .
SPARQL-UPDATE
SPARQL 1.1 Update , S. Schenk, P. Gearon, Editor, W3C Working Draft, 26 January 2010, http://www.w3.org/TR/2010/WD-sparql11-update-20100126/ . Latest version available at http://www.w3.org/TR/sparql11-update/ .

CVS History

 
$Log: Overview.html,v $
Revision 1.2  2010/06/01 17:48:03  bertails
(bertails) Changed through Jigsaw on edit.w3.org

Revision 1.1  2010/06/01 15:41:01  lfeigenb
initial checkin

Revision 1.48  2010/05/25 18:17:51  lfeigenb
small pub fixes, added pub date

Revision 1.47  2010/05/20 20:44:51  cogbuji
yet another validation fix

Revision 1.46  2010/05/20 20:43:50  cogbuji
another XHTML validation fix

Revision 1.44  2010/05/20 20:40:04  cogbuji
various pubrules related fixes

Revision 1.43  2010/05/20 19:46:38  cogbuji
switch to WD template and added change summary in SOTD section in prep for publication

Revision 1.42  2010/05/18 13:26:48  cogbuji
Cleaned up language regarding alternative container POST behavior, broken SPARQL Update Language syntax, and added an editorial note about discovering the network-manipulable RDF dataset URI.  Updated diagram

Revision 1.41  2010/05/17 23:30:00  cogbuji
fixed double numbering of outline

Revision 1.40  2010/05/17 23:22:09  cogbuji
Updates in response to Greg's review:

http://lists.w3.org/Archives/Public/public-rdf-dawg/2010AprJun/0164.html

Revision 1.39  2010/03/08 19:44:36  cogbuji
Removed two editorial notes, added (to section 5) a sentence addressing handling of Content-Type headers (so there should not be anymore ambiguity about handling different kinds of payloads)

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!