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.
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].
The following terminology is used in this document:
- Architectural style - An architectural design perspective that limits a system in order to enduce harmonous behavior
- Representation State Transfer architectural style (REST) - An architectural style for distributed hypermedia systems
- URI - A Uniform Resource Identifier as defined in [RFC3986].
- Resource - A network-accessible data object or service identified by an IRI, as defined in [RFC2616]. See [WEBARCH] for further discussion on Resources.
- Resolvable URI - A URI whose resource has one or more representations available via invoking HTTP GET on the URI as defined in [WEBARCH].
- IRI - An Internationalized Resource Identifier as defined in [RFC3987]. Before an IRI found in a document is used by HTTP, the IRI is first converted to a URI. See Section 4.1.
- Network-manipulable RDF (Dataset) - An RDF dataset used by an implementation of this protocol whose named RDF graphs are the targets of the operations and their
identifiers are resolvable URIs or URIs that can be embedded in the query component of URI in a manner described later in this document
- Networked RDF knowledge - An information resource, identified by the IRI of a graph in a network-manipulable RDF dataset, and managed
by a server that implements this protocol. See [WEBARCH] for further discussion on Resources.
- Semantic (adj.) , semantics (n.). Concerned with the specification of meanings. Often contrasted with syntactic to emphasize the distinction between expressions and what they denote [RDF-MT].
- RDF payload - The representations sometimes included with the body of invokations of the operations defined here as defined in [RFC2616].
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".
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
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
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.
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.
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
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> ]
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.
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
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.
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.
@@Additional input is needed regarding whether specific language (beyond describing the expected behavior) is needed
to determine levels of conformance
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.3 2018/10/09 13:23:03 denis
fix validation of xhtml documents
Revision 1.2 2017/10/02 10:42:15 denis
add fixup.js to old specs
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
