The best of <time>s

(Article updated to correct some typos noticed by commenters, and clarify some aspects.)

Avid HTML5 watchers will know that the <time> element was dropped from HTML, then re-instated, with more New! Improved! semantics.

As before, you can put anything you like between the opening and closing tags – that’s the human-readable bit. The machine-readable bit is contained within a datetime attribute. Dates are expressed YYYY-MM-DD.

Previously, you could only mark up precise dates. So, 13 November 1905 could be expressed in HTML <time datetime="1905-11-13"> but November 1905 couldn’t be. This is a problem for historians where sometimes the precise date isn’t known.

Now, “fuzzy dates” are possible:

As before, times are expressed using the 24 hour clock. Now, you can separate the date and time with a space rather than a “T” (but you don’t have to). So both of these are valid:

You can localise times, as before. Appending “Z” to the timezone indicates UTC (a way of saying “GMT” without it being comprehensible to normal people). Otherwise, use an offset:

Durations

In New! Improved! HTML5 <time>, you can represent durations, with the prefix “P” for “period”.

The datetime attribute “D” for days, “H” for hours, “M” for minutes and “XQ” for seconds. Just kidding – that’s “S”.

You can separate them with spaces (but you don’t have to). So <time datetime="P4D"> is a duration of 4 days, as is <time datetime="P 4 D">.

Using a “T” after the “P” marker allows you to be more precise: <time datetime="PT23H 9M 2.343S"> is a duration of 23 hours, 9 minutes and 2.345 seconds.

Alternatively, you can use a duration time component.

Whichever you choose, it’s represented internally as a number of seconds. Because of this, you can’t specify a duration in terms of months, because a month isn’t a precise number of seconds; a month can last from 28 to 31 days. Similarly, a year isn’t a precise number of seconds; it’s 12 months and February sometimes has an extra day.

You still can’t represent dates before the Christian era, as years can’t be negative. Neither can you indicate date ranges. To mark up From “21/02/2012 to 25/02/2012″, use two separate <time> elements.

pubdate

