Time element

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

Granularity

year only

The time element should accept just a year.

ISO8601 syntax

YYYY

use case research

http://microformats.org/wiki/birthday-examples#year_only

Opinions / discussion:

• +1 Faruk (per Bug 7145 - Valid date strings should accept ambiguous inputs, like "2009" or "2007-01") One example is the very common archive view found on most blogs, which contain distinct links or headers for each year, each month per year, and often each date within a chosen or highlighted month. Currently, the <time> element only allows for datetime values as precise as a specific day, e.g. YYYY-MM-DD.
• -1 Hixie - "Without clear use cases, I don't intend to change the spec here." (ibid)
• +1 Tantek (per HTML5 Super Friends Technical Details: time element)
• +1 Andy Mabbett (Per use cases in VCARDDAV & EDTF - see external links)
• +1 Philip Jägenstedt - for marking up release dates on e.g. MusicBrainz where the date is given as YYYY, YYYY-MM or YYYY-MM-DD.
• ...

year month only

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

ISO8601 syntax

YYYY-MM

use cases

Blog/publishing archive pages - see Benward.me, ablognotlimited.com (need specific links to archive pages), http://www.flickr.com/photos/tantek/archives/

output equivalent of <input type="month">, see impedance match new date time inputs above.

Opinions / discussion:

• +1 Faruk (per Bug 7145 - Valid date strings should accept ambiguous inputs, like "2009" or "2007-01") One example is the very common archive view found on most blogs, which contain distinct links or headers for each year, each month per year, and often each date within a chosen or highlighted month. Currently, the <time> element only allows for datetime values as precise as a specific day, e.g. YYYY-MM-DD.
• -1 Hixie - "Without clear use cases, I don't intend to change the spec here." (ibid)
• +1 Tantek I think the blog archives use case (where blogs often link to their archives by a specific month and year) is sufficient to justify adding this capability to the time element. Content hosting sites like Flickr also list archives by specific year/month, e.g. see http://www.flickr.com/photos/tantek/archives/
• +1 Andy Mabbett (Per use cases in VCARDDAV & EDTF - see external links)
• +1 Philip Jägenstedt - for marking up release dates on e.g. MusicBrainz where the date is given as YYYY, YYYY-MM or YYYY-MM-DD.
• ...

year week only

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

ISO8601 syntax

YYYY-WNN

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.

reasoning

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

--MM-DD

use case research

http://microformats.org/wiki/birthday-examples#month_and_day_only

Opinions / discussion:

• +1 Tantek (per HTML5 Super Friends Technical Details: time element)
• +1 "radiz" implied support for --MM-DD with the use case question: "How to use <time> with a date in astrology?" in the article http://html5doctor.com/your-questions-answered-6/
• +1 Andy Mabbett (Per use cases discussed in VCARDDAV & EDTF, e.g. birthdays, wedding anniversaries - see external links)
  • Portable contacts allows this using a "0000" year value.

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.

Simple example:

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>.
</p>

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

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>
  </span>.
</p>

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.

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 
     <time>2010-08-05</time>
  </time>.
</p>

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.

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.
• ...

am pm and coarser time parsing

Right now time values inside a <time> element are required 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 pattern:

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

This proposal expands this to:

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

Where "am" and "pm" mean "am or a.m." and "pm or p.m." with optional leading white-space.

When MM or SS is omitted, infer 00 for them respectively.

Example (uses aforementioned composite time proposal as well)

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

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.
• ...

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 some as-yet-to-be-formulated CALSCALE type.

Opinions / discussion:

• +1 Andy Mabbett (Per use cases in VCARDDAV, EDTF & TEI - see external links)
• …

Fuzzy dates

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

Opinions / discussion:

• +1 Andy Mabbett (Per use cases in "Extended Date Time Format" proposals & TEI - see external links)
• +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.)

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.

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.

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:

• input type="month" - this would be satisfied by the time element year month proposal.
• input type="week" - this would be satisfied by the time element year week proposal.

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

• input type="year" - this would be satisfied by the time element year proposal.
• input type="month-day" - this would be satisfied by the time element month day proposal.

Opinions / discussion:

• +1 Tantek
• ...

Tag

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

External links

Prior discussion

• Dates and coordinates in HTML5 - blog post by Andy Mabbett
  • whatwg mailing list discussion of the above, Feb 2009
  • further whatwg mailing list discussion of the above, Mar 2009
  • Another mailing list thread Mar 2009
  • Spec editor's response to the above threads and further discussion, late Mar 2009
• HTML5 Doctor: The Time Element

Resources

• Extended Date Time Format efforts based at the USA's Library of Congress (Covers unspecific dates; date periods and non-Gregorian dates)
  • EDTF proposals (use-cases)
• vCard Format Specification draft-ietf-vcarddav-vcardrev-11 (latest draft as at July 2010)
  • Section 4.3, date & time
  • Section 5.7, CALSCALE (specifies Gregorian or other (e.g. Julian) calendar)
    • VCARDDAV discussion of CALSCALE
• TEI dates, widely used by archives and libraries to mark up texts, including non-Gregorian ISO8601 & uncertain/ approximate dates
  • TEI dates+times
• ISO 8601 (Wikipedia article)