2026-08-29 · 8 min read
- time
- api-design
- timezones
Time bugs often begin with a field whose meaning was never defined. An instant identifies one point on the global timeline, a local date-time describes wall-clock fields, and a date describes a calendar day without an hour or offset.
Converting among those concepts implicitly creates ambiguity. Reliable systems name the concept in the schema, preserve enough information for the product requirement, and test the complete serialization round trip.
Choose the correct representation
For API instants, use a documented ISO 8601 profile with Z or an explicit numeric offset, or use an integer epoch with an explicit unit. For future appointments tied to regional civil time, retain the local fields and IANA zone identifier because a numeric offset alone does not contain future daylight-saving rules.
- Represent date-only values as YYYY-MM-DD, not midnight UTC.
- Name epoch fields with seconds or milliseconds when ambiguity is possible.
- Reject timestamp strings that omit a required zone or offset.
- Document fractional-second precision and truncation behavior.
Preserve the instant through storage
Database timestamp types differ in whether they normalize an instant, preserve an offset, or store wall-clock fields without zone information. Confirm driver behavior with an integration test instead of inferring semantics from a column name.
Compare parsed epoch values at each boundary. Two ISO strings with different offsets can represent the same instant, while two identical local strings can represent different instants in an overlap during a daylight-saving transition.
Separate presentation from transport
Serialize a stable machine representation from the API and format it for a user's locale only in the presentation layer. Do not send a locale-formatted date back through a strict API parser.
- Display the relevant zone when users coordinate across regions.
- Keep logs in UTC while retaining the event's source zone when useful.
- Avoid manual fixed-hour corrections.
- Include invalid and ambiguous local times in calendar tests.
Verify with controlled conversions
Use Flashman's timestamp converter to inspect ISO and epoch forms, JSON formatter to expose numeric versus string fields, diff tool to compare each hop, URL tool for query encoding, and cron helper to preview scheduled wall times. These tools clarify representations; production libraries remain responsible for zone rules.
Build round-trip fixtures around midnight, leap days, daylight-saving gaps and overlaps, negative epochs if supported, maximum precision, and both seconds and milliseconds. Assert the final instant and intended display separately.