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.