A literary appreciation of the Olson/Zoneinfo/tz database

You will probably never need to know about the Olson database, also known as the Zoneinfo or tz database. And were it not for my elmcity project I never would have looked into it. I knew roughly that this bedrock database is a compendium of definitions of the world’s timezones, plus rules for daylight savings transitions (DST), used by many operating systems and programming languages.

I presumed that it was written Unix-style, in some kind of plain-text format, and that’s true. Here, for example, are top-level DST rules for the United States since 1918:

# Rule NAME FROM  TO    IN   ON         AT      SAVE    LETTER/S
Rule   US   1918  1919  Mar  lastSun    2:00    1:00    D
Rule   US   1918  1919  Oct  lastSun    2:00    0       S
Rule   US   1942  only  Feb  9          2:00    1:00    W # War
Rule   US   1945  only  Aug  14         23:00u  1:00    P # Peace
Rule   US   1945  only  Sep  30         2:00    0       S
Rule   US   1967  2006  Oct  lastSun    2:00    0       S
Rule   US   1967  1973  Apr  lastSun    2:00    1:00    D
Rule   US   1974  only  Jan  6          2:00    1:00    D
Rule   US   1975  only  Feb  23         2:00    1:00    D
Rule   US   1976  1986  Apr  lastSun    2:00    1:00    D
Rule   US   1987  2006  Apr  Sun>=1     2:00    1:00    D
Rule   US   2007  max   Mar  Sun>=8     2:00    1:00    D
Rule   US   2007  max   Nov  Sun>=1     2:00    0       S

What I didn’t appreciate, until I finally unzipped and untarred a copy of ftp://elsie.nci.nih.gov/pub/tzdata2009o.tar.gz, is the historical scholarship scribbled in the margins of this remarkable database, or document, or hybrid of the two.

You can see a glimpse of that scholarship in the above example. The most recent two rules define the latest (2007) change to US daylight savings. The spring forward rule says: “On the second Sunday in March, at 2AM, save one hour, and use D to change EST to EDT.” Likewise, on the fast-approaching first Sunday in November, spend one hour and go back to EST.

But look at the rules for Feb 9 1942 and Aug 14 1945. The letters are W and P instead of D and S. And the comments tell us that during that period there were timezones like Eastern War Time (EWT) and Eastern Peace Time (EPT). Arthur David Olson elaborates:

From Arthur David Olson (2000-09-25):

Last night I heard part of a rebroadcast of a 1945 Arch Oboler radio drama. In the introduction, Oboler spoke of “Eastern Peace Time.” An AltaVista search turned up :”When the time is announced over the radio now, it is ‘Eastern Peace Time’ instead of the old familiar ‘Eastern War Time.’ Peace is wonderful.”


Most of this Talmudic scholarship comes from founding contributor Arthur David Olson and editor Paul Eggert, both of whose Wikipedia pages, although referenced from the Zoneinfo page, strangely do not exist.

But the Olson/Eggert commentary is also interspersed with many contributions, like this one about the Mount Washington Observatory.

From Dave Cantor (2004-11-02)

Early this summer I had the occasion to visit the Mount Washington Observatory weather station atop (of course!) Mount Washington [, NH]…. One of the staff members said that the station was on Eastern Standard Time and didn’t change their clocks for Daylight Saving … so that their reports will always have times which are 5 hours behind UTC.


Since Mount Washington has a climate all its own, I guess it makes sense for it to have its own time as well.

Here’s a glimpse of Alaska’s timezone history:

From Paul Eggert (2001-05-30):

Howse writes that Alaska switched from the Julian to the Gregorian calendar, and from east-of-GMT to west-of-GMT days, when the US bought it from Russia. This was on 1867-10-18, a Friday; the previous day was 1867-10-06 Julian, also a Friday. Include only the time zone part of this transition, ignoring the switch from Julian to Gregorian, since we can’t represent the Julian calendar.

As far as we know, none of the exact locations mentioned below were permanently inhabited in 1867 by anyone using either calendar. (Yakutat was colonized by the Russians in 1799, but the settlement was destroyed in 1805 by a Yakutat-kon war party.) However, there were nearby inhabitants in some cases and for our purposes perhaps it’s best to simply use the official transition.


