Format comparison
| Format | Example | Precision | Common source |
|---|---|---|---|
| Unix seconds | 1763311200 | 1 s | POSIX, most databases |
| Unix milliseconds | 1763311200000 | 1 ms | JavaScript, Java Date |
| ISO 8601 / RFC 3339 | 2025-11-16T14:00:00Z | Configurable | JSON APIs, OpenAPI |
| RFC 2822 | Sun, 16 Nov 2025 14:00:00 +0000 | 1 s | Email, HTTP Date header |
| SQL timestamp | 2025-11-16 14:00:00 | Microseconds | MySQL, PostgreSQL |
| Excel serial | 46037.583333 | 1 day | Spreadsheets |
Which format should you choose?
- For storage and APIs: an integer epoch (seconds or milliseconds) or ISO 8601 with an offset. Pick one and document the unit.
- For logs: ISO 8601 with milliseconds and an explicit offset, so humans and machines can both read it.
- For user interfaces: localize at render time; never store a localized string.
- For email headers: RFC 2822 is the required format.
- For SQL: use the database's timezone-aware type if it has one; otherwise store UTC explicitly.
Precision traps
Mixing units is the most common timestamp bug. A seconds value multiplied by 1000 twice lands in the year 56000; a milliseconds value divided by 1000 once lands in 1970. A second class of bug comes from truncating fractional seconds: two events in the same second become indistinguishable.
RFC 3339 allows an arbitrary number of fractional digits, but many parsers accept only 3 (milliseconds) or 6 (microseconds). If interoperability matters, send exactly three digits.
When in doubt, print both the raw number and the ISO string in logs. It makes unit errors obvious at a glance.
Formatting tokens you will meet
| Token | Meaning | Example |
|---|---|---|
| %Y | Four-digit year | 2025 |
| %m | Zero-padded month | 11 |
| %d | Zero-padded day | 16 |
| %H:%M:%S | 24-hour time | 14:00:00 |
| %z | Numeric offset | +0000 |
| %Z | Zone abbreviation | UTC |
| yyyy-MM-dd'T'HH:mm:ssX | Java pattern | 2025-11-16T14:00:00Z |