The pubdate attribute (a boolean that indicates that this particular date is the publication date of the parent <article> (or, if there is none, the whole document) is currently missing from the W3C version of the spec, but is still current in the WHATWG version. Its status is unclear to me (but I’m still using it).

Update 10 August 2012: in response to a query, I checked again and pubdate is gone from both the WHATWG and W3C specs.

46 Responses to “ The best of <time>s ”

Comment by Masklinn

Because of this, you can’t specify a duration in terms of months, because a month isn’t a precise number of seconds; a month can last from 28 to 31 days. Similarly, a year isn’t a precise number of seconds; it’s 12 months and February sometimes has an extra day.

That paragraph is an issue, because — thanks to leap seconds — no duration other than the second (and its SI derivatives) is a precise number of seconds. From the minute up, if it falls across a leap seconds all your computations are thrown off.

Technically, all durations (other than the second) are and should remain context-dependent.

Comment by Tantek

problem for historians … “fuzzy dates”

Bruce, you mention “problem for historians” but “historians” were not the use case that justified the addition of these additional granularities.

“fuzzy” is more imprecise than intended by these features – “fuzzy dates” is a separate proposal that does not (yet) have sufficient research/justification for adoption: http://wiki.whatwg.org/wiki/Time_element#Fuzzy_dates – it’s also something that can potentially be solved with multiple use-cases. More research/brainstorming welcome at that wiki section.

The use-cases that did justify the time element additions were the ability to mark up typical blog archives (years, or year-months), and birthdays/anniversaries (month-day) – both of which are very easily found/documented on the web (frankly, far more sites than “historian” references to dates on the web).

What would be a good use case for such markup?

Jason, you can find use cases for all the various enhancements to the time element on the WHATWG time element wiki page:

http://wiki.whatwg.org/wiki/Time_element

including specifically for duration:

http://wiki.whatwg.org/wiki/Time_element#duration

if it falls across a leap seconds [sic] all your computations are thrown off

Masklinn, in practice, software (even operating systems) don’t care nor compute leap seconds. With all due respect, this is a largely theoretical handwringing concern. If you actually believe otherwise, petition Apple, Microsoft, those who work on Linux, etc. to care about leap seconds. I look forward to seeing your documentation of their responses.

Bruce, a few errata:

<time datetime=”1905-11″> means November 1905

This appears to be repeated in the initial list.

<time…<

In the durations paragraph, the time markup uses < instead of a > in a few places.

You still can’t represent dates before the Christian era, as years can’t be negative.

There haven’t been a critical mass of research/proposals for BCE dates. There have been some mention of BCE dates as potential use-cases for alternate calendar scales but those haven’t garnered sufficient broad interest/research/justification either. If you think the time element should be expanded to somehow markup BCE dates, please add a section on the WHATWG wiki page and document URLs of examples/use-cases on the web, along with a simple proposal (hopefully simpler than alternate calendar scales which aren’t even supported by typical calendar programs, and are likely to be too complex/involved for web authors to use in practice).

pubdate attribute … statis [sic] is unclear

Currently I’ve got a change proposal to drop it for a number of reasons and I encourage you to take a look. Feedback encouraged!

http://www.w3.org/wiki/User:Tantekelik/drop_pubdate

Comment by Bruce

Thanks for pointing out the errors, Tantek – a pre-proofed version sneaked out into the wild.

“historians” were not the use case that justified the addition of these additional granularities”.

- Perhaps. But it’s the use-case that most interests me (specifically, family trees)

“You still can’t represent dates before the Christian era, as years can’t be negative.”

- and I’m not sure if it’s necessary, given that you can’t really compare ancient dates with modern ones due to calendar changes. There’s the year zero problem, too. But, as I said above, my interest is modern history; people interested in ancient history may disagree with me.

Comment by Matt Machell

This is a really welcome improvement!

We do a lot of work with library catalogues and archive data at work. That data gets messy with regards to dates very quickly and any improvements to handling fuzzy stuff in TIME will be greatly appreciated as it’ll mean we can actually use it.

We have things like: An item detail display for an ebook version of a book first published in about 1507 by an author maybe born in circa 1485. Bib data is full of that stuff and you won’t often find it on the open web as lots of library catalogues are legacy systems without stable urls (we’re one of the exceptions).

Comment by Ian

For representing dates that are BCE (Before Common Era), the datetime definition could contain ‘BCE’ to indicate a date that is such. If it’s not present (as in most cases), then naturally ‘CE’ is assumed.

Also, to get around the year 0 problem: “Using these two calendar eras [CE and BCE] as historians use them means that there is no year 0 or negative year numbers” (Dionysian “Common Era”).

Comment by Tantek

Thanks for the updates Bruce!

Perhaps. But it’s [history] the use-case that most interests me (specifically, family trees)

I strongly encourage you to contribute your real-world use cases (i.e. history / family-tree related stuff you’ve published on the web) to the ongoing research being performed for both genealogy and history related microformats:
* http://microformats.org/wiki/history-examples
* http://microformats.org/wiki/genealogy-examples
Even if we don’t get historical/fuzzy dates in the time element, we may be able to develop microformats for publishing such information, which might help strengthen the case for more time enhancements in the future.

Comment by Francesco

I love the improved <time>!

Shouldn’t be a “T” after the “P” in the duration datetime attribute? I seem to understand so from the spec… or is it optional, maybe?

Comment by Andy Mabbett

All these claims of “insufficient broad interest/research/justification”, with no quantification of what exactly constitutes “sufficient”…

Also, sadly, I wouldn’t put much faith in talk of genealogy or history microformats, given the dearth of development of other microformats, and lack of answer to questions about the above issue, in recent years.

Comment by Evan

WTF is the point of this tag? What’s next, tags for <person> or <building> or <plant> or <animal> ? It’s a bit obsessive.

Comment by Australian Poliglot

I can finally publish articles in the past or the future. Could be useful for scheduled automatic releases or just to keep things orderly.

Otherwise this is a major way of abusing time sensitive facts.

Comment by Joe in Australia

Our present calendar was reformed in 1582 but not all countries accepted it at the same time: the UK accepted it in 1752, but Greece and Turkey held out until 1923. If we refer to a date during this period do we implicitly mean “the date that would have been used if the Gregorian Calendar had been adopted”, even though this is not the date that will appear on documents of the period? Or will we have to specify a particular location? And since adopting the reforms meant “losing” at least ten days to bring the calendar into line with the Solar year, will it be illegal to specify a date inconsistent with the calendar for that location?

Comment by egino

Hi Bruce,
I was wondering what I could use in case of multiple date values eg.

From 21/02/2012 to 25/02/2012

Thanks for your invaluable help,
egino

Comment by Steve Williams

Thanks for a great summary Bruce!

The new period option sounds perfect for events that last more than a day. I’ll incorporate into a current project that has a mix of single day and short courses of a few days duration.

Plus it’s one less named class since styling can use the element :)

