2026-09-07 · 8 min read
- time
- api-design
- databases
A timestamp representation carries an instant only as precisely as its narrowest boundary. An ISO string may contain nanoseconds while the receiving runtime stores milliseconds, or a database column may preserve microseconds that a JSON number later rounds.
Precision loss can break event ordering, incremental synchronization, expiry boundaries, deduplication, and audit reconstruction without changing the human-visible date or second.
Define one transport contract
Choose a documented ISO 8601 profile with a required offset and bounded fractional digits, or an integer epoch with the unit encoded in the schema and field name. State whether unsupported extra digits are rejected, rounded, or truncated.
- Do not infer epoch units solely from value magnitude.
- Avoid floating-point numbers for exact large epoch values.
- Keep date-only and local date-time values separate from instants.
- Version a contract before changing its unit or precision.
Map every storage and runtime boundary
Inventory parser precision, in-memory type range, serializer behavior, database column type, driver binding, database rounding, replica or export behavior, and UI formatting. Verify these characteristics with executable fixtures for the exact versions in production.
A display can intentionally hide fractional digits while retaining them internally. Keep presentation formatting out of transport and storage comparisons so a cosmetic decision does not destroy information.
Design ordering independently
Timestamps are not guaranteed unique, and clocks on separate machines do not establish a perfect causal order. Add a stable tie-breaker for pagination and deterministic sorting, and use domain sequence numbers or logical clocks when causality matters.
- Preserve every compound cursor component exactly.
- Define behavior for events with equal stored timestamps.
- Measure and monitor clock skew separately from precision.
- Do not add artificial fractional digits to imply accuracy.
Build end-to-end round trips
Use Flashman's timestamp converter to inspect ISO and epoch forms, JSON formatter for string and number boundaries, diff for round trips, units converter for unit changes, and number-base converter for bounded integer fixtures.
Test no fraction, maximum supported fractions, extra digits, values around second and day boundaries, negative epochs if supported, exact database writes and reads, sorting ties, API clients, logging pipelines, and dependency upgrades.