HistoryViewLinks to this page Revision from: 2013 March 8 | 04:33 pm
This is the revision from 2013 March 8 at 04:33 pmView the current live version of the article.
OSLC_logo.png

Open Services for Lifecycle Collaboration
Partial Update Specification Version 2.0

Status: Working Draft

This Version

Latest Version

PreviousVersion

  • N/A

Authors

Contributors

Table of Contents

Contents

  • Appendix A: Samples
  • Appendix B: Resource Shapes
  • Appendix C: Notices and References
  • Appendix D: Open Items
  • Items needed to close this work
  • Named Graph Approach

  • License

    Creative Commons Attribution License
    This work is licensed under a Creative Commons Attribution License.

    Notation and Conventions

    The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

    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 patch model based on a subset of SPARQL Update http://www.w3.org/Submission/SPARQL-Update, includes recommended PATCH document formats based on existing RDF formats and provides examples of how this approach works. If additional use cases need to be satisfied, a full SPARQL Update solution can be used.

    Terminology

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

    Patch - See Partial update

    Use Cases & Requirements

    Use Cases:

    • Given a URI 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 URI 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 URI for a Test Case resource, I’d like to remove only one blocking defect link whether it exists or not.
    • Given a URI for a ChangeRequest resource, I’d like to update the link label associated with the related test plan link.

    Requirements:

    • Add triples to an existing resource
    • Delete triples from a resource
    • Updating the object of a triple in a resource
    • Update reified statements on links, such as link labels
    • 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

    HTTP PATCH

    Model

    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 status code 405 (Method not allowed). If a server does support PATCH on a resource, then it SHOULD respond to a HTTP OPTIONS operation with at least 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 Partial Update servers MUST treat HTTP PATCH request, on an existing resource identified by the canonical Request-URI, as an atomic modification to that resource. The patch model is limited to web resources that are identified by their URI that maps to the subject of triples. HTTP PATCH of web resource is symmetric with the usage HTTP verbs of GET, PUT and DELETE which operate on a web resource identified by the Request-URI.

    OSLC Partial Update servers MAY choose to allow the creation of new resources using HTTP PATCH.

    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]

    A pre-defined named graph that represents the nodes to match or to insert is sufficient.
    The semantics of the PATCH model are based on SPARQL Update. Namely the subset of SPARQL Update is limited to:

    This model does not handle patching resources across multiple graphs.

    Format

    To use HTTP PATCH a client must provide with the request a PATCH document format that is able convey the change to be match in the partial update. This guidance recommends the use of named graph (quad) formats for the PATCH document. In this way, it does not require a new format or parsers to be created. Some quad formats available include TriG (Turtle-based) and TriX (XML-based).

    Discussion: We got confirmation on this approach previously, question is: Should we require a minimum format for servers to support?

    Proposed RESOLUTION: Since Core 2.0 requires RDF/XML it would make sense that those implementations would use TriX. For Core 3.0 (W3C LDP based), which requires Turtle, it would make sense that those implementations would use TriG.

    Add statements about a resource

    Named graph URI: http://open-services.net/ns/core#insertGraph

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

    OSLC Partial Update servers MUST support inserting triples using the INSERT DATA command as defined by SPARQL Update.

    SPARQL Update mapping

    ToDo: Provide mapping details

    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/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#>.
    <http://open-services.net/ns/core#insertGraph> { 
      <http://example.com/tasks/27> dcterms:description "Need to update Website owners as of May 2012" .
      <http://example.com/tasks/27> ex: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.

    <http://open-services.net/ns/core#insertGraph> { 
      <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" .
    }
    

    Remove statements from a resource

    Named graph URI: http://open-services.net/ns/core#deleteGraph

    To remove statements(triples) from a resource, a client will HTTP PATCH the in Patch Document (see examples below) to the resource URI with HTTP Header `Content-Type: application/x-trig’. In this case we use the SPARQL Update DELETE DATA command to specify the statements (triples) wish to remove.

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

    SPARQL Update mapping

    ToDo: Provide mapping details

    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#>.
    <http://open-services.net/ns/core#deleteGraph> { 
       <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 statement

    To update objects of triples for a resource, a client will send a HTTP PATCH request (see below) to the resource Request-URI with HTTP Header Content-type: application/x-trig or Content-type: application/trix+xml. 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 Partial Update servers MUST support updating triples using the DELETE DATA and INSERT DATA commands as defined by SPARQL Update.

    OSLC Partial Update servers MAY allow only the the update of only those triples who’s subject is the HTTP Request-URI.

    SPARQL Update mapping

    ToDo: Provide mapping details

    Example

    Before PATCH

    TBD
    

    PATCH Document

    @prefix ex: <http://example.com/ns/terms#>.
    <http://open-services.net/ns/core#deleteGraph> { 
      <http://example.com/files/file1> ex:parent <http://example.com/resources/1>.
      <http://example.com/files/file1> ex:favoriteTeam <http://example.com/teams/brazil>.
    }
    <http://open-services.net/ns/core#insertGraph> {
      <http://example.com/files/file1> ex:parent <http://example.com/resources/2>.
      <http://example.com/files/file1> ex:favoriteTeam <http://example.com/teams/paraguay>.
    }
    

    After PATCH

    TBD
    

    Example - update with blank nodes (link label)

    Before PATCH

    @prefix ex: <http://example.com/bugtracker> .
    @prefix oslc: <http://open-services.net/ns/core#> .
    @prefix oslc_cm: <http://open-services.net/ns/cm#> .
    @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
    @prefix dcterms: <http://purl.org/dc/terms/> .
    
    <http://example.com/bugs/2314>
       a oslc_cm:ChangeRequest ;
       dcterms:identifier " 00002314 " ;
       oslc:shortTitle "Bug 2314" ;
       dcterms:title "Invalid installation instructions" ;
       oslc:instanceShape <http://example.com/shapes/defect> ;
       dcterms:description "Invalid installation instructions indicating invalid patches to be applied." ;
       oslc:discussedBy <http://example.com/bugs/2314/discussion> ;
       oslc_cm:relatedChangeRequest <http://myserver/mycmapp/bugs/1235> ,
          <http://remoteserver/mycmapp/defects/abc123> ;
       ex:priority " Medium " ;
       ex:severity " Normal " .
    
    _:b1 dcterms:title "A bad link title";
       rdf:object <http://myserver/mycmapp/bugs/1235>;
       rdf:predicate oslc_cm:relatedChangeRequest;
       rdf:subject <http://example.com/bugs/2314>;
       a rdf:Statement.
    

    Patch document as TriG

    @prefix ex: <http://example.com/bugtracker>. 
    @prefix oslc: <http://open-services.net/ns/core#>. 
    @prefix oslc_cm: <http://open-services.net/ns/cm#>. 
    @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
    @prefix dcterms: <http://purl.org/dc/terms/>.
    
    oslc:deleteGraph { 
    _:b1 dcterms:title "A bad link title";
       rdf:object <http://myserver/mycmapp/bugs/1235>;
       rdf:predicate oslc_cm:relatedChangeRequest;
       rdf:subject <http://example.com/bugs/2314>;
       a rdf:Statement.
    }
    oslc:insertGraph {
    _:b1 dcterms:title "A very good link title";
       rdf:object <http://myserver/mycmapp/bugs/1235>;
       rdf:predicate oslc_cm:relatedChangeRequest;
       rdf:subject <http://example.com/bugs/2314>;
       a rdf:Statement.
    }
    

    Mapped to SPARQL Update

    prefix ex: <http://example.com/bugtracker> 
    prefix oslc: <http://open-services.net/ns/core#> 
    prefix oslc_cm: <http://open-services.net/ns/cm#> 
    prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> 
    prefix dcterms: <http://purl.org/dc/terms/> 
    
    DELETE {?s dcterms:title ?o . }
    INSERT  {?s dcterms:title "A very good link title". } 
    WHERE {
       ?s rdf:object <http://myserver/mycmapp/bugs/1235> .
       ?s rdf:predicate oslc_cm:relatedChangeRequest .
       ?s rdf:subject <http://example.com/bugs/2314> .
       ?s dcterms:title ?o .
    }
    

    After PATCH

    TBD
    

    Example - remove the label

    Before PATCH

    TBD
    

    Patch document as TriG

    @prefix oslc: <http://open-services.net/ns/core#>. 
    @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
    @prefix dcterms: <http://purl.org/dc/terms/>.
    
    oslc:deleteGraph {
    _:b1 dcterms:title "A very good link title";
       rdf:object <http://myserver/mycmapp/bugs/1235>;
       rdf:predicate oslc_cm:relatedChangeRequest;
       rdf:subject <http://example.com/bugs/2314>;
       a rdf:Statement.
    }
    

    Mapped to SPARQL Update

    prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> 
    prefix dcterms: <http://purl.org/dc/terms/> 
    
    DELETE  {?s dcterms:title "My special link title". } 
    WHERE {
       ?s rdf:object <http://myserver/mycmapp/bugs/1235> .
       ?s rdf:predicate oslc_cm:relatedChangeRequest .
       ?s rdf:subject <http://example.com/bugs/2314> .
       ?s dcterms:title ?o .
    }
    

    After PATCH

    TBD
    

    Note: a clever server may decide to remove the additional reification triples if decides there are no other interesting facts that they hold.

    Appendix A: Samples

    (this section is informative)

    See TrackedResourceSet 2.0 Samples

    Appendix B: Resource Shapes

    (this section is informative)

    See TrackedResourceSet 2.0 Shapes

    Appendix C: Notices and References

    Contributors

    • SteveSpeicher (IBM, OSLC-Core Lead)
    • Arthur Ryman (IBM, OSLC-Core)
    • Nick Crossley (IBM, OSLC-Core)

    Reporting Issues on the Specification

    The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Core Mailing List

    Also the issues found with this specification and their resolution can be found at Core Issues.

    License and Intellectual Property

    We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy, and the Workgroup Participation Agreement for this Workgroup.

    References

    Appendix D: 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
    • PATCH’ing link labels (reified statements), how do we do this since we don’t support blank nodes in delete? Proposal: invent new syntax for this use case and not have to support full SPARQL Update Insert/Delete/Where: Agreed to use named graph (quad) format instead. Previous proposal included something like:
    PREFIX ex: <http://example.com/ns/terms#>
    DELETE DATA { 
         [ <http://example.com/tasks/27> ex:relatedTo <http://example.com/resources/1> ]
            dcterms:title "My old link label title".
    }
    INSERT DATA {
         [ <http://example.com/tasks/27> ex:relatedTo <http://example.com/resources/1> ]
            dcterms:title "NEW NEW NEW Link title".
    }
    

    Items needed to close this work

    • resolve all open issues
    • insert rules for mapping to SPARQL Update

    Named Graph Approach

    Idea - use RDF representation itself, to represent the patch format. In order to achieve this, the patch format will be treated like a set of well-known named graphs.

    • oslc:deleteGraph to indicate the graph of triples that should be purged, needs to match exactly
    • oslc:insertGraph to indicate the graph of triples that should be added. Perhaps it would be better to call them *PartialGraph as they are incomplete.

    Pros:

    • This has the outstanding quality of not requiring any new (other than named graph) parsers to accomplish this.
    • Handles blank nodes (to some extent)
    • Meets OSLC’s basic use cases

    Cons:

    • Doesn’t support patching named graphs
    • Doesn’t have a model+syntax for future extension of graph pattern matching

    Category:Supporting Documents


    Categories