What Makes a Timestamp Unambiguous in JSON?
From the earlier reference collection. Read the current software blog.
Include a complete date and time with either a UTC marker or an explicit offset so clients can place an event on a shared timeline.
Local clock time is not enough
A JSON string such as 2026-10-28T09:30:00 gives a date and a clock reading, but no time zone. It could refer to 9:30 in Los Angeles, London, or another location. A client cannot reliably compare it with another event or convert it for display without additional context.
This becomes especially troublesome around daylight-saving transitions, when a local clock can repeat an hour or skip ahead. An unqualified timestamp leaves multiple possible instants or no clear instant at all.
Include UTC or an offset
Use an ISO-style timestamp that includes Z for UTC, such as 2026-10-28T16:30:00Z, or an explicit offset, such as 2026-10-28T09:30:00-07:00. Those examples identify the same instant while expressing it in different ways. The offset tells a parser how the local time relates to UTC.
Choose one convention for an API where possible. UTC is often convenient for event logs because every record shares a common basis. An explicit offset is useful when preserving the offset supplied with an observation is part of the data’s meaning.
Distinguish event time from other times
A record may have several timestamps: when an event occurred, when a device reported it, and when a server received it. Give these fields distinct names and descriptions. For instance, observed_at should identify the time attached to the measurement, while received_at can describe ingestion time.
For a transit schedule, a service time can follow domain rules that differ from an ordinary calendar timestamp. Do not convert a scheduled service-day value into a generic instant unless the schedule’s date and time-zone context are known. Explain the convention where clients will see it.
Validate the contract
A practical check is to parse sample timestamps in two independent clients and confirm that they identify the same instant. Include a case with a nonzero offset, and reject or flag strings that omit the offset when the field is meant to represent an instant.
Document precision as well: say whether fractional seconds are possible and how many digits are meaningful. A complete timestamp contract prevents client software from silently guessing and keeps sorting, comparisons, and displays consistent.