How Should a Field Reference Explain a Timestamp?
From the earlier reference collection. Read the current software blog.
A timestamp definition should make clear what event it marks, how it is encoded, which time zone applies, what precision is meaningful, and how absence is represented.
Name the event, not just the format
A field reference should first explain what happened at the recorded time. “Timestamp of the observation” is clearer than “date,” but it may still need refinement: does it mark when a sensor sampled, when a device transmitted, or when a server received the reading? Those events can occur minutes apart. A dashboard that uses receipt time to label measurement time can make delayed data appear newer than it is.
Use a field description such as: “Time the instrument recorded the measurement, before transmission.” If the field can represent more than one event depending on the record type, describe that condition. Avoid using a name like created_at as its own definition; readers need the meaning independent of the implementation label.
Specify encoding and zone
Show the representation readers should expect. For example, “ISO 8601 date and time with seconds; examples include 2026-04-03T14:25:10Z.” State whether the value is UTC, carries an explicit numeric offset, or uses a named local time zone. “Local time” alone is ambiguous because daylight-saving transitions can repeat or skip clock times, and different locations observe different rules.
If a source uses a local clock without an offset, disclose that limitation and explain how your project interprets it. Do not silently treat a date-only value as midnight unless that is truly the intended meaning. Where the system stores a normalized form but presents local time, document both: readers should know whether conversion happens in storage, display, or both.
Describe precision and absence
Precision is the smallest meaningful unit, not necessarily the number of digits displayed. A value shown with milliseconds may originate from a clock accurate only to the nearest second. State the source precision or the precision your system preserves, and say whether rounding or truncation occurs. For example, if a reading arrives at second precision and the interface displays milliseconds as .000, make clear those zeros do not represent finer measurement.
Define missing-value behavior explicitly. Does a blank mean unknown, not collected, not applicable, or withheld? Can the field be null, omitted, or represented by a sentinel such as an empty string? These cases affect parsing and interpretation. A useful entry might say, “Null means the source supplied no event time; the record remains usable, but chronological ordering may be unavailable.” Include an example of a valid value and, where relevant, an absent one. This lets readers parse the field and understand what conclusions its timestamp can support.