Skip to content

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.