A January cutoff must not select a February revision
Walk through two synthetic FRED-shaped versions of the same observation and reconcile the value visible at a declared cutoff.
For the synthetic 2024-01-01 observation, value 100 has availability date 2024-01-02 and revised value 101 has availability date 2024-02-02. A cutoff of 2024-01-31 selects 100. Selecting the latest row in the file would introduce the later revision into the earlier snapshot.
Freeze the input before writing the selector
Use a fixture shaped like the selected FRED V1 observations response. Its series is SYNTHETIC_INDEX, with the declared unit index points. Both records describe observation_date 2024-01-01. The first has value 100 and realtime_start 2024-01-02; the second has value 101 and realtime_start 2024-02-02. The fixture retrieval timestamp is 2024-03-15T12:00:00Z. These are invented demonstration values, not an actual economic series or recovered release history.
Keep the observation date, vintage date and retrieval timestamp as separate fields. The observation date identifies the period being described. The vintage date supplies the selected provider-date availability convention. The March retrieval timestamp records this fixture's supposed acquisition context. Backdating retrieval to the observation date would remove information about the dataset's provenance without creating any evidence of earlier access.
| Observation date | Value | Available date | Eligible on 2024-01-31? |
|---|---|---|---|
| 2024-01-01 | 100 | 2024-01-02 | Yes |
| 2024-01-01 | 101 | 2024-02-02 | No |
Filter availability, then choose the eligible version
Normalize the source as fred and record availability_basis as fred_realtime_date. Each row retains a revision key and source-record locator; keep the input payload separately. First exclude rows whose available_date is later than the requested asOf date. Then group comparable observations by their source, series, period and unit, and select the latest eligible version only where its identity is unambiguous.
At asOf 2024-01-31, the February record is excluded before selection, leaving value 100. At 2024-02-02 the revised value becomes eligible under this day-level convention. A cutoff before 2024-01-02 yields no eligible observation. That empty result is different from a numeric zero and different from a failure to download the file. Each condition should have its own explicit result. Retain the selected cutoff with an empty selection so downstream code can distinguish it from an empty source response.
Test the tempting implementation mistakes
An implementation that sorts by observation_date alone cannot distinguish these two versions because their dates are identical. Taking the last array element happens to return 101 for this ordering and fails the January case. Reversing array order should not change a valid selection. Filtering the observation date against the cutoff also fails: both observations concern January, even though one version is available only in February.
Add an adversarial record with the same observation and availability identity but a conflicting value. The contract should surface the conflict and retain enough source information to investigate it. Silently taking the last value transforms input order into a revision policy. Exact duplicates also deserve a visible diagnostic or declared treatment; suppressing them without a trace can hide pagination or replay defects.
State what the successful test proves
The FRED documentation separates observation periods from real-time periods and supports historical vintage queries. This fixture tests one local date-selection rule over supplied candidates. It does not establish that every historical vintage was retrieved, implement every FRED response mode or prove what a particular researcher actually possessed in January. The original input remains necessary for examining additional provider fields and assumptions.
A date has no intraday release time. Passing this example does not justify using value 100 at a particular January 2 trading-session open. An intraday research claim requires verified release timing, timezone and receipt evidence appropriate to that claim. Export the cutoff, normalized rows, availability basis and fixture identity together so another reader can reproduce the narrower result without mistaking it for a complete point-in-time database.
Keep in the decision record
- Filter by availability before selecting a revision.
- A matching observation date does not make a later revision historically eligible.
- Day-level vintage selection cannot establish intraday knowledge.
Source notes
Primary specifications support the interface descriptions. All downloadable response fixtures are synthetic. Access and rights checks are dated in the source inventory.
Version 1 · Published 16 October 2026. Inspect the method · Open the contract lab