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.