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

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.

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

2 Terminology

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)

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.

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:

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.

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:

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:

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

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:

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.

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.

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.

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.