TZ History Every time zone change, ever made, explained
#developers #standards #parser

How to Read a tzdb Zone and Rule Line: A Developer's Guide

A step-by-step breakdown of tzdb syntax: Zone definitions, Rule transitions, Link aliases, and AT/UNTIL modifiers.

Published on

The IANA Time Zone Database source distribution consists of plain text files with names corresponding to world regions: northamerica, europe, asia, africa, australasia, southamerica, and etcetera.

Inside these files, civil timekeeping is expressed using three core directives: Zone, Rule, and Link. Understanding this grammar makes reading the database straightforward.

The Zone Line

A Zone block defines the standard offset and DST rule set for a canonical identifier over historical intervals. Consider this simplified definition for New York:

# NAME                  STDOFF  RULES   FORMAT  [UNTIL]
Zone America/New_York   -4:56:02 -      LMT     1883 Nov 18 12:03:58
                        -5:00   US      E%sT    1920
                        -5:00   NYC     E%sT    1942
                        -5:00   US      E%sT    1946
                        -5:00   NYC     E%sT    1967
                        -5:00   US      E%sT

Let’s break down each column:

  1. NAME (America/New_York): The primary identifier. Continuation lines indent with whitespace, omitting the name.
  2. STDOFF (-5:00): The standard time offset from UTC when daylight saving time is not in effect.
  3. RULES (US): The name of a Rule table governing daylight saving transitions, or a fixed offset (e.g. 1:00), or - for no DST.
  4. FORMAT (E%sT): The string format for time zone abbreviations. %s is substituted with the LETTER column from the matching Rule (producing EST or EDT).
  5. UNTIL (1883 Nov 18 12:03:58): The ending boundary for this line. The rule takes effect until this instant, after which the next line governs. The final line has no UNTIL, indicating it applies indefinitely into the future.

The Rule Line

A Rule block defines recurring transition events, such as when clocks spring forward or fall back:

# NAME  FROM  TO    TYPE  IN   ON       AT    SAVE  LETTER
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    2007  max   -    Mar      Sun>=8  2:00  1:00  D
Rule    US    2007  max   -    Nov      Sun>=1  2:00  0     S

The columns specify:

  • FROM / TO: The range of calendar years the rule applies to (max means the current year and all future years; only means a single year).
  • IN: Month of transition (Jan, Feb, Mar, etc.).
  • ON: Day specification. Supported patterns include:
    • Exact day: 6 (the 6th of the month).
    • Relative weekday: lastSun (the last Sunday of the month).
    • Conditional weekday: Sun>=8 (the first Sunday on or after the 8th of the month).
  • AT: The transition clock time. Suffixes denote time types:
    • w or no suffix: Local wall-clock time.
    • s: Standard time (ignoring DST).
    • u or g or z: UTC.
  • SAVE: Offset added to standard time (1:00 for 1 hour of daylight saving, 0 for standard time).
  • LETTER: Variable part inserted into %s of the Zone format string (S for Standard, D for Daylight).

A Link creates an alias from an existing canonical zone or previous link to a secondary name:

Link America/New_York US/Eastern

Links ensure backwards compatibility with legacy zone naming schemes while preserving a single source of truth for calculations.

Browse our Zone Notes to see verbatim historical source blocks and maintainer commentary across the entire database.

Advertisement Space