UserPreferences

PaceDateKarlGuertin


Abstract

There are numerous competing proposals, this proposal attempts to combine two (PaceDateAntoneRoundy and PaceDateAsbjornUlsberg). This proposal attempts to make client implementation as simple as possible while still providing for the most common use cases and leave the rest to extension. It features a producer-defined primary date as well as a sample of other dates that would be useful to know as a consumer.

'UPDATE' Text that has been rescinded is in /slashes/ and text that has been added is in bold. I have rearranged the elements atom:c and atom:d to indicate that atom:c now depends on atom:d rather than vice-versa. I keep the names the same so that discussions in email refer to the correct element.

Introduction

You donít know me, I(Karl) just hopped onto the list yesterday and so Iím entering this date debate from the middle. Itís obvious to me that the argument about dates has been going on at least since the beginning of July, so I propose this with a little trepidation.

It seems to me that the following are more or less agreed upon by the four+ competing date proposals:

I(Karl) come to the table believing the following:

Mixing the above together, I(Karl) get a proposal similar to paceDateAntoneRoundy and PaceDateAsbjornUlsberg but with a different focus (that of there being one primary date and multiple informational ones). I have judiciously dropped all the sorting comments from PaceDateAsbjornUlsberg and instead only provided client requirements where I would be tempted to make a poor design decision. Everything in the NOTE: paragraphs after the section are comments justifying my reasoning. This thinking is heavily influenced by PaceEntryDatesUseCases, for which I've tried to provide mechanisms to cover all cases.

I have never seen a specs document do this, but it would be nice to provide a complimentary document to provide the rationale behind particular standards design decisions. This would allow me as a developer to try to guess the spirit of the standard for cases where behavior is underspecified, hence my inclusion of the Note sections below.

Proposal

Replace sections 3.3, 5.6, 5.7 and 5.8 with the following:

3.3 Date Constructs

A Date Construct is an element whose content is an RFC 3339 Date-Time string [RFC 3339]. Except as otherwise specified, the following additional requirements apply:

Note: Publishers wishing to express additional timestamps beyond those defined below MAY use elements defined by dcterms. dcterms defines [WWW]created, [WWW]valid, [WWW]available, [WWW]issued, [WWW]modified, [WWW]accepted, [WWW]copyrighted, and [WWW]submitted, but defines each in terms of [WWW]W3CDTF. Both W3CDTF and RFC 3339 are profiles or subsets of [WWW]ISO 8601, and in general RFC 3339 is a subset of W3CDTF. Consumers will need to be aware that the dates they find in dcterms MAY be of a lesser precision (e.g., "2004" is a valid W3CDTF date). When elements from the dcterms extension module are present in an Atom feed they SHOULD be expressed using the smaller RFC 3339 profile.

NOTE: directly from PaceAntoneRoundy

5.6 Date Constructs of "atom:entry"

An atom:entry MUST contain an atom:a element. It SHOULD include additional date elements. Refer to section 3.3 Date Constructs for formatting requirements.

5.6.1 "atom:a" Element

The "atom:a" element is a Date Construct indicating a date and time which the publisher wishes to associate with the contents of the entry. Typically, atom:a will be associated with the creation or availability of the resource, but it need not be related to events in the publishing process.

This date SHOULD remain constant for an entry and SHOULD NOT be used as a substitute for the atom:d and atom:c fields.

NOTE: This corresponds to atom:c in PaceDateAsbjornUlsberg and atom:d in PaceDateAntoneRoundy. It is intended for this date to be the most important and the one primarily displayed by clients, hence the requirement for there must be one and only one. It is intended that this would provide for virtually all use cases and be extremely easy to implement. Making the requirements loose on this element allows making the requirements on other fields very tight.

Use cases covered:

  1. newspaper

  2. WWII

  3. normal blog

  4. weather - edge case, does not fit in with the common case of websites and blogs. Here it would probably be most useful for consumers if it were to either act the same as atom:b or as atom:c. This is why the precise semantics of this element are left up to the producer.

  5. Hypothetical Illustrated - covered but not as written, atom:a = hi:created, atom:b = hi:issued, as specified in section 5.6.2

Use cases not covered

  1. Norway News - not covered, exposes publishing process to the world. As a consumer, I don't care. I want to know when your article was atom:b and when it was atom:c. Can be implemented using the dcterms extension mechanism

5.6.2 "atom:b" Element

The "atom:b" element is a Date Construct indicating the date and time that the entry was first published, whether in this or another feed.

atom:entry elements SHOULD contain an atom:created element, but MUST NOT contain more than one.

Publishers MUST NOT change the value of atom:b element over time. If an atom:entry is re-issued at several different locations, atom:b MUST NOT be altered except to correct errors in its value.

Clients MUST NOT depend on this value remaining constant. This is an informational element, not an identification or disambiguating element.

NOTE:

This corresponds to atom:c in PaceDateAntoneRoundy and atom:b in PaceDateAsbjornUlsberg. A created field, e.g. atom:a in PaceDateAsbjornUlsberg causes publishing process to encroach into the feed. If this information must be provided, it can be done so using the dcterms, per section 3.3. The client bit is an attempt to head off bad programming ideas before they get started. I know I'd be tempted to use this as part of a message identifier.

5.6./4/'''3''' "atom:d" Element

The "atom:d" element is a Date Construct indicating the most recent date and time that the entry was altered in any way, with one exception: if external data, such as advertisements, are being incorporated into the entry, atom:d need not be updated when that data changes.

This is the equivalent of a wikipeida "minor edit" and can be used to indicate that the content of an entry has changed, but in an unimportant way. Examples of such changes are spelling or grammar corrections. For data feeds (e.g. weather) it can be used as a confirmation that the data (e.g. forecast) is valid at a point in time after the initial creation date.

atom:entry elements /MAY/SHOULD contain an atom:d element if an existing element is changed after being published. atom:entry elements MUST NOT contain an atom:d element if the entry has not been modified.

If a provider cannot distinguish between significant and non-significant updates, the atom:/c/d element SHOULD be present and the atom:/d/c element MUST NOT be present.

atom:entry elements MAY contain more than one atom:d element. If an atom:entry contains more than one atom:d element, the elements MUST be adjacent and MUST be arranged in reverse chronological order.

NOTE:

this corresponds to atom:b in PaceAntoneRoundy and atom:d in PaceDateAsbjornUlsberg.

5.6./3/'''4''' "atom:c" Element

The "atom:c" element is a Date Construct indicating the most recent date and time when a change was made to the entry which the publisher wishes to bring to the attention of subscribers. Such changes would typically not include minor adjustments like spelling and grammatical corrections.

atom:entry elements /SHOULD/MAY contain an atom:c element if an existing element is changed after being published. atom:entry elements MUST NOT contain an atom:c element if the entry has not been modified.

atom:entry elements MAY contain more than one atom:c element. If an atom:entry contains more than one atom:c element, the elements MUST be adjacent and MUST be arranged in reverse chronological order.

NOTE:

this corresponds to atom:c in PaceAntoneRoundy and (the erstwhile) atom:e in PaceDateAsbjornUlsberg.

I (Karl) believe that it is easier to test for the presence of an element than to inspect the contents of an existing element and determine whether they're applicable. If this element is absent, the consumer can assume the entry has not been updated. Otherwise you have different implementations setting the time to the same as published or epoch or some other random value to indicate the entry has not been updated.

The requirements on the adjacency and order of multiple elements make implementation simpler and are not a great burden on providers. Justification: It is anticipated that the most recent modification is the most significant, if these requirements are in place, this is easy to do both with xpath and with sax.