What to write first¶
You do not need every field. This page ranks them by one question: what happens to an agent's answer when the field is missing?
| Tier | Without it |
|---|---|
| Critical | Answers are wrong. |
| Important | Answers are wrong for some questions, or the agent has to guess. |
| Useful | Answers are better and easier to trust, but not right versus wrong. |
| None for accuracy | Commercial or admin terms. They matter, but not for whether the answer is right. |
A judgment, not a measurement
This order is a judgment drawn from the failure types seen in real projects. It has not been measured yet. A benchmark that drops one tier at a time and compares agents' answers is planned.
Every Definitions table in the spec has a Priority column with these tiers. Priority is not the same as Required: Required says what the checker needs for the file to be valid; Priority says what a field does for answers.
Critical¶
Answers are wrong without these.
| Field | Why it is critical | Failure it prevents |
|---|---|---|
grain |
Without it an agent cannot tell what one row is, what a sum means, or which joins are safe. | 3. Grain and keys, 4. Join rules |
columns.*.unit (or currency + per) |
A number with no unit is read at the wrong scale: 0.012 as 0.012% instead of 1.2%. | 1. Units and scale |
columns.*.description |
Without it the agent guesses what a column measures from its name. | 7. Meaning of derived metrics |
dates_asof |
Without it the agent cannot say which release it used, and calls an old one "latest". | 2. As-of dates and restatements |
do_not |
Standing rules that, when broken, give a wrong number that looks right. | 4. Join rules, 8. Vendor method quirks |
facts with severity: blocker |
By definition: ignore it and the answer is wrong. | 8. Vendor method quirks, 13. Undated statements |
relationships, for keys that look joinable but are not |
Names instead of ids, codes that lose a leading zero, a mapping table in between: the join runs and silently loses or repeats rows. For other joins, the grain is usually enough. | 4. Join rules |
Important¶
Wrong for some questions, or the agent guesses.
| Field | Why it is important | Failure it prevents |
|---|---|---|
purpose |
Tells the agent which dataset serves which question. | 5. Which dataset to use |
use_cases (filter, then, pitfall) |
The right way to do a common task, and what goes wrong the obvious way. | 5. Which dataset to use, 8. Vendor method quirks |
profile.period, profile.coverage_by |
Shows coverage gaps, for example a sector that starts later, before the agent averages over them. | 6. History spans and gaps |
facts with severity: caution |
Wrong for some uses only, such as comparing across a definition change. | 9. Undocumented decisions |
removed_columns, dataset and project aliases, retired_names, removed_datasets |
After a rename, queries break or keep reading a stale copy, often silently. See Schema changes. | 11. Renames that break consumers |
project.sources |
Names each vendor feed once, so as-of dates and citations point at the right one. | 2. As-of dates and restatements, 10. The same fact copied |
Useful¶
Better answers and more trust, not right versus wrong.
| Field | Why it is useful | What it helps with |
|---|---|---|
profile.entities, profile.series |
Counts of markets and series in the profile. series usually defaults correctly. |
6. History spans and gaps |
facts with severity: info |
Background; ignoring it does not make an answer wrong. | |
not_exported |
Says what is deliberately missing and where to get it, so the agent does not hunt or guess. | |
columns.*.type |
How each value is stored (number, text, date). A tool fills it from the data on every build, so you rarely write it; it lets a tool flag a type change between builds and a unit on a text column. It is not Critical because the agent can read the stored type from the data itself. |
11. Renames that break consumers |
cadence, lag_days |
Display only today. | |
Fact and use case id |
Stable citation ids: a reader can audit which fact a number relied on. | 10. The same fact copied |
probe, reviewed_by |
Keep facts true over time. This is how critical facts stay correct. | 13. Undated statements |
None for accuracy¶
| Field | Why |
|---|---|
license |
Whether the agent may use the data, not whether the answer is right. See 14. Licensing. |
pricing |
What the data costs, not whether the answer is right. |
columns.*.physical_type |
The storage type as the engine names it (int64); a tool keeps the build's value. |
display, checks, identity_only_params |
Admin and implementation details. |
x- extensions |
Team conventions; no meaning in the spec. |
Your minimum file¶
The Critical tier, for a dataset of rents and a dataset of markets. It passes oryxkb check with no errors or
warnings.
version: 1
datasets:
Rents:
grain: [market_id, sector, period_yq]
dates_asof:
vendor_a:
constant: "2026-09-30"
columns:
market_id:
description: market code (text; keep leading zeros)
rent:
description: asking rent per square foot
currency: USD
per: year
rent_growth:
description: quarter-on-quarter rent growth
unit: decimal
do_not:
- text: compare rent across sectors without adjusting for lease length
columns: [rent]
facts:
- id: growth-is-decimal
statement: "rent_growth is a decimal, not a percent: 0.012 means 1.2%"
as_of: 2026-11-13
severity: blocker
columns: [rent_growth]
Markets:
grain: [market_id]
columns:
market_id:
description: market code (text; keep leading zeros)
market_name:
description: display name; spelled differently across vendors
relationships:
- name: rents_to_markets
from: Rents
to: Markets
from_columns: [market_id]
to_columns: [market_id]
ai_context: join on market_id, never on market_name
The file has no type lines: a tool fills each column's type from the data when it publishes. Together with the
column names, units, aliases and removed_columns, the types make up the dataset's schema
(Columns, Schema changes).
Next, add the Important tier: a purpose line per dataset, project.sources, and a profile with period and
coverage_by. A step-by-step version: Write your first file.