You have to have a sense of humor about this stuff, and Paul Eggert does:

From Paul Eggert (1999-03-31):

Shanks writes that Michigan started using standard time on 1885-09-18, but Howse writes (pp 124-125, referring to Popular Astronomy, 1901-01) that Detroit kept

local time until 1900 when the City Council decreed that clocks should be put back twenty-eight minutes to Central Standard Time. Half the city obeyed, half refused. After considerable debate, the decision was rescinded and the city reverted to Sun time. A derisive offer to erect a sundial in front of the city hall was referred to the Committee on Sewers. Then, in 1905, Central time was adopted by city vote.


This story is too entertaining to be false, so go with Howse over Shanks.


The document is chock full of these sorts of you-can’t-make-this-stuff-up tales:

From Paul Eggert (2001-03-06), following a tip by Markus Kuhn:

Pam Belluck reported in the New York Times (2001-01-31) that the Indiana Legislature is considering a bill to adopt DST statewide. Her article mentioned Vevay, whose post office observes a different
time zone from Danner’s Hardware across the street.


I love this one about the cranky Portuguese prime minister:

Martin Bruckmann (1996-02-29) reports via Peter Ilieve

that Portugal is reverting to 0:00 by not moving its clocks this spring.
The new Prime Minister was fed up with getting up in the dark in the winter.


Of course Gaza could hardly fail to exhibit weirdness:

From Ephraim Silverberg (1997-03-04, 1998-03-16, 1998-12-28, 2000-01-17 and 2000-07-25):

According to the Office of the Secretary General of the Ministry of Interior, there is NO set rule for Daylight-Savings/Standard time changes. One thing is entrenched in law, however: that there must be at least 150 days of daylight savings time annually.


The rule names for this zone are poignant too:

# Zone  NAME            GMTOFF  RULES   FORMAT  [UNTIL]
Zone    Asia/Gaza       2:17:52 -       LMT     1900 Oct
                        2:00    Zion    EET     1948 May 15
                        2:00 EgyptAsia  EE%sT   1967 Jun  5
                        2:00    Zion    I%sT    1996
                        2:00    Jordan  EE%sT   1999
                        2:00 Palestine  EE%sT

There’s also some wonderful commentary in the various software libraries that embody the Olson database. Here’s Stuart Bishop on why pytz, the Python implementation, supports almost all of the Olson timezones:

As Saudi Arabia gave up trying to cope with their timezone definition, I see no reason to complicate my code further to cope with them. (I understand the intention was to set sunset to 0:00 local time, the start of the Islamic day. In the best case caused the DST offset to change daily and worst case caused the DST offset to change each instant depending on how you interpreted the ruling.)


It’s all deliciously absurd. And according to Paul Eggert, Ben Franklin is having the last laugh:

From Paul Eggert (2001-03-06):

Daylight Saving Time was first suggested as a joke by Benjamin Franklin in his whimsical essay “An Economical Project for Diminishing the Cost of Light” published in the Journal de Paris (1784-04-26). Not everyone is happy with the results.


So is Olson/Zoneinfo/tz a database or a document? Clearly both. And its synthesis of the two modes is, I would argue, a nice example of literate programming.

