Date and time formats, ISO 8601, Unix timestamps, and locale formats
Dates are deceptively complex. The same date can be written as 05/06/2024 (May 6 in the US, 5 June in the UK), 06.05.2024 (June 5 in Germany), 2024-05-06 (ISO 8601, always unambiguous), or 1714953600 (Unix timestamp, seconds since 1970-01-01 00:00:00 UTC). Systems that mix these formats produce data that is silently wrong, a bug that only surfaces when two countries' data is merged, often months after the event.
ISO 8601 (YYYY-MM-DD for dates, YYYY-MM-DDTHH:MM:SSZ for timestamps with UTC timezone indicated by Z) is the universal unambiguous format for data interchange. Use it for database storage, API responses, log files, and any data that crosses system or locale boundaries. Use locale-specific formats only in the final display layer, after parsing from ISO 8601.
| Format | Example | Use case |
|---|---|---|
| ISO 8601 date | 2024-05-06 | Storage, APIs, logs, always unambiguous |
| ISO 8601 datetime | 2024-05-06T14:30:00Z | Timestamps with timezone (UTC) |
| Unix timestamp | 1714953600 | Compact storage, arithmetic, most databases |
| RFC 2822 | Mon, 06 May 2024 14:30:00 +0000 | Email headers |
| US format | 05/06/2024 | Display only, ambiguous outside US |
Timezone handling, UTC and IANA zones
The single most common date bug is storing local times without timezone information. When a user in New York and a user in London both save "meeting at 2pm", the timestamps are 5 hours apart, but if both are stored as bare 14:00 without timezone offset, the data is irrecoverably ambiguous. Always store UTC or store an explicit offset. Convert to the user's local timezone in the display layer only. Use the IANA timezone database format (America/New_York, not EST) because IANA zones account for daylight saving time transitions; abbreviated timezone names like EST are ambiguous and differ between countries.
Related: Number formatter, JSON formatter for API timestamp values.