Which value was actually knowable on a decision date? This sounds basic, but it is one of the most important questions in data work. A polished chart cannot rescue a dataset whose rows, fields, or time meaning were misunderstood.
The idea in one minute
A revision changes a previously reported value, a vintage is the dataset as known at a particular time, and point-in-time retrieval selects only records available by the as-of cutoff.
The safe rule is simple: Filter by availability time first, then select the latest eligible vintage for each observation. This gives you an explanation that another person can inspect instead of a hidden assumption.
A tiny synthetic example
The package uses four deliberately small records so every conclusion can be checked by eye. At the synthetic as-of time 2025-03-15, the April vintage is not yet knowable. The eligible latest value is therefore 102 from the March vintage.
The independent result is as-of 2025-03-15 → value 102, not future value 101. “Synthetic” matters: these values teach the concept; they are not observations from a company, exchange, survey, or market-data provider.
Use the four-stage check
- Inspect. Read the fields and ask what one record represents.
- Declare. Write the schema, grain, time basis, or measurement meaning that the calculation depends on.
- Test. Run a small diagnostic that could expose a contradiction.
- Explain. State both the result and its boundary.
This is intentionally more careful than “load a file and calculate.” It prevents the most dangerous data errors: the ones that return reasonable-looking numbers.
The tempting mistake
Using today’s revised history in an old backtest creates look-ahead bias. The problem is semantic, so more decimal places or faster code will not fix it.
There is also an edge case: Observation date, release date, revision date, and ingestion date may all differ. A good pipeline exposes this state to the reader. It does not quietly select a convenient interpretation.
Try the guided lab
Open the self-contained guided lab. Choose Canonical, Edge, or Failure, then use Step to move from input through declaration, diagnostic, and explanation. The lab starts with useful data, works without a server, supports keyboard controls, and has a deterministic reduced-motion mode.
What this result does not prove
The diagnostic does not prove that the source is representative, error-free, licensed for every use, or fit for an investment decision. It tells you whether the narrow assumption in this lesson survives one explicit check. Unknown metadata is a reason to abstain, not permission to guess.
Optional code verification
Python and TypeScript implementations are included for reproducibility and use the same JSON expectation. They are optional: a nontechnical learner should be able to reach the same conclusion from the table and explanation alone.
Takeaway
Filter by availability time first, then select the latest eligible vintage for each observation. If you can say what the input means, show the check, and name the boundary, your result is ready for the next analytical step.
Enhancement studio: draw, compare, explain
This additive studio does not replace the beginner lesson above. It gives you two more drawings, a decision comparison, and short practice prompts so you can explain the idea without copying a formula or writing code.
Drawing 1 — name, apply, check
Read left to right: name what the data means, apply the narrow lesson rule, then use an independent check. Open the full-size concept anatomy.
Choose the right idea
| Decision | This lesson | Closest next or comparison | Why the difference matters |
|---|---|---|---|
| Main question | A revision changes a previously reported value, a vintage is the dataset as known at a particular time, and point-in-time retrieval selects only records available by the as-of cutoff. | Timestamps, Time Zones, Calendars, and Observation Time | Choose the question before choosing the arithmetic. |
| Safe rule | Filter by availability time first, then select the latest eligible vintage for each observation. | Uses its own input and boundary contract. | Neighboring lessons can use the same numbers but answer different questions. |
| Required check | as-of 2025-03-15 → value 102, not future value 101 | Re-check its own unit, time, denominator, or schema. | A correct answer to the wrong question is still wrong. |
| Stop condition | Using today’s revised history in an old backtest creates look-ahead bias. | Move only when its prerequisites are satisfied. | Unknown meaning is a reason to pause, not to guess. |
Drawing 2 — common-mistake clinic
The left side states the safe interpretation; the right side shows the mistake that often produces a believable but misleading result. Open the full-size mistake comparison.
Explain it back without code
- Name it: What does the first input or observation mean?
Answer: A revision changes a previously reported value, a vintage is the dataset as known at a particular time, and point-in-time retrieval selects only records available by the as-of cutoff. - Choose it: Which rule belongs to this question?
Answer: Filter by availability time first, then select the latest eligible vintage for each observation. - Challenge it: What check could make you stop?
Answer: as-of 2025-03-15 → value 102, not future value 101
If your explanation leaves out the unit, period, denominator, grain, or availability time that the lesson needs, it is not complete yet.
Related concepts and learning handoff
- Governed glossary: revision, vintage, as-of date, point-in-time. Browse the full financial glossary when a term is unfamiliar.
- Continue with: Timestamps, Time Zones, Calendars, and Observation Time.
- Evidence boundary: all displayed numbers remain synthetic teaching data; the drawings do not claim a market observation, forecast, or investment result.
Rendered from the canonical Mermaid sources linked by this article.
Concept flow — D00-F03-A09
ReferencesPrimary sources and evidence notesExpand the source trail, evidence role, and limitations behind the engineering choices.
Expand the source trail, evidence role, and limitations behind the engineering choices.
The lesson uses primary standards, official statistical guidance, or official software documentation. The worked data are synthetic and author-derived.
1. FRED API — Real-Time Periods
- URL: https://fred.stlouisfed.org/docs/api/fred/realtime_period.html
- Accessed: 2026-08-10
- Supports: how a real-time period expresses what data were known during a historical interval.
- Limitations: FRED’s API model is a concrete implementation, not the only possible vintage schema.
- Source role: authoritative definition or implementation reference; no numerical teaching values were copied.
2. FRED API — Series Vintage Dates
- URL: https://fred.stlouisfed.org/docs/api/fred/series_vintagedates.html
- Accessed: 2026-08-10
- Supports: dates on which a series’ values were revised or newly released.
- Limitations: A vintage date alone may not capture a user’s actual ingestion latency.
- Source role: authoritative definition or implementation reference; no numerical teaching values were copied.
Evidence boundary
The sources support definitions and operational cautions. They do not validate a particular investment decision, provider dataset, or legal interpretation. The historical-example decision is not useful for this foundations lesson: a named market dataset would add licensing and point-in-time complications without making the core distinction clearer.
Full dependency-light reference implementations in both supported languages.
import { runTopic as runD00Topic, type D00Input, type D00Output } from "../../../../shared/typescript/d00Engine.ts";
/** Run the canonical D00-F03-A09 calculation. */
export function revisionsVintagesAndPointInTimeAvailability(input: D00Input): D00Output {
return runD00Topic("D00-F03-A09", input);
}
The embedded lab now expands to its full document height, keeping the article as the only scroll surface.