Skip to content

Facts

A fact is a dated statement someone may need to know. Write it so a reader knows what to do differently, not only what is true. Facts appear under project.facts and datasets.<name>.facts.

Fact or do_not? Use a fact when something was learned or decided at a point in time and might change. Use do_not for a rule that is always true for this data.

as_of here is not dates_asof. A fact's as_of is the date the statement was written or decided. The as-of date of a source is which vendor release the data reflects.

Example

facts:
- id: office-incl-flex
  statement: "office includes flex space from 2026Q2: compare office within one side of 2026Q2 only"
  as_of: 2026-10-31
  severity: caution
  columns: [sector]
- id: covid-window
  statement: how to treat 2020-2021 is undecided
  as_of: 2026-10-31
  status: decision-open
  options: [exclude 2020-2021, keep all quarters]
- statement: the 2026Q3 file was re-sent on 2026-11-02
  as_of: 2026-11-02
  expires: 2027-01-31

Definitions

Priority is by severity: a blocker fact is Critical, a caution fact Important, an info fact Useful. The fields that keep a fact true and citable (id, probe, reviewed_by, source) are Useful whatever the severity. See What to write first.

Key Type Required Priority Check Description
facts[].statement string yes by severity - What is true and what to do about it.
facts[].as_of date YYYY-MM-DD yes by severity error if not a date When the statement was written, found true or decided.
facts[].expires date no by severity error if before as_of After this date the fact is no longer shown to agents as current.
facts[].status proposed, reviewed, decision-open, retired no, default proposed by severity error on any other value proposed is shown as unreviewed. The owner sets reviewed, decision-open or retired.
facts[].severity blocker, caution, info no, default info by severity error on any other value How much it matters to a reader.
facts[].columns list of column names no by severity each must be in the data (error) Columns the fact is about.
facts[].options list of string required when status is decision-open, otherwise must be empty by severity error if the rule is broken The open choices: there is no house rule yet, so a reader says which option they used.
facts[].reviewed_by string no Useful - Who reviewed it.
facts[].source string no Useful - Where the decision was made, such as a ticket or a thread. Tooling may fill it when a settled decision becomes a fact.
facts[].probe string no Useful error if absolute, contains : or .. Path from the project folder to a committed probe script that re-checks the claim.
facts[].id string no Useful error unless lower-case letters, digits and -, 2 to 63 characters; hint if absent Stable citation id kept across rewording. Without one the id follows the wording, so always add one.

A dataset fact's citation id has the form <project>/<Dataset>/fact:<id>, for example marketdata-example/Rents/fact:office-incl-flex. A citation form for project-level facts is not in the spec yet.

A probe is a small script, committed with the project, that re-tests the claim against the data on each build and passes or fails. What a probe script must accept and print is defined by the implementation for now; it is not in the spec yet.

Two separate questions: how much it matters, and how sure we are

Every fact answers two questions, with separate fields. Do not mix them: a fact can be verified and minor, or unverified and critical.

How much it matters to an answer: severity.

Value Meaning Example How it is shown
blocker Ignore it and the answer is wrong. The reader must act on it every time. "rent_growth is a decimal, not a percent" Counted and listed first in the project summary ("2 blockers"), and first on the card.
caution Ignore it and the answer is wrong for some uses only. The reader applies it when the case fits. "office includes flex space from 2026Q2: only matters when comparing across 2026Q2" After blockers.
info (default) Background. Ignoring it does not make an answer wrong. "the 2026Q3 file was re-sent on 2026-11-02" Last.

How sure we are that it is true: status, reviewed_by and probe.

Level Fields How it is shown
Proposed status: proposed (the default): someone wrote it, nobody has confirmed it [unreviewed]
Reviewed status: reviewed, reviewed_by: the owner confirmed it no label
Checked against the data probe: a committed script re-tests the claim on each build the probe's last result, or "probe: not run yet"
Open decision status: decision-open with options: there is no house rule yet [decision open]; the reader says which option they used
Retired status: retired: no longer true not shown

The strongest fact is reviewed and has a passing probe. Severity does not change when a fact is verified: a verified blocker is still a blocker; verification only tells the reader they can rely on it.