Comment by Vas

Like egino in comment 24 I was wondering what the best way to mark up things like:

*) This was in place for 2004-2005
= the full years 2004 + 2005

*) The snow was bad in the winter 1963/64
= the winter at the end of 1963 and
the beginning of 1964

*) The castle was built 1270-1275
= started sometime in the year 1270 and
completed in the year 1275
Cheers
Vas

Comment by Mikey

I’ve been using the pubdate attribute too, but now it no longer validates through the W3C. Doing a bit of time value edits this morning as a result.

Comment by Bruce

@francesco “Shouldn’t be a “T” after the “P” in the duration datetime attribute?” – yes, it should (or “D”). Have amended the article; thanks for spotting it.

@Barış, “Wait… <datetime> .. That’s a typo, right?” – a typo; corrected. Thanks for spotting it!

@evan “WTF is the point of this tag? What’s next, tags for <person> or <building> or <plant> or <animal> ? It’s a bit obsessive.”

Depends on what you’re doing. Arguably, different elements for paragraph, ordered list, unordered list, articles are “a bit obesssive” if all you do is post images on tumblr. Why not just a <text> element and be done with it?

@Joe – the different adoptions of gregorian/ julian calendars is very well discussed in PPK’s post Making <time> safe for historians.

@egino, @vas there is no way to mark up a range of dates. Use different <time> elements for the start and end dates. As two people asked, I’ve addressed that it the revised article, too.

Comment by Andy Mabbett

To mark up From “21/02/2012 to 25/02/2012″, use two separate elements

Note that some microformats (and microdata) cater for this with start/ end date (“dtstart”/ “dtend”) or birth/ death date (“bday”/ “dday”) classes, which can be applied to the two dates as appropriate (death date is in the new vCard 4.0 spec, though not yet written into hCard, but should be used anyway; as done on Wikipedia, for example)

Comment by HTML | Pearltrees

[...] Bruce Lawson’s personal site  : The best of <time>s Avid HTML5 watchers will know that the element was dropped from HTML, then re-instated , with more New! Improved! semantics. As before, you can put anything you like between the opening and closing tags – that’s the human-readable bit. [...]

Comment by Christian Ready

Um…I’m confused! Is pubdate no longer valid? I don’t understand why it wouldn’t be there as it makes so much sense!

Comment by Ben Knight

I <3 semantics but I'm lazy. Is there any real tangible benefit to marking up all of my dates, periods, etc like this? If not, wake me up when there is.

Comment by Henry

Building a little site for friends, a fuzzy date was just what I wanted for something happening sometime next January. But the W3C validator report doesn’t like
&lt;time datetime="2013-01"&gt;January 2013&lt;/time&gt;.
I’m not going to lose sleep over this, but any thoughts?

Comment by RobIII

I am curious how &lt;time datetime=&quot;1905-W21&quot;&gt; will be interpreted. Weeknumbers are, unfortunately (as with many date/time related stuff) not agreed upon on how to number:

There are mutually equivalent descriptions of week 01:

• the week with the year’s first Thursday in it (the formal ISO definition),
• the week with 4 January in it,
• the first week with the majority (four or more) of its days in the starting year, and
• the week starting with the Monday in the period 29 December – 4 January.