Home Guidelines Datetime Currency i18n Names & Addresses Problems Practical Bits Quality

Simple guidelines for date, time, timezone, and calendar handling



Processing of date, time and time zone data are fundamental operations across most software products. The importance of datetime and timezone handling depends very much on the purpose of the given product. The algorithms and data used are largely dependent of the programming stack plus additional libraries or external data. Calendar systems organize date and time for "social, religious, commercial, or administrative purposes" (http://en.wikipedia.org/wiki/Calendar).

In this document, calendar systems are treated as "materialized views" of date and time. Only minimal attention is given to the display and data entering considerations for user interface artifacts that represent calendars and calendar-based operations, such as scheduling.

24 hour day (see en.wikipedia.org/wiki/Day)
Time: time of day.
Time zone: region of the earth that keeps the same time (for a map, see this time zone map).   
Legal time zone or Legal Entity time zone: time zone used in trading or time-sensitive business transactions that span more than one time zone.
View locale:  think of this as the text and its layout in a program window, following the rules of a certain locale (or just a language). Available in some of the fancier development frameworks.
Formatting locale: the formatting of certain bits and pieces on the screen in accordance with the rules for a certain locale.
You can use a view locale that is different from a formatting locale and, magically, show, for example, text in English but dates in French. Available in some of the fancier development frameworks.           

What's in a timezone name

There are a number of ways to "name" a time zone.

Recommendation: when referring to a time zone use "name" only for official, legal names. Use "display name" or "id" in all other cases.

Problems with the Olson tz implementation

The tz database is a collection of entries by different people using different naming conventions for almost anything. The main problem we can find with tz based timezone libraries is bad naming.

For example, some database systems and other software allow either a correct zone setting (add or subtract a number of hours) or set the time zone implicitly as a "location within a timezone".

SET TIME_ZONE='-05:00';

SET TIME_ZONE='Europe/London';

"Europe/London" is not a timezone

"Europe/London" - and all other entries like it - is a geographic location that can be associated with a timezone offset to identify which timezone the city of London belongs to. Without an offset, an id like this cannot be correctly mapped to a timezone "name". Internal use in software is fine, but exposing these to any end user is not a good idea.

The CLDR, Java and .NET

Unicode.org appears to have recognized the implicit naming problems of the tz. The have chosen "zone" with the attribute "type" for IDs of the kind "Africa/Algiers" and "metazone" for actual timezone names and common abbreviations. The CLDR is at this location: http://cldr.unicode.org/.

The CLDR also contains translations for timezone names and identifiers.
Recommendation: use CLDR translations to get translated ids and zone names for your product if you read timezone ids and names from a file.

Java terminology is as follows: TimeZone.getAvailableIDs() returns the list that includes the continent/city values. The method getDisplayName() returns legal names and offset based values.

For a standard timezone, .NET will show a timezone "name" that matches the displayNames value used in Java. Use .StandardName and .DaylightName to get the respective names.


Coordinated Universal Time (UTC) is the civil standard time that replaced Greenwich Mean Time (GMT). In everyday usage, GMT continues to be used as the "name".  Just listen to the BBC News once to understand.
Issue: end-user is faced with offset displayed with label "UTC", for example, "UTC+1"
Solution: use only "GMT" in end-user ui, for example, "GMT + 1".

User interface requirements

Persistence and transfer requirements

8. Translation considerations

For date, times, time zones and related text (long day of the week, short day, month name, etc.) the best practice is: never send lists to translation. The only exception is when you plan to use the CLDR values. But these can be extracted and translators never need to work on them. You cannot expect unique translations for geographic locations: what is the "name" of a given Chinese city in English?
Think of time zone ids, "names", "names" of weekdays, etc. only as labels. And then remember that you never base programming logic on string matching operations against labels.

MM/DD/YYYY - pattern considerations

This section provides a slightly different take on patterns than many other practitioners have.

Conclusion: it really is more mechanical than you might think, and: know your audience.

The Great Timezone Panic of 2011
The “tz” authors/maintainers Olson and Eggert faced a copyright infringement lawsuit by Astrolabe.  There had been rumors in the industry about “the tz going away soon”, but the bosses kept mum. I read the paperwork and promptly sent a nice email to their lawyer but not the kind you might expect. Instead of focusing on “historic data”, science or fair use, I noted that the parts dealing with international time zones drew on numerous publications from around the world, and that a copyright infringement suit against Olson and Eggert might be a good time to look at how the copyright situation in the “ACS International Atlas” held up.  In other words: the ACS compilation was very likely doing exactly what the new owners accused Olson and Eggert of.
The Electronic Frontier Foundation worked on the issue.  And in all fairness, Astrolabe deserves a thank you.