58 thoughts on “A literary appreciation of the Olson/Zoneinfo/tz database

  1. This is fabulous stuff, thank you! I’ve been fascinated by the insanities of DST and wider computational chronometry for a while, but never actually looked at the contents of zoneinfo.

    There’s a similar kind of fantasticness in Mark Crispin’s calendar work for the University of Washington IMAP server:

    And for the latest DST silliness: Argentina decided to postpone their switch this year *two days* before it was due to happen:
    (I love Steve Langasek’s comment in particular)

  2. I believe your reference to “Gaza’s” weirdness is inaccurate. The lack of any set rule but a minimum of 150 days of Summer Time (as they call it here) referred to Israel. Since then, rules have been codified and legislated. Summer Time starts, approximately the Thursday night before Passover (this isn’t the complete or exact rule) and ends the Thursday night before Yom Kippur.

  3. The idea of DST as a social construction and cultural force amazes me. The realization that “we just made this up” strikes me anew.

  4. Its thoroughness is a joyful thing. It’s so much more than just a configuration file.

    I added a custom timezone (UTC +15s) to some systems a few years ago and made sure our entry had a characteristically dry explanation of the new silliness.

  5. I’m portuguese and I can add a little context to the small quote about the cranky Portuguese prime minister: We’ve been on GMT in the last 40 years. However, when we joined the EU in 86 there was a movement to place us in CET so that bussiness calls would be easier to schedule. The effect was that it was still night at 8:00AM. This meant that lots of workers actually never saw the daylight outside their office during the winter. So the decision to go back to GMT by that cranky PM was really wellcome by all of us :)

  6. This is my favorite piece, from an older edition of Olson:

    “The most interesting region I have found consists of three towns on the southern coast of Australia, population 10 at last report, along with 50,000 sheep, about 100 kilometers long and 40 kilometers into the continent. The primary town is Madura, with the other towns being Mundrabilla and Eucla. According to the sheriff of Madura, the residents got tired of having to change the time so often, as they are located in a strip overlapping the border of South Australia and Western Australia. South Australia observes daylight saving time; Western Australia does not. The two states are one and a half hours apart. The residents decided to forget about this nonsense of changing the clock so much and set the local time 20 hours and 45 minutes from the international date line, or right in the middle of the time of South Australia and Western Australia. […]”

    1. This “sheriff of Madura” tale seems to perpetuate in Unix circles. This title in Australia belongs to a court official, not a gun-toting policeman and I doubt that Madura has a courthouse, being just a truck stop.

      More to the point, this region is UTC +8:45, not 20:45 hours from the date line. I haven’t heard of time zones being measured from that un-straight line.

  7. I’m not sure if it is in the timezone file, but the best (?) story is about the Swedish Julian->Georgian transitions. Not only did they come up with a weird, multi year transition plan, half way though they forgot about it..

    From Wikipedia:

    “Sweden’s relationship with the Gregorian Calendar was a difficult one. Sweden started to make the change from the Julian calendar and towards the Gregorian calendar in 1700, but it was decided to make the (then 11-day) adjustment gradually, by excluding the leap days (29 February) from each of 11 successive leap years, 1700 to 1740. In the meantime, the Swedish calendar would be out of step with both the Julian calendar and the Gregorian calendar for 40 years; also, the difference would not be constant but would change every 4 years. This strange system clearly had great potential for endless confusion when working out the dates of Swedish events in this 40-year period. To make matters worse, the system was poorly administered and the leap days that should have been excluded from 1704 and 1708 were not excluded. The Swedish calendar (according to the transition plan) should now have been 8 days behind the Gregorian, but was still in fact 10 days behind. King Charles XII recognised that the gradual change to the new system was not working, and he abandoned it.
    However, rather than proceeding directly to the Gregorian calendar, it was decided to revert to the Julian calendar. This was achieved by introducing the unique date 30 February in the year 1712, adjusting the discrepancy in the calendars from 10 back to 11 days. Sweden finally adopted the Gregorian calendar in 1753, when Wednesday, 17 February was followed by Thursday, 1 March. Since Finland was under Swedish rule at that time, it did the same”


  8. So the decision to go back to GMT by that cranky PM was really welcome by all of us :)

    Thanks Paulo. That’s nice to know, and it doesn’t diminish the humor really, does it?

  9. it was decided to make the (then 11-day) adjustment gradually

    And we can totally appreciate the good will behind that decision. And yet, with 20-20 hindsight, so clearly hopeless…

  10. from an older edition of Olson

    I couldn’t find an HTML archive that can be used to trace the evolution of the document. Is there one?

    1. There isn’t an “HTML” archive, no, but the complete archive of the tz mailing-list (going back to 1986) is available from ADO’s server (ftp://elsie.nci.nih.gov/pub/tzarchive.gz). Robert Elz maintains an archive of historical tzdata releases, but I can’t figure out where it is at the moment.

  11. Its thoroughness is a joyful thing. It’s so much more than just a configuration file

    Joyful is exactly the right word. I would love to interview Arthur Olson and Paul Eggert sometime.

  12. I believe your reference to “Gaza’s” weirdness is inaccurate.

    The table I showed is from the current edition of the file. But that comment is a historical note which has been followed by /many/ later entries. Including:

    From Paul Eggert (2007-09-20):
    My understanding is that Gaza and the West Bank disagree even over when the weekend is (Thursday+Friday versus Friday+Saturday), so I’d be a bit surprised if they agreed about DST. But for now, assume they agree. For lack of better information, predict that future changes will be the 2nd Thursday of September at 02:00.

  13. If you’re interested in the calculation of time, then run and grab a copy of Calendrical Calculations by Nachum Dershowitz and Edward Reingold.

    I discovered this book while browsing through the ‘other’ section of a technical bookstore about 15 years ago. Everything you ever wanted to know about calculating time. And I see on Amazon that they have a new edition out as well.

  14. Another interesting, though certainly shorter, read is the GNU Units database. On your system, if you have units installed, you can find it in /usr/share/misc/units.dat.

  15. I’m not surprised that the two maintainers are such passionate experts that they document everything. The lead guys in all technical endeavours are of this type. It is the long list of contributors that has me surprised. A boring pedantic task in many cases, TZ data being made lively by such volunteer reports is plain awesome. As much to the 2 (or more) hermits, so also credit to the volunteers!

  16. Small world. I had to do much of the programming at the Mount Washington Observatory regarding timezones. It is surprisingly difficult to ask a computer to tell you if the timezone you are in is currently observing daylight saving time. The servers never followed DST, so the traditional date functions couldn’t tell me if everyone else in the Eastern Timezone was. I figured out I had to probe the tz files to determine this. The 2007 change to DST was the monkey wrench that forced the solution.

  17. Astrologywizard.com – Website of the Week: July 20, 2012

    “The Time Zone Database is your best source of reference for time zones across the world and for when daylight savings are observed. Besides being adopted by some of the most important computing systems around, if you take the trouble to study the notes behind this reference, you’ll see it is a long way from a dry academic exercise.”

    Astrologers care very much about time zones in their calculations!

  18. Hi Jon, Great article ! A couple of interpretation questions –
    1. How do you interpret Sun>=8 to be ‘second sunday’?
    2. On the next line where Save = 0, why do you interpret it as ‘spend an hour’?

    1. 1. The lowest Sunday that is equal to or greater than 8 (which is the reading of the “Sun>=8” notation) will fall in the range 8-14 inclusive. That is always the “human-readable” term “second Sunday.”

      2. You’ve gone from having “saved” an hour to having no hour saved. Since there’s no opposite to “save” as a verb in the time context, he has borrowed its opposite from the context of money.

  19. This sort of “literate” (a la Knuth) database/document is a perfect example of why I despise the move to XML. The config and app data in the computer world should remain “human readable” — it is the place of computers to accomodate people, not for people to accomodate computers.

    XML data formats are an example of the latter case.

    Yeah… the programmer is going to have to parse the datafile each time, more or less from scratch (less, if he’s clever and follows conventions). But, of course, some human has to be involved incompiling and translating the original data into XML when that is used. (Or programming to parse raw data into XML has to be employed. Often an extra piece of external software. Now that didn’t really save work in the long run… did it?)

    I’d hate to see an XML version of /etc/passwd or /etc/fstab! :O

    The only thing worse than XML config files that comes to mind is … … Microsoft Windows Registry… :O :O


  20. “Of course Gaza could hardly fail to exhibit weirdness”

    The comment is about Israel and the associated “Zion” rule. The main timezone for this rule is Asia/Jerusalem, and it only applied to Asia/Gaza and Asia/Hebron during some years. At the time, as Ephraim Silverberg writes, Israel had no set rule for daylight saving time, but they established one in 2013. Until then Ephraim was receiving announcements about upcoming time changes labelled “for the press” from the Ministry of Interior by fax, usually twice a year. Source: I worked with him for several years.

Leave a Reply to Jon UdellCancel reply