This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.

Unapproved and INCOMPLETE DRAFT

OSLC Core Guidance: Partial Update

Please provide feedback to the OSLC Mailing List.

Introduction

There are many motivating cases for supporting a writable Web, existing approaches have focused heavily on the usage of HTTP PUT as the method for updating resources. As experience has shown, this method for updating resources comes with some significant limitations and performance costs. This has motivated the creation of the IETF Proposed Standard titled "PATCH Method for HTTP" http://tools.ietf.org/html/rfc5789 which introduces a new HTTP verb called PATCH. RFC5789 defines the semantics of the new HTTP verb PATCH but does not endorse a PATCH representation.

Motivated by our use cases and requirements, partial update can be simple. Given a resource URL, triples can be added or removed.

This document recommends to use HTTP PATCH to implement partial update, provides a recommended PATCH document based on a subset of SPARQL Update language http://www.w3.org/Submission/SPARQL-Update and provides examples of how this approach works. If additional use cases need to be satisfied, a full SPARQL Update solution can be used.

Use Cases & Requirements

Use Cases:

  • Given a URL for a Change Request resource, I'd like to add a link to a related test plan. I don't want to remove any existing links and if the link already exists, then do nothing.
  • Given a URL for a Test Case resource, I'd like to replace all the blocking defect links with the set of the defect links I have (from a picked list of existing defects from various providers).
  • Given a URL for a Test Case resource, I'd like to remove only one blocking defect link whether it exists or not.

Requirements:

  • Add triples to an existing resource
  • Delete triples from a resource
  • Updating the object of a triple in a resource
  • Guidance on collision detection (usage of If-Match ETag and 412 responses)
  • Reduce possibility of errors in updates because partial updates are safer than complete replace operations
  • Reduce bandwidth used and load on server because partial updates are smaller

Terminology

Partial update - The HTTP operation to modify only a subset of the triples for a given resource.

Patch - See Partial update

HTTP PATCH

OSLC clients SHOULD use the HTTP PATCH method to apply a partial update. For servers that support partial update but not HTTP PATCH, an OSLC client SHOULD use HTTP POST to send the request to the resource URI and will use the HTTP header X-Method-Override=PATCH to indicate that the patch is a PATCH. If a server does not support PATCH on a resource, then it SHOULD respond with HTTP 405 (Method not allowed). If a server does support PATCH on a resource, then it SHOULD respond to a HTTP HEAD operation with the token value "PATCH" for the response header Allow.

OSLC Partial Update servers MUST treat a single HTTP PATCH request as a single resource update operation and not as independent insert and delete operations.

OSLC clients SHOULD use the HTTP If-Match header and HTTP ETags to ensure it isn’t modifying a resource that has changed since the client last retrieved its representation. OSLC servers SHOULD require the HTTP If-Match header and HTTP ETags to detect collisions. OSLC servers MUST respond with status code 412 (Condition Failed) if ETags fail to match if there are no other errors with the request. [RFC2616]

PATCH Document

To use HTTP PATCH, a server must specify a PATCH document format that is able convey the change to be match in the partial update. This guidance recommends the use of a subset of SPARQL Update language for the PATCH document.

The subset of SPARQL Update is limited to:

Add new property values to a resource

To add new triples to a resource, PATCH them in patch Document (see below) to the resource URI with HTTP Header Content-Type=application/sparq-update. In this case we use the SPARQL Update INSERT DATA command to specify the statements (triples) wish to add.

OSLC server implementations that support for Partial Update MUST support inserting triples using the INSERT DATA command as defined by SPARQL Update.

Example

Here's an example of what a client might post to add new property values of dcterms:description and ex:status to a file or directory resource with URL of http://example.com/tasks/27.

Before PATCH

<http://example.com/tasks/27> <http://purl.org/dc/terms/description> "Need to update Website owners" .
<http://example.com/tasks/27> <http://example.com/ns/terms/status> "OPEN" .
<http://example.com/tasks/27> <http://purl.org/dc/terms/modified> "1996-09-16T08:42:11.265Z" .
<http://example.com/tasks/27> <http://example.com/ns/terms/relatedTo> <http://example.com/resources/1> .

PATCH Document

   PREFIX dcterms: <http://purl.org/dc/terms/>
   PREFIX ex: <http://example.com/ns/terms#>
   INSERT DATA { 
      <http://example.com/tasks/27> <http://purl.org/dc/terms/description> "Need to update Website owners as of May 2012" .
      <http://example.com/tasks/27> <http://example.com/ns/terms/status> "PENDING" .
   }

