How Would You Build a Stale-Data Badge?
From the earlier reference collection. Read the current software blog.
A stale-data badge compares an observation timestamp with a chosen freshness limit and explains its status clearly.
Choose the timestamp and the limit
A freshness badge is a small interpretation layer over data that already has an observation time. It should compare that time to a configurable limit and report a clear state, such as “current,” “stale,” or “timestamp unavailable.” The badge does not establish whether a source is accurate; it tells readers how old the represented observation is according to a stated rule.
Define the inputs first: an observation timestamp, the current time, and a maximum age such as 15 minutes. Parse timestamps with their time zones intact. If the observation time lacks a zone, do not silently assume one unless the source format defines it. An ambiguous timestamp can produce a confidently wrong badge.
Calculate age and set boundaries
Compute age as current time minus observation time. If the age is at or below the limit, label it current; if it exceeds the limit, label it stale. State the boundary in the interface so that an observation exactly 15 minutes old has an unambiguous result when the limit is 15 minutes.
For example, with a 15-minute limit and a current time of 12:30 UTC, an observation at 12:20 UTC is current, while one at 12:10 UTC is stale. A timestamp in the future deserves its own status or warning. It may indicate clock skew, a parsing error, or a source that labels forecast values as observations. Hiding that condition inside “current” conceals a useful diagnostic.
Make the badge explain itself
Show both the status and the observation time, ideally with a human-readable age such as “updated 10 minutes ago.” Include the configured threshold somewhere nearby, for example “current; limit 15 minutes.” If the timestamp cannot be parsed or is missing, use wording such as “freshness unknown” rather than presenting a green current state.
The badge can also expose machine-readable status in its markup, but its visible label should remain understandable without color. Pair text with color or an icon so that users who cannot distinguish colors still see the same meaning. Keep the source’s timestamp distinct from the page’s fetch time: downloading an old record now does not make the observation new.
Keep policy configurable and testable
Make the freshness limit a setting tied to the data’s expected cadence. A rapidly changing sensor and a daily report need different thresholds. Avoid implying that one universal cutoff defines stale data; the right limit depends on how often the source is expected to publish and how the information is used.
Test values just below, exactly at, and just above the limit, plus missing, malformed, and future timestamps. Use a fixed reference time in those tests so results do not drift. The finished badge is most useful when it reveals the age rule and the underlying observation time, letting readers judge whether the data is timely for their task.