Reference · Formats
Timestamp string formats
Pick one canonical wire format per API surface, document timezone rules, and never mix seconds and milliseconds in the same field name without a suffix.
| Format | Example | Typical use |
|---|---|---|
| ISO 8601 / RFC 3339 | 2026-04-22T14:30:00.000Z | REST JSON, PostgreSQL timestamptz, OpenAPI datetime strings. |
| Unix seconds | 1713796200 | Redis TTL, JWT exp when integer seconds, many mobile clients. |
| Unix milliseconds | 1713796200123 | JavaScript Date, Elasticsearch @timestamp in ms mode. |
| HTTP-date (RFC 9110) | Wed, 22 Apr 2026 14:30:00 GMT | Cache-Control / Last-Modified / Cookie expiry attributes. |
| Custom compact | 20260422143000 | Legacy batch files — avoid unless you control readers end-to-end. |
RFC 3339 profile tips
Always include timezone offset or Z for UTC. Prefer sub-second precision only when your clock source justifies it; truncate consistently on write.
// Good: explicit Z "2026-04-22T14:30:00.000Z" // Risky: no offset (ambiguous for local wall times) "2026-04-22T14:30:00"
Naming fields
Pair names with units: createdAtMs, expiresAtS, or use structured objects { seconds, nanos } to avoid silent scale bugs in client parsers.