After PATCH

   <http://example.com/tasks/27> <http://purl.org/dc/terms/description> "Website owners as of May 2012" .
   <http://example.com/tasks/27> <http://example.com/ns/terms/status> "PENDING" .
   <http://example.com/tasks/27> <http://purl.org/dc/terms/modified> "2012-05-21T17:02:13.265Z" .
   <http://example.com/tasks/27> <http://example.com/ns/terms/relatedTo> <http://example.com/resources/1> .

And here's an example of adding a new dcterms:contributor value to a resource with URL of http://example.com/tasks/27. Note that the property has a value that is a blank-node of type foaf:Person. Also note that the subject of some of the triples is not the resource, but instead a blank-node reference.

INSERT DATA { 
   <http://example.com/tasks/27> <http://purl.org/dc/terms/contributor> _:bnode1 .
     _:bnode1 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/person> .
     _:bnode1 <http://xmlns.com/foaf/0.1/name> "Fernando Jones" .
}

Deleting triples from a resource

To delete triples from a resource, a client will PATCH a SPARQL Update document (see below) to the resource URI with HTTP Header Content-type=application/sparql-update. In this case we use the SPARQL Update DELETE DATA command, which requires at least one triple.

OSLC server implementations that support for Partial Update MUST support removing triples using the DELETE DATA command as defined by SPARQL Update.

Since there is not a way to identify blank nodes, deletion of blank nodes is not defined. SPARQL Update could be used to remove blank nodes.

Example

Here's an example of what a client would patch to remove a triple from the resource at URL http://example.com/tasks/27.

Before PATCH

<http://example.com/tasks/27> <http://purl.org/dc/terms/description> "Website owners as of May 2012" .
<http://example.com/tasks/27> <http://example.com/ns/terms/status> "PENDING" .
<http://example.com/tasks/27> <http://purl.org/dc/terms/modified> "2012-05-21T17:02:13.265Z" .
<http://example.com/tasks/27> <http://example.com/ns/terms/relatedTo> <http://example.com/resources/1> .

PATCH Document

PREFIX ex: <http://example.com/ns/terms#>
DELETE DATA { 
   <http://example.com/tasks/27> ex:relatedTo <http://example.com/resources/1> .
}

After PATCH

<http://example.com/tasks/27> <http://purl.org/dc/terms/description> "Website owners as of May 2012" .
<http://example.com/tasks/27> <http://example.com/ns/terms/status> "PENDING" .
<http://example.com/tasks/27> <http://purl.org/dc/terms/modified> "2012-05-21T17:27:42.265Z" .

Updating the object of a triple

To update objects of triples for a resource, a client will PATCH a SPARQL Update document (see below) to the resource URL with HTTP Header Content-type=applications/sparql-update. In this case we use a SPARQL Update DELETE DATA command followed by an INSERT DATA command to specify the triples to be updated, the old triples and the new triples.

OSLC server implementations that support for Partial Update MUST support updating triples using the DELETE DATA and INSERT DATA commands as defined by SPARQL Update.

OSLC server implementations that support for Partial Update MAY allow only the the update of only those triples who's subject is the HTTP Request-URI.

Example

Here's an example SPARQL Update document that changes a couple of links.

   PREFIX ex: <http://example.com/ns/terms#>
   DELETE DATA { 
      <http://example.com/files/file1> ex:parent <http://example.com/resources/1>.
      <http://example.com/files/file1> ex:favoriteTeam <http://example.com/teams/brazil>.
   }
   INSERT DATA {
      <http://example.com/files/file1> ex:parent <http://example.com/resources/2>.
      <http://example.com/files/file1> ex:favoriteTeam <http://example.com/teams/paraguay>.
   }

Related work

Open Items

  • Define method to "wildcard" delete/remove triples. For example triples that just match a subject and predicate. No longer needed, not good use case requiring it. Recommend getting all, putting all in a delete statement and then patching OR using SPARQL Update.
  • Define the transactionality of the set commands, is it important? should the client control it? Specifically, do if a delete operation fails (user doesn't have enough access to perform the operation), do you continue with the insert? Done - rely on SPARQL Update spec for semantics
  • Validate use cases and requirements -- Done
  • Produce better examples that show the resource before and after the patch -- Done
  • Should we support various SPARQL Update format shorthands such as: PREFIX, ",", ";", etc. ? -- Done, just add PATCH
  • With non-RDF repos, ensure that model works with properties like dc:title where occurs=exactly-one (see RTC WorkItems? , CQrecords). What happens when receive: DELETE only (assume it would "null" the value), INSERT only (fail request), DELETE/INSERT (should the DELETE object match exactly before insert? - Yes) -- Done
  • Open Issue: PATCH'ing link labels, how do we do this since we don't support blank nodes in delete?
Edit | Attach | Print version | History: r36 | r34 < r33 < r32 < r31 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r32 - 30 May 2012 - 17:21:39 - SteveSpeicher
 
This site is powered by the TWiki collaboration platform Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback