A date-only availability field cannot answer an intraday question
Use explicit inclusion policies for daily vintage and filing dates without manufacturing release times or claiming unsupported point-in-time precision.
A calendar date supplies less information than a timestamp. If an observation is known only to have become available on a particular day, its availability at a specific hour that day remains uncertain unless another source resolves the timing.
Do not add precision by formatting
Appending T00:00:00Z to a date changes its meaning from a day label to a specific instant. That is not a harmless serialization choice when the field controls a historical cutoff. RFC 3339 distinguishes full dates from date-time values, and an application should preserve that distinction in both storage and interpretation.
The workbench retains daily evidence for fred_realtime_date and sec_filed_date. Neither basis means the underlying value was available at the opening of that calendar day in UTC. A UI should display the day and basis together so a neat timestamp does not imply precision the source did not provide.
A synthetic same-day ambiguity
Imagine a synthetic company fact with filed date 2026-04-15 and a decision cutoff at 2026-04-15T10:00:00Z. The filed date alone cannot establish whether the filing preceded that cutoff. Selecting the fact by date less than or equal to April 15 is a date-granularity policy, not proof of morning availability.
If the decision instead occurs on a later day, the date evidence may support a less demanding comparison under a documented calendar convention, but time-zone and dissemination assumptions still need to be explicit. A date label should never be promoted into a universal UTC bound without knowing how the provider defines that date.
Choose a policy that exposes uncertainty
Possible application policies include excluding same-day date-only records from intraday research, reporting them as ambiguous, or obtaining an independently documented dissemination timestamp. Each policy has a cost. Exclusion may discard usable information; inclusion may admit information not yet known. The choice belongs in the research design before outcomes are examined.
For a synthetic test with three records dated April 14, April 15 and April 16 and an April 15 intraday cutoff, the middle record should exercise the ambiguity path. A test that only checks earlier and later dates misses the exact boundary where false precision enters the system.
The workbench itself accepts calendar-date cutoffs. It demonstrates daily selection, not an intraday exclusion policy. Its same-day conflict check concerns competing values, which is a separate uncertainty from the unknown hour of publication.
Separate period conventions from availability conventions
The World Bank annual fixture maps a year such as 2024 to observation_date 2024-12-31 while retaining observation_period 2024 and period_kind annual. This is an analytical period key. It does not mean the annual value was known on December 31, and it does not turn a year into a measured daily observation.
Its availability evidence is retrieval_time, so a later retrieval date must remain visible. A query filtering observation_date before a historical cutoff only chooses measured periods. It does not demonstrate that those periods’ current values were available at the cutoff or that revisions have been reconstructed.
Test calendar validity and document the limit
A parser should reject impossible dates and avoid host-time-zone conversions that shift a date to the previous day. Preserve date-only strings as dates or equivalent structured values until a policy deliberately relates them to instants. Test leap days, month boundaries and offsets rather than relying on the development machine’s locale.
The output should name the comparison mode: date-level vintage selection, retrieval-based snapshot or intraday evidence with verified timestamps. If the source cannot support the desired mode, report that limitation. Passing a cutoff filter is a software result under declared rules; it is not a blanket certificate that an investment backtest is free of look-ahead bias.
Keep in the decision record
- Keep daily dates as dates until an explicit policy relates them to instants.
- Treat same-day intraday inclusion as unresolved without stronger evidence.
- Period-end keys do not establish release availability.
Source notes
- RFC 3339 — Date and Time on the Internet: Timestamps
- FRED API V1 — Real-Time Periods
- SEC — Accessing EDGAR Data
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
Separate observation, availability and retrieval clocks
Record what a value describes, what evidence supports its availability, and when the integration actually obtained it.
Build an as-of join that explains what it can prove
Join observations to decision cutoffs using availability evidence, revision rules and coverage checks rather than observation dates alone.
Design a normalized record without erasing provider meaning
Specify a small shared observation contract while retaining the provider fields needed to interpret units, periods, availability and revisions.
Version 1 · Published 16 October 2026. Inspect the method · Open the contract lab