A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on Chat (such as one of these permanent autoconfirmed members).

Time element

From WHATWG Wiki
Revision as of 22:09, 7 August 2010 by Tantek (talk | contribs) (→‎noon and midnight: i18n question handled in a separate question)
Jump to navigation Jump to search

Research, data, use cases, issues, and enhancements related to the HTML5 time element.

Date granularity

year only

The time element should accept just a year.

ISO8601 syntax
use case research
use cases in VCARDDAV & EDTF - see external links
Wikipedia 'Start date' template - thousands of YYYY instances
Wikipedia infobox with YYYY birthdate (unknown MM-DD)

Opinions / discussion:

year month only

The time element should accept just a year and a month.

ISO8601 syntax
use cases
Blog/publishing archive pages - see Benward.me, ablognotlimited.com (need specific links to archive pages)
whatwg's own mailing list archives (!)
output equivalent of <input type="month">, see impedance match new date time inputs.
use cases in VCARDDAV & EDTF - see external links
Wikipedia 'Start date' template - thousands of YYYY-MM instances
Credit/ debit card expiry dates, entered into, then republished for verification on, e-commerce sites (security concerns prohibit use of example URL)

Opinions / discussion:

year week only

The time element should accept just a year and a week number.

ISO8601 syntax
use case research
no examples in the wild currently. If anyone knows of any sites which publish references to specific weeks of a year, either by name / expression (e.g. "first week of the year") or by specific number (e.g. "weeks 1-26"), please provide URLs and quotes of example content.
output equivalent of <input type="week">, see impedance match new date time inputs above.
to provide the output equivalent of <input type="week">

See impedance match new date time inputs above.

Opinions / discussion:

  • +1 Tantek per good design of impedance matching date time inputs.
  • ...

month day only

The time element should accept just a month and a day.

ISO8601 syntax
use case research
use cases discussed in VCARDDAV & EDTF - see external links
Facebook - allows users to elect to show their birthday as, for example, "17 December", with no year.

Opinions / discussion:

HTML5 internal consistency

impedance match new date time inputs

The time element should be able to represent every granularity of times and dates that the new date time <input> elements allow. Here is a list of all the date time <input> elements along with the corresponding <time> element usage (if applicable)

<input type="date">           - <time>YYYY-MM-DD</time>
<input type="datetime">       - <time>YYYY-MM-DDTHH:MM:SS</time>
<input type="month">          - not supported in current time element
<input type="week">           - not supported in current time element
<input type="time">           - <time>HH:MM:SS</time>
<input type="datetime-local"> - <time>HH:MM:SS-ZZ:YY</time>
New proposed input elements:
<input type="year">           - not supported in current time element
<input type="month-day">      - not supported in current time element

In particular the <time> element is missing support for the following date inputs:

In addition, if the new proposed input elements are accepted, the respective time element support should be added as well:

Opinions / discussion:

Proposals extending scope

Fuzzy dates

The time element should accept fuzzy (uncertain, approximate) dates ("around 18 June 1855" "summer 1970", "circa December 1963", "flourished 1580"), centuries, and eras ("Edwardian", "bronze age", "Jurassic")".

Use cases
1. "... an application that might input Wikipedia data and output an annotated visual timeline. For movements or trends rather than events, it would need to output rough dates and date ranges like 2001-2003, rather than exact dates."[1]
Implemented, see [2], (target site currently broken, but worked previously; a fix is promised shortly), but can only map precise dates, because there is currently no way to mark up fuzzy dates in a machine-readable format. The acceptance of this proposal would allow this implementation and others to map all such dates. Note that the implementation works with any site, not just Wikipedia, by parsing hCalendar microformats.
2. ...

