Unapproved and INCOMPLETE DRAFT

OSLC Core Guidance: Partial Update

Use cases & goals

The goal of this guidance is not to invent a universally applicable scheme for partial update, but instead to meet these specific use cases on an OSLC Defined Resource:

• Adding property-values of any value-type
• Deleting property-values from a resource
• Updating values in a resource

And, to meet these specific goals:

• 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
• Provide an alternative to "Link Collections" -- a pattern we are avoiding in OSLC specs

Recommendation for partial update

Sticking to our use cases and goals we can keep partial update simple. We limit what we support just to the operations we can support without specifying a query language, path language or diff-patch mechanism and this is enough to support our use cases and meet our goals.

Until recently, there was no standard way to achieve partial update of web resources. Now there is an IETF Proposed Standard titled "PATCH Method for HTTP" http://tools.ietf.org/html/rfc5789 which introduces a new HTTP verb called PATCH. This guidance recommends that OSLC services 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.

Because the PATCH method is not yet implemented in many web servers, OSLC clients will use the HTTP POST method to apply a patch.

When applying a PATCH to a resource, 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 an OSLC service does not support PATCH on a resource, then it SHOULD respond with HTTP 501 (Not Implemented).

Limitations

To simplify guidance and implementations, this document:

• Limits recommendations to the four use cases above
• Places some limitations on the SPARQL Update syntax that is required by provider implementations
• Limits Partial Update operations on a resource: they apply only to property-values of the one resource targeted for update
• Llimits PATCH documents to contain at most one SPARQL Update command.

The PATCH Document

To use HTTP PATCH, a service 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. We spell out the use cases below and the SPARQL Update constructs that can be used to implement them.

1) Add new property values to resource

To add new property values of any value-type to a resource, POST them in an OSLC Add-Patch Document (see below) to the resource URI with HTTP Header X-Method-Override=PATCH. In this case we use the SPARQL Update INSERT DATA command to specify the property values that we wish to add. We specify the subject, predicate and object (A.K.A. resource, property and value) for each.

Examples

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

   PREFIX dcterms: <http://purl.org/dc/terms/>
   PREFIX terms: <http://example.com/ns/terms/>
   INSERT DATA { 
      <http://example.com/files/file1> dcterms:description "This file is quite out of date." .
      <http://example.com/files/file1> terms:status "PENDING" .
   }

OSLC provider implementations that claim support for Partial Update MUST support inserting property-values using the INSERT DATA command as illustrated above.

And here's an example off adding a new dc:contributor value to a file or directory resource with URL of http://example.com/files/file1. Note that the property has a value that is a Local Resource (i.e. 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.

   PREFIX foaf: <http://purl.org/dc/terms/>
   INSERT DATA { 
      <http://example.com/files/file1> dcterms:contributor _:bnode1 .
      _:bnode1 rdf:type <http://xmlns.com/foaf/0.1/person> .
      _:bnode1 foaf:name "Fernando Jones" .
}

OSLC provider implementations that claim support for Partial Update MAY support the addition of only those property-values whose resource (i.e. subject) is the resource being operated on, and thus will not allow update of inlined Resource or Local Resource properties.

2) Deleting property-values from a resource

To delete property-values from a resource, a client will POST a SPARQL Update document (see below) to the resource URI with HTTP Header X-Method-Override=PATCH. In this case we use the SPARQL Update DELETE DATA command, which requires each property-value be identified by subject, predicate ad object (also known as resource, property and value).

Example

Here's an example of what a client would post to remove two property-values a resource at URL http://example.com/files/file1.

   PREFIX dcterms: <http://purl.org/dc/terms/>
   PREFIX terms: <http://example.com/ns/terms/>
   DELETE DATA { 
      <http://example.com/files/file1> dcterms:title "FY 2009 Defect Count Report" .
      <http://example.com/files/file1> terms:status "PENDING" .
      <http://example.com/files/file1> terms:relatedTo "http://example.com/resources/1" .
   }

OSLC provider implementations that claim support for Partial Update MUST support inserting property-values using the DELETE command as described above.

OSLC provider implementations that claim support for Partial Update MAY allow only the the deletion of only those property-values whose resource (i.e. subject) is the resource being operated on, and thus will not allow update of inlined Resource or Local Resource properties.

3) Updating property values

To update values of a link property from a resource, a client will POST a SPARQL Update document (see below) to the resource URI with HTTP Header X-Method-Override=PATCH. In this case we use a SPARQL Update DELETE DATA command followed by an INSERT DATA command to specify the properties to be updated, the old values and the new values. Each value is identified by specifying subject, predicate ad object (also known as resource, property and value). OSLC Partial Update providers MUST treat this form as an update operation and not as a delete operation followed by an insert.

Example

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

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

OSLC provider implementations that claim support for Partial Update MUST support updating property-values using the DELETE DATA and INSERT DATA commands as described above.

OSLC provider implementations that claim support for Partial Update MAY allow only the the update of only those property-values whose resource (i.e. subject) is the resource being operated on, and thus will not allow update of inlined Resource or Local Resource property-values.

That brings us to the end of the guidance. Please provide feedback to the OSLC Core Workgroup mailing-list:

• Mailing List Registration
• Mailing List Archives

Related work

• Jazz Foundation item #10252 - Partial Resource Update
• Jazz Foundation item #101430 - Support for Bulk Operations