Calendars & leaps
Gregorian rules, leap years, leap seconds, and ISO week dates.
The Gregorian calendar is the civil calendar used in most of the world. Its leap-year rule: a year is a leap year if it is divisible by 4 — except century years (divisible by 100), which are not leap years unless also divisible by 400. So 2000 was a leap year (divisible by 400), but 1900 was not (divisible by 100 but not 400). This rule gives an average year length of 365.2425 days, a very close approximation to the tropical year.
Leap seconds are a completely different concept. UTC is kept aligned to Earth’s rotation by occasionally inserting a one-second correction — the last minute of a day becomes 61 seconds long (23:59:60 exists briefly). Leap seconds are announced by the IERS (International Earth Rotation and Reference Systems Service) with only a few months’ notice and cannot be predicted far in advance. Many systems — including POSIX, JavaScript, and NTP “leap smearing” — ignore or redistribute leap seconds, meaning UTC as implemented is not a pure count of SI seconds. Between 1972 and 2024, 27 leap seconds were inserted.
ISO week dates
The ISO 8601 week date system numbers weeks Mon–Sun, and the ISO week-year can differ from the Gregorian calendar year near the boundaries. A week belongs to the year that contains its Thursday. This means January 1 may belong to the previous ISO year (if it falls Fri/Sat/Sun), and late December days may belong to the next ISO year.
Pitfall: Using %Y (four-digit calendar year) instead of %G (ISO week-year) in a format string when building ISO week-date strings. For dates in the last days of December or first days of January, these two values can differ by one, silently producing wrong ISO week identifiers (e.g. 2015-W53 vs 2016-W53).
Go deeper: proleptic Gregorian, Julian, other calendars, and the leap second debate
The proleptic Gregorian calendar extends Gregorian rules backward before the calendar was adopted (1582 in Catholic countries; later elsewhere). Many programming libraries use the proleptic Gregorian calendar for all historical dates for simplicity, even though historical dates were originally recorded in the Julian calendar (which lacks the century-year exception). The difference accumulates to ~13 days by the 20th century.
The Julian Day Number (JDN) is an unambiguous continuous count of days since January 1, 4713 BCE (proleptic Julian), used in astronomy and some software to avoid calendar system confusion.
The leap second problem: because leap seconds cannot be predicted far in advance and require special handling (a 60 second value), many distributed systems (Google, Amazon, Meta) instead “smear” the leap second — spreading 1 second across a window of hours — so that all their clocks remain strictly monotone. POSIX explicitly ignores leap seconds by defining each day as exactly 86400 seconds, which means a POSIX Unix timestamp is not a pure SI-second count. A 2022 international resolution (CGPM Resolution 4) calls for abolishing the leap second by or around 2035, letting the UTC–UT1 difference grow to a larger tolerance (the exact value is still to be decided) before any correction — likely deferring the first such correction by a century or more.
For how Unix time handles (or does not handle) the second-level timeline, see Unix time.