Abstract
Proposed resolution to the app:updated/app:edited problem. Tim says we need to get consensus before anything goes in to the spec regarding app:edited
This uses the app:edited element but introduces the concept of a "synchronization feed" ordered by app:edited to supplement the collection's primary feed ordered by atom:updated
Status
Proposed
Rationale
-
I *think* we've all agreed that, for at least some editing clients, there are problems inherent in always sorting by atom:updated.
-
I *think* we've all agreed that having some form of app:edited element is very useful
-
Where we've disagreed is on whether or not collections MUST (or SHOULD) be sorted by app:edited.
-
The key problem with requiring collections to be sorted by app:edited is that use of app:edited would not be mandatory and that for many (if not a majority) of APP collections, app:updated would equal app:edited.
-
There is also a fundamental problem with requiring that collections always be ordered by app:edited in that it could cause significant usability problems with large collections. For instance, suppose I want to bulk update the members in my collection (e.g. I want to update a bunch of category elements). If I apply those updates sequentially starting with the first entry in the collection feed and working back, when the update is complete, the sort order of the collection will have "flipped", with the most recently modified but least recently created entries listed first. Another editor comes along and wants to pull up the 10 most recently created entries and they end up with entries that were created a year ago whose only difference is a changed category element. To find the ten most recently created entries, they have to look for a "last" link relation or worse have to walk through a bunch of feed pages until they reach the final page in the set. Personally, I think the "get me the ten most recently created or significantly updated entries" is going to be far more common than the "get me the ten most recently edited entries regardless of significance". IMHO, We should be optimizing for the most common case.
-
Note that sorting by app:edited also impacts APP collection feeds that are also used as subscription feeds. We have several of these in production already and I suspect there will be more. Flipping a collection for insignificant changes could cause significant usability problems for several of our subscription clients.
-
PaceAppEdited does not define what it means to "edit" an entry. If I change the namespace prefix used or add insignificant whitespace to an entry, have a "edited" it? Does any change that would lead to a different ETag or Last-Modified header value for the Member URI constitute an "edit" (keeping in mind, of course, that in some systems, touching a file without making any modifications to it could cause the Last-Modified and ETag values to change).
-
PaceAppEdited recommends a default sort order based on what is essentially an optional (but strongly recommended) property value without defining what happens if that value is not specified. Such underspecification could lead to significant interop problems down the road.
Proposal
10. Listing Collections
Collection resources MUST provide representations in the form of Atom
Feed documents whose entries represent the Members in the Collection.
Each entry in the Feed Document SHOULD have an atom:link element with
a relation of "edit" (See Section 11.1).
Clients MUST NOT assume that an Atom Entry returned in the Feed is a
full representation of a Member Entry Resource and SHOULD perform a
GET on the URI of the Member Entry before editing.
10.1 Collection Sort Order
The entries in the collection's Atom Feed MUST be ordered by their
"atom:updated" property, with the most recently updated entries
coming first in the document order.
Clients SHOULD be constructed in consideration of the fact that
certain types of changes to an entry might not alter its atom:updated
value and will not affect the position of the entry in a collection.
It is the responsibility of the server to determine what constitutes a
"significant" change as discussed by Section 4.2.15 of [RFC4287]
although the server can allow the client to specify the value of
atom:updated.
10.2 The "app:edited" Element
Ordering collections by atom:updated means that some modifications
to a collections members might not be readily apparent to some
editing clients that require finer-grained notification of when an
entry has been modified in ways that the server considers insignificant.
To address the needs of such clients, the entries in the collection's
Atom Feed SHOULD contain an app:edited element.
appEdited = element app:edited ( atomDateConstruct )
The "app:edited" element is Date construct as defined by [RFC4287]
whose value indicates the most recent instant in time when an entry
was edited, including when it was created. For the purposes of this
specification, an entry has been "edited" only if the value of any of its
elements or attributes have changed or, in the case of media
link entries, a linked media resource has been modified in any way. This
definition purposefully excludes superficial modifications to an entries
XML infoset such as using a different namespace prefix and adding or stripping
insigificant whitespace.
Entries MUST NOT contain more than one app:edited element.
10.3 Synchronization Feeds
A collection MAY choose to offer an additional Atom feed listing its
member entries sorted by their "app:edited" property with the most
recently edited entries coming first in the document order. Such feeds
are called "Synchronization Feeds" to reflect their intended use as a
reliable means of detecting and coordinating all modifications to a collections
membership regardless of their "significance".
Every entry in the Synchronization Feed MUST contain an app:edited element
and MUST otherwise meet all of the requirements of the collections primary feed.
The availability of a Synchronization Feed is advertised within the
collection's primary feed using a link element with a rel attribute value of
"sync" as in the following example.
<feed xmlns="http://www.w3.org/2005/Atom">
...
<link rel="self" type="application/atom+xml"
href="http://example.org/collection/feed" />
<link rel="sync" type="application/atom+xml"
href="http://example.org/collection/feed?o=edited" />
...
</feed>
10.4 Collection Paging
...
11.3 The "sync" Link Relation
This specification adds the value "sync" to the Atom Registry of Link Relations
(see section 7.1 of [RFC4287]). The value "sync" specifies that the value of
the href attribute is the IRI of a Synchronization Feed as described by
Section 10.2. The meaning of a "sync" link relation appearing anywhere other
than within an atom:feed element is undefined. An atom:feed MUST contain no
more than one "sync" link relation.
