Separate observation, availability and retrieval clocks

Give each clock one job

A monthly observation might describe January while appearing in a February release and being retrieved in March. Labeling all three events January creates future leakage; labeling all three March loses useful information about the measured period. The normalized contract therefore carries observation_date, available_date, availability_basis and retrieved_at separately.

RFC 3339 supplies a timestamp representation with an explicit offset, but syntax alone does not establish the real-world event represented. A valid 2026-03-01T12:00:00Z string can be a retrieval timestamp, a release timestamp or an invented assumption. The field definition and retained evidence must say which one it is.

Walk through a synthetic timeline

Suppose a synthetic January index has value 102.4. A documented daily vintage begins on February 12, and a fixture records retrieval at March 3, 09:15 UTC. Its observation date can identify January, its available_date can be February 12 with a daily-vintage basis, and retrieved_at can be the exact March timestamp.

A February 1 research decision cannot use that value merely because the observation belongs to January. A March 4 replay can use the retained retrieval under an explicitly defined policy. A February 12 intraday replay remains unresolved if the only availability evidence is a calendar date. The timeline is invented to illustrate these separate questions.

Represent the evidence strength

The workbench’s availability_basis values are fred_realtime_date, retrieval_time and sec_filed_date. They identify different evidence, not three equivalent labels for an exact publication timestamp. FRED real-time dates support a daily vintage interpretation; the SEC fixture preserves a filing date; the World Bank fixture conservatively uses retrieval as its availability evidence.

A World Bank response’s lastupdated metadata must not be treated as the release time of every observation in the response. It can describe a broader update context. When no observation-specific release history is supplied, a retained retrieval shows that the integration possessed the value then, while leaving earlier public availability unproven.

Keep source time and system time distinguishable

An integration can also record request start, response receipt and processing completion. These operational timestamps help diagnose latency, but they are not automatically source release times. If a response arrives at 09:15:02 and normalization finishes at 09:15:05, those three seconds concern processing, not a revision to the economic period.

For a synthetic freshness check, a response retrieved at 09:00 and evaluated at 09:20 has twenty minutes of retrieval age. That calculation does not establish that the underlying observation is twenty minutes old. A yearly observation can be freshly retrieved and still describe a year that ended long ago.

Check clock contradictions explicitly. A declared availability date after the recorded retrieval date requires investigation; the workbench rejects that inconsistency. A syntactically valid timestamp cannot rescue an impossible sequence of claimed events.

Design joins around the question

A chart by observation period asks how measurements evolve. A replay by availability asks what could be included under a declared information policy. An operations dashboard by retrieval asks whether collection is running. Use separate indexes or query paths for these questions rather than making one timestamp serve all three.

Retain the source’s precision, time zone and any uncertainty. Do not invent midnight or a familiar release hour to make dates sortable as timestamps. This separation prevents a common category error, but it does not alone guarantee point-in-time research: completeness, revisions, source coverage and the chosen decision cutoff still need independent evidence.

Keep in the decision record

• Observation time, availability evidence and retrieval time answer different questions.
• Use availability_basis to preserve evidence strength.
• A recent retrieval does not make the underlying observation recent.

Source notes

1. RFC 3339 — Date and Time on the Internet: Timestamps, July 2002
2. FRED API V1 — Real-Time Periods
3. World Bank — Indicators API basic call structures

Primary specifications support the interface descriptions. All downloadable response fixtures are synthetic. Access and rights checks are dated in the source inventory.

Continue the analysis