How Do You Model a Reading and Its Measurement Time?
From the earlier reference collection. Read the current software blog.
Represent a measurement with its value, unit, observation time, and source identity so clients can interpret and trace it.
Keep the measurement’s parts together
A numeric reading alone is incomplete. A useful record associates the value with a unit, the time the observation applies to, and the source or instrument that produced it. Without those fields, 21.3 could be a temperature, a voltage, or a reading from an unknown moment.
For example, a temperature record might include value: 21.3, unit: "Cel", observed_at: "2026-10-28T16:30:00Z", and source_id: "station-17". Each field answers a different question and should have its own documented type and meaning.
Name the relevant time
The measurement time is not always the same as the time a server received or published the record. A sensor may observe a condition at 10:00 and upload it at 10:04. If both times matter, store them separately as observed_at and received_at rather than using an ambiguous field called timestamp.
Use a complete timestamp with UTC or an explicit offset when identifying an instant. If a reading summarizes an interval, include the start and end or a clearly defined interval duration. A daily average is not the same kind of observation as an instantaneous sample.
Identify the source precisely
A source identifier should refer to a documented station, device, or reporting system. If the measurement can be revised, consider including a record identifier or revision so clients can tell whether they have received a correction or a second observation.
Keep provenance separate from the value. The source name may change, and a device may be replaced; a stable source ID plus descriptive metadata gives consumers a better way to trace where a reading came from without embedding all context into one string.
Handle missing and suspect readings
Define what happens when the value is unknown, the instrument is offline, or validation marks a reading as suspect. Use explicit status or quality fields rather than substituting a normal number that could be mistaken for a measurement. Keep unknown distinct from zero, which may be valid for some quantities.
A well-modeled reading can be sorted, compared, converted, and audited without guessing. With value, unit, observation time, and source identity represented explicitly, downstream tools can display the data faithfully and explain its limits.