PATCH motivating examples

Sam Ruby:

Spend some time up front specifying the behaviors that you want to address.  In the case of Atom, adding an entry, deleting an entry, adding a category to an entry, fixing a typo in the content are examples of common scenarios.  Feel free to use the Atom wiki for this purpose.

To move the discussion of PATCH forward I've posted some examples on the Atom Wiki. They're good examples because the highlight the problem with coming up with a PATCH format for Atom. The largest of those problems is ordering in Atom. That is:

   <entry xmlns="http://www.w3.org/2005/Atom">
       <title>Atom-Powered Robots Run Amok</title>
       <link href="http://example.org/2003/12/13/atom03"/>
       <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <summary>Some text.</summary>
    </entry>

and

   <entry xmlns="http://www.w3.org/2005/Atom">
       <updated>2003-12-13T18:30:02Z</updated>
       <title>Atom-Powered Robots Run Amok</title>
       <link href="http://example.org/2003/12/13/atom03"/>
       <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
       <summary>Some text.</summary>
    </entry>

are the same even though the <updated> element has moved. You can create a patch format that required the server to always serialize elements the same order. For example, in the first example we could order our elements:

   <entry xmlns="http://www.w3.org/2005/Atom">                #1
       <title>Atom-Powered Robots Run Amok</title>            #2
       <link href="http://example.org/2003/12/13/atom03"/>    #3 
       <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> #4
       <updated>2003-12-13T18:30:02Z</updated>                #5
       <summary>Some text.</summary>                          #6
    </entry>

Then our patch format becomes a matter of sending over the element number, and information on either the updated element value or updated attribute values. For example, to change the summary to "foo" we could send:

{
  "n": 6,
  "value": "foo"
}

But given that order is not significant for Atom we may not want to use that approach.

Once you step outside of ordering you need some other way of addressing the elements and attributes that are changed. Note that relying on an already existing XML technology like XPath doesn't solve the problem. For example, here is a severely elided example from Google Calendar:

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:batch='http://schemas.google.com/gdata/batch'
    xmlns:gCal='http://schemas.google.com/gCal/2005'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.google.com/calenda...ervobk3ng</id>
  ...
  <gd:who rel='http://schemas.google.com/g/2005#event.attendee'
      valueString='Fred Flintstone' 
      email='fred@example.com'>
    <gd:attendeeStatus value='http://schemas.google.com/g/2005#event.invited' />
  </gd:who>
  <gd:who rel='http://schemas.google.com/g/2005#event.organizer'
      valueString='Joe Gregorio' 
      email='joe@bitworking.org'>
    <gd:attendeeStatus value='http://schemas.google.com/g/2005#event.accepted' />
  </gd:who>
  <gd:where />
</entry>

If I wanted to send back a patch to update Fred's gd:attendeeStatus, what XPath would I construct to isolate that element and attribute?

atom:entry/gd:who/gd:attendeeStatus/@value

No, since that will capture both attendees.

atom:entry/gd:who[position()=0]/gd:attendeeStatus/@value

No, since that relies on the ordering of the elements.

atom:entry/gd:who[valueString="Fred Flintstone"]/gd:attendeeStatus/@value

Maybe, but is there any guarantee that valueStrings are unique?

atom:entry/gd:who[email="fred@example.com"]/gd:attendeeStatus/@value

This is right, but how would a generic client know how to construct such an XPath?

I am bringing this up to highlight the questions that need to be answered.

1. Does the patch format work only for base Atom elements?
2. Will it work for any and all extensions?
3. Do we assume that all extensions are order independent?
4. Do we presume that the server can always reconstruct the element ordering?
5. Do we require out-of-band information to use or construct the patch representation?

The gd:attendeeStatus example points out that we either need out-of-band information, i.e. that @email uniquely identifies a gd:who element, or that order is preserved. The only other option is to include "in-band" information that makes constructing patches possible, for example, adding id attributes to each element.