Time values in AtomPub

AtomPub/Atom define a number of time values for feeds and feed entries, I have trouble keeping them straight in my head. The values are:

  • atom:published
  • atom:updated
  • app:edited

Since AtomPub works over HTTP the Last-Modified header is also relevant.

atom:published denotes when the item was first published, atom:updated the time at which the last significant edit was made to the entry, app:edited the time when the entry’s was last edited, and Last-Modified the time at which the HTTP server determines the entity backing the entry was last changed.

So when an entry is first published to a collection, the atom:published, atom:updated, app:edited and Last-Modified values should be all roughly the same. When an entry is subsequently updated the atom:published value should be unchanged, while the other 3 values may change. So why do we need 3 values, would one not suffice ?

Firstly Last-Modified is only available when fetching the entry itself, its not available when the entry is included in a feed. Secondly atom:updated and app:edited have slightly different meanings.

From RFC 4287, section 4.2.15:

The “atom:updated” element is a Date construct indicating the most recent instant in time when an entry or feed was modified in a way the publisher considers significant. Therefore, not all modifications necessarily result in a changed atom:updated value.

What’s a ‘significant’ modification? There’s no definite answer but the general consensus seems to be anything that makes a substantial change to the atom:content element entry, excluding minor edits like typo corrections. Any changes to the other elements of the entry (say adding a new category ) would generally not be considered significant. I expect the user/client to make the determination of when atom:updated should change, not the server (well okay if the server has a set of rules to define a ‘significant change’ it could be empowered to make that determination).

From RFC 5023, section 10.2:

The server SHOULD change the value of this element every time an Entry Resource or an associated Media Resource has been edited.

I would define an edit as any time the octets of the entry change (but I guess this is deliberately left somewhat vague, if the only change were to white space between atom elements would this count as an ‘edit’ ?). So I expect app:edited to change any time a change is made to an entry, even changes to non atom:content elements such as atom:category, atom:author etc. I expect the server to make the determination of when app:edited should change. Put another way I expect app:edited to change every time the ETag of the entry changes.

From RFC 2616, section 14.29:

The Last-Modified entity-header field indicates the date and time at which the origin server believes the variant was last modified.

So on most systems I would expect the Last-Modified header to correlate with the app:edited element. They could be off by a small margin, for example if the AtomPub server persisted the entry octets to a disk file and used say Apache to serve those files then the timestamp of app:edited and the timestamp of the file may well vary. As with app:edited Last-Modified should change every time the ETag of an entry changes. Having said all that app:edited is still a distinct value from Last-Modified.

From RFC 5023, section 10:

The app:edited value is not equivalent to the HTTP Last-Modified: header and cannot be used to determine the freshness of cached responses

In summary atom:updated is a value determined by the user, app:edited is determined by the server, some clients (e.g. a feed reader) will be interested in atom:updated, other clients (e.g. a blog editor) will be interested in app:edited. There is considerable latitude in the selection of an appropriate value for app:edited, some AtomPub servers might always keep it in sync with atom:updated, others with Last-Modified, generally the following should hold true:

atom:published <= atom:updated <= app:edited <= Last-Modified

(Updated 2008/06/27: Replaced links to Atompub draft with links to RFC 5023)