Skip to content
Updated tool Plan business days across two countries with built-in public holidays, shared open days, and exports

ISO 8601 Explained: The International Date Format Every Developer Should Use

Why YYYY-MM-DD is unambiguous, how the standard handles weeks, durations, and intervals, and the reasons it powers everything from databases to JSON APIs.

· 10 min read · Gabriel

Writing the date in ISO 8601 format
Table of Contents

The problem ISO 8601 solves

What does 03/04/05 mean? In the United States it is March 4, 2005. In most of Europe it is April 3, 2005. In Japan it is April 5, 2003. This kind of ambiguity has caused failed contracts, missed flights, double-charged invoices, and at least one famous database migration disaster. ISO 8601, first published by the International Organization for Standardization in 1988 and most recently revised as ISO 8601-1:2019 and ISO 8601-2:2019, exists to make all of that go away.

The basic format

The headline rule is simple: write dates as YYYY-MM-DD, always with four-digit years, always largest unit first. The format sorts correctly as a plain string, which is why it is the default in databases, log files, and filenames, and why it is the only date format you should ever store.

Times and combined date-times

Times use 24-hour notation: HH:MM:SS. A combined date and time uses a literal "T" as a separator: 2025-01-25T14:30:00. Time zone information is appended with either a "Z" for UTC or a signed offset like +02:00. So a fully qualified instant looks like 2025-01-25T14:30:00+01:00.

Week dates

ISO 8601 also defines a week-based calendar that many businesses use for fiscal reporting. Weeks start on Monday. Week 1 is the week containing the first Thursday of the year, equivalent to the week containing January 4. A week date is written as YYYY-Www-D, for example 2025-W04-6. This is why some years have 52 ISO weeks and some have 53.

Ordinal dates

A less common but useful format is the ordinal date: YYYY-DDD, where DDD is the day of the year from 001 to 365 (or 366 in a leap year). NASA, meteorologists, and the airline industry use ordinal dates frequently because they make day-of-year arithmetic trivial.

Durations and intervals

ISO 8601 also defines a syntax for durations. A duration starts with the letter "P" (for "period") and uses single-letter designators. Examples:

  • P1Y — one year
  • P3M — three months
  • PT2H30M — two hours and thirty minutes
  • P1Y2M10DT2H30M — one year, two months, ten days, two and a half hours

An interval is two date-times separated by a slash: 2025-01-01T00:00:00Z/2025-12-31T23:59:59Z. A repeating interval prefixes that with R[n]/, where n is the number of repetitions.

RFC 3339: the internet profile

Most internet protocols do not actually use ISO 8601 directly. They use RFC 3339, a 2002 specification by Graham Klyne and Chris Newman that profiles a strict subset of ISO 8601 for use in internet timestamps. RFC 3339 is what JSON APIs, log files, OAuth tokens, and email headers use. Any RFC 3339 timestamp is also a valid ISO 8601 timestamp.

Practical advice for developers

  • Always store timestamps in UTC. Convert to local time only when displaying to a user.
  • Always write four-digit years.
  • Use YYYY-MM-DD in filenames; they sort chronologically without any extra logic.
  • If your API returns a date, return it as an ISO 8601 string in UTC, not as a Unix timestamp.
  • Parse with a real library. Hand-rolled regex parsers eventually fail.
  • Be careful with the ISO week-year. 2024-12-30 is in ISO week-year 2025.

Further reading

  • ISO, "ISO 8601-1:2019 Date and time — Representations for information interchange — Part 1: Basic rules" (2019).
  • Klyne, G. and Newman, C., "Date and Time on the Internet: Timestamps", IETF RFC 3339 (July 2002).

← Back to all articles