What Should a Protocol Say About Timestamps?
From the earlier reference collection. Read the current software blog.
A timestamp needs a defined representation, time zone, precision, and event meaning before different systems can interpret it consistently.
Specify the representation
A protocol should define the timestamp syntax rather than rely on an example alone. State whether it uses a calendar date and clock time, whether a UTC offset is required, and which separators and fractional-second forms are allowed. If the protocol uses a standard textual format, name it and describe any restrictions the protocol adds.
Time zone information matters because a local clock reading such as 09:15 does not identify a unique instant. It could refer to different places or dates, and local clocks can shift when daylight-saving rules change. A timestamp with an explicit offset, or one defined as UTC, lets systems compare instants without guessing the sender’s location.
Define precision and rounding
Tell readers whether seconds are required and whether fractional seconds are allowed. A system that stores milliseconds may truncate a value supplied with finer precision; another may round it. If comparisons, signatures, or ordering depend on the value, inconsistent precision handling can cause confusing mismatches.
For example, if a service accepts fractional seconds to three decimal places, it should state whether 12:30:00.123 is valid and what happens to a value with six fractional digits. It should also define whether a timestamp denotes an exact instant or a coarser observation whose precision is limited. Avoid implying that a precise-looking string guarantees a precise measurement.
Name the event being timed
A timestamp field should say what event it represents. created_at might mean when a client formed a request, when a server first received it, or when a record was committed. Those moments can differ during delays or retries. A precise field description might say “the server time at which this record was committed,” giving consumers a consistent interpretation.
For sensor readings, distinguish the time of observation from the time the reading reached the service. For scheduled events, distinguish a planned time from an actual departure or arrival. If both are useful, give them separate names rather than overloading one field.
Explain ordering and uncertainty
Do not rely on timestamps alone to establish a total order unless the protocol guarantees a shared clock and sufficient precision. Two events may have equal timestamps, and device clocks may be inaccurate. If order matters, define a sequence number or other ordering rule alongside the time value.
A strong timestamp definition answers four questions: how it is encoded, which time basis it uses, how precise it is, and which event it describes. It may also state how invalid or out-of-range values are rejected. These details make timestamps useful data instead of ambiguous strings that each implementation must interpret independently.