Opinions / discussion:

  • +1 Andy Mabbett (Per use cases in "Extended Date Time Format" proposals & TEI - see external links)
    • Uncertainty possibly resolved by a "certainty" attribute:
      <time datetime="1855-06-18" certainty="3days">around 18 June 1855</time>
      <time datetime="1970-06" certainty="45days">summer 1970</time>
      (with "45days" meaning "+/- 45 days" - in other words, a 90-day window, and similar allowance for year or other ranges; or:
      <time datetime="1963-12" certainty="circa">circa December 1963</time>
      with pre-defined prose values allowed, such as "flourished", "notbefore", "notafter", etc.
  • +1 Jim O'Donnell (Dates such as 'circa 1910' published on Flickr eg. The RNVR Training Ship 'Buzzard'… also a list of fuzzy dates for a set of photos.)
  • 0 (comments) Tantek - Update: the syntax still seems a bit loose/imprecise, however, I appreciate the improvements being made. Some additional changes for consideration:
    • certainty attribute, empty or missing is equivalent to "0" (absolute certainty presumably)
    • certainty attribute takes an ISO8601 duration.
    • alternatively it might make more sense to introduce a compound time structure for ranges such as the use case example of 2001-2003. Here is a strawman markup example (feel free to pick alternative markup, but re-using nested time elements for portions of a range seem useful)
      • <range><time>2001</time>-<time>2003</time></range>

Calendar scale

The time element should accept a calendar scale (CALSCALE; default is GREGORIAN) per (and to facilitate interoperability with) the emergent vCard 4 specification, to allow for the the mark-up of non-Gregorian (e.g. Julian) dates, using one of a set of pre-defined CALSCALE types.


<time datetime="1330-06-01" calscale="julian">1 June 1330</time>

User agents could be instructed to ignore any unrecognised CALSCALE value, treating the contents of the element as plain text for data-processing (but not styling) purposes. This would prevent, for example the processing of the above example by an agent written to deal only with Gregorian dates. (At some point, CSS should recognise CALSCALE, allowing authors to, say, style all Julian dates differently to Gregorian dates.)

Use case research
The Wikipedia timeline example in HTML5 Super Friends Technical Details: time element proposes to map a timeline of dates from Wikipedia (e.g. 2001-2003 Gregorian). However, Wikipedia includes several thousand articles about or referring to pre-Gregorian era events, usually using the Julian calendar, such as the birth and death of Julius Ceaser and, in the same article, the Ides of March (15 March) 44 BC. The existing timeline implementation (see [3] - target site currently broken, but worked previously; a fix is promised shortly) can only map Wikipedia's Gregorian dates, because there is currently no way to mark up Julian dates in a machine-readable format. The use of CALSCALE as suggested would allow this implementation and others to map all of these dates. (Note that the implementation works with any site, not just Wikipedia, parsing hCalendar microformats.)

Opinions / discussion:

  • +1 Andy Mabbett (Per use cases in VCARDDAV, EDTF & TEI - see external links)
  • 0 Tantek - Update: I have mixed feelings about this. On one hand, despite years of the presence of the CALSCALE feature in iCalendar etc., there are no implementations (AFAIK) of non-GREGORIAN CALSCALE values in iCalendar etc. user agents, thus there is no reason to believe that specifying it in HTML5 would actually encourage any other user agents to implement it either. On the other hand the Wikipedia long-term timeline use case does appeal to me so overall I've upgraded my opinion on this from -1 to 0 neutral.

Miscellaneous proposals

Choose different default date

The statement that valueAsDate IDL attribute should return the value 1970-01-01 plus the appropriate time when the time element contains no date creates a problem that there are likely to be time elements that explicitly contain that date.

A better choice would be a value that is highly unlikely to be encountered, and would be implausible as an actual date in most applications, perhaps 9999-12-31.

Opinions / discussion:

  • 0 (comment) Andy Mabbett - 9999-12-31 may well occur in real applications (projected comet sightings, say). Can we return either an invalid date (perhaps 9999-02-31) or an error code?
  • -1 Tantek - I don't see any other default date as being significantly different.
  • ...

Syntax improvements for reducing DRY violations

composite nested time elements

A time element should permit child time elements which may contain only partial date time information which can then be composed into more complete date time information.

This is intended as a cleaner way to provide functionality equivalent to the microformats value-class-pattern date and time values pattern.


Currently the <time> element forces you to duplicate and hide date time information if you want to avoid displaying the not-very-friendly full ISO datetime:

<p class="vevent">
  <span class="summary">I went to the cafe</span> at 
  <time class="dtstart"
        datetime="2010-08-05T18:00:00">18:00 on 2010-08-05</time>.

Note the date and time information is duplicated (violating DRY, placing the content at risk of divergence).

microformats value class pattern DRY advantage

With the microformats value-class-pattern date and time values pattern you could instead mark this up like this:

<p class="vevent">
  <span class="summary">I went to the cafe</span> at 
  <span class="dtstart">
     <span class="value">18:00</span> on 
     <span class="value">2010-08-05</span>

Advantages: no duplication of time and date data! (avoiding DRY violation) If you need to update the info, you only have to update it in one place, thus reducing the chances of inforot.

Disadvantage: the loss of the HTML5 time semantic.

simple nested time example improvement

We'd like to have our time and date time separation as well, so this should work:

<p class="vevent">
  <span class="summary">I went to the cafe</span> at 
  <time class="dtstart">
     <time>18:00</time> on 

summary of updated datetime algorithm

In short: the algorithm for determining the "datetime" of a time element should:

  1. check for an explicit 'datetime' attribute (allowing a local to element override regardless of child elements)
  2. check for nested <time> elements, and if any are found, compose their values into a more complete date and time (use the first date found if any, then the first time found, if any. thus latter dates or times are gracefully ignored)
  3. use the complete contents of the <time> element as its datetime value.

Essentially, step 2 is added to enable composing nested child time elements.

applicability to microdata

All of the aforementioned advantages for microformats apply to microdata use of the <time> element as well. microformats are used in the above examples as that is the type of content (including the value class pattern) that is being published today (e.g. see http://microformats.org/wiki/events - the markup on that page itself).

nested time example with datetime attribute

If the publisher prefers to publish a "localized" form of dates (rather than the previous simple example with the most overall internationally human-friendly/readable YYYY-MM-DD ISODate), they can still do so:

<p class="vevent">
  <span class="summary">I went to the cafe</span> at 
  <time class="dtstart">
     <time>18:00</time> on 
     <time datetime="2010-08-05">August 5th, 2010</time>

Advantage: The advantage here over the current time element is that the DRY violation is limited to only the date information (instead of date and time information), thus reducing the risk of data divergence due to duplication.

nested time example with two datetimes

If the publisher prefers to publish a "localized" form of times, they can do that as well:

<p class="vevent">
  <span class="summary">I went to the cafe</span> at 
  <time class="dtstart">
     <time datetime="18:00:00">6pm</time> on 
     <time datetime="2010-08-05">August 5th, 2010</time>

Advantage: The two separate 'datetime' attributes (containing just the time and just the date) are more human-readable than a single datetime attribute containing both, and thus there is a slightly better chance that the few humans that check would correctly determine whether the times and dates in the datetime attributes represent the same value as the content of the element.

The AM/PM proposal below further helps improve this example.

nested time discussion

Opinions / discussion:

  • +1 Tantek - I'd really like to be able to more cleanly markup dates and times than the best we have been able to do so far with microformats (the aforementioned value-class-pattern), and HTML5 presents us with the potential to do so.
  • -1 Andy Mabbett - Introduces excessive complexity on the apparent assumption that a significant proportion of dates in the wild (or even in microformats in the wild) use the format "2010-08-05" and not more human-readable and accessible prose such as, say, "5 August 2010" or "August 5th, 2010". No evidence (also supposedly required by the microformats "process") has been provided to show that this is the case. {If the apparent assumption is not made, then this fails 80/20.) Update: Subsequent changes have addressed some of my concerns. The proposal to separate times from dates with datetime attributes is a better one. However, we still lack supporting evidence and I object to any wording in the spec which perpetuates the myth that YYYY-MM-DD dates are in any way "human-friendly/readable" compared to prose dates: "international" readability is irrelevant, when pages are otherwise in one language or another.
  • ...

am pm and coarser time parsing

Right now time values inside a <time> element are required to specify hours in 24 hour time.

In our experience with the microformats value class pattern date and time values we've found it is relatively easy to both specify and implement (multiple implementations) parsing of (potentially coarser) am and pm values to permit a broader set of values to marked up directly (rather than with a separate datetime/title attribute).

In short, the current <time> element only allows for the following time syntax:

  • HH:MM:SS - where HH is in 24 hour time.

am pm syntax summary

This proposal expands the allowed time syntax to:

  • HH:MM:SSam
  • HH:MM:SSpm
  • HH:MMam
  • HH:MMpm
  • HHam
  • HHpm

am pm syntax details

  • periods, white-space, case-insensitivity. "am" and "pm" mean "am or a.m." and "pm or p.m." with optional leading ("6 pm") and intermittent ("6 p. m.") white-space; and are case-insensitive ("6 PM").
  • implied 00 minutes and seconds. When :SS or :MM:SS is omitted, infer :00 or :00:00, respectively.;
  • handling of 12am and 12pm. "12am" is treated as "00:00:00" (midnight at the start of the day). "12pm" is treated as "12:00:00" (noon).

simple am pm example

A simple example:

I went to the cafe at <time>6pm</time>.

Advantage: by specifying am and pm times that can be parsed directly from the contents of the

am pm example with nested time elements

Example (uses aforementioned composite nested time element proposal as well)

<p class="vevent">
  <span class="summary">I went to the cafe</span> at 
  <time class="dtstart">
     <time>6pm</time> on 

Advantage: again, this reduces DRY violations, in this case further improving upon the composite nested time elements case.

am pm discussion

Opinions / discussion:

  • +1 Tantek - in practice we in the microformats community have found that enabling users to markup am/pm times leads to many more cases where we can avoid violating DRY and thus encourage greater accuracy over time for such content. I think the HTML5 <time> element presents us with the opportunity to more cleanly markup times (than what we've been able to do with the aforementioned microformats value-class-pattern), and thus we should do so.
  • 0(query) Andy Mabbett - see above for concerns over date formatting.
    • queries moved to am pm FAQ section with answers. - Tantek 16:57, 6 August 2010 (UTC)
  • ...

am pm FAQ

noon and midnight

Question: How does this cater for "noon" and "midnight", and the ambiguity over "12am" and "12pm"?

Answer: This proposal does not address the (English) language specific terms of "noon" and "midnight". Proposal clarified to explicitly treat 12am as 00:00:00, and 12pm as 12:00:00.

am pm i18n

Question: How does this internationalise "am" and "pm", for languages which do not use them?

Answer: For languages that do not use "am" or "pm", the am pm proposal does not confer any additional advantage.

Issues without specific proposals

Specification ambiguities

The specification requires that time be expressed as UTC (or another time zone with a specified offset from UTC). However, the representation of leap seconds is not specified. Further, the algorithms to convert between string and number are flawed, because the number is described as "number of milliseconds elapsed from midnight UTC on the morning of 1970-01-01" but the actual number of milliseconds includes all kinds of strange decisecond offsets during the period 1961-01-01 to 1972-01-01. Also, UTC did not exist before about 1960.

Unix timekeeping has a long history of terrible definitions, and Unix notions of time should be totally rejected and expunged.

External links


Blog posts, Twitter updates etc. may be tagged HTML5time or #HTML5time

Prior discussion