Write your first file¶
You have a table of quarterly rents by market and sector. Two columns come from two vendors: asking rent from
vendor_a and effective rent from vendor_b. You load each vendor's file when it arrives. By the end of this page
you will have a file that declares the table, checked with a checker.
It takes six steps. Every key used here is defined in the spec.
1. Create the file¶
In your project folder (the folder that holds the data or the code that builds it), create oryxkb/project.yaml:
version: 1
project:
name: rents-research
owner: data-team
sources:
vendor_a: Quarterly asking-rent file from vendor A
vendor_b: Quarterly effective-rent file from vendor B
version: 1 is required. sources names each vendor feed once, with one line saying what it is. You will use these
names again in step 4.
2. Say what one row is¶
Add the dataset. Its name is the name of the table others read.
datasets:
Rents:
purpose: Quarterly rent per market and sector, from vendors A and B.
grain: [market_id, sector, period_yq]
purpose is the first line an agent reads. grain lists the columns that identify one row: here, one row per
market, sector and quarter. Grain is the most useful line in the file. It tells an agent what a sum means and which
joins are safe.
3. Give every number a unit¶
Add columns under Rents:
columns:
market_id:
description: market code (text; keep leading zeros)
sector:
description: property sector
period_yq:
description: calendar quarter, written 2026Q3
asof_a:
description: as-of date of the vendor A file this row came from
rent_a:
description: vendor A asking rent per square foot
currency: USD
per: year
rent_b:
description: vendor B effective rent per square foot
currency: USD
per: year
- Money takes
currency(an ISO code) and, for a flow such as rent,per(the period). Here: US dollars per year. - Other numbers take
unit, for exampleunit: decimalfor a fraction where 0.012 means 1.2%. See Common units. - "Per square foot" has no field of its own; it is not in the spec yet. Write it in the description.
4. Say which release each vendor's data is¶
Add dates_asof under Rents. It gives the as-of date of each source: which release of
the vendor's data the table reflects.
dates_asof:
vendor_a:
column: asof_a
cadence: quarterly
vendor_b:
constant: "2026-09-30"
cadence: quarterly
Two forms, for two common cases:
column: your load step writes the release date of the vendor A file into the columnasof_a. This stays right when the next file arrives. Prefer it when you can.constant: a fixed date. Simple, but you must update it when you load a new vendor B file. The checker does not notice a stale constant.
Then link each value column to its source, so a citation of rent_a names only vendor A:
rent_a:
description: vendor A asking rent per square foot
currency: USD
per: year
as_of_sources: [vendor_a]
Do the same for rent_b with [vendor_b]. Other forms (param, from_input) are for pipelines: see
Which form to use.
5. Write down what a reader must know¶
The two rent columns look alike but measure different things. Say so twice: once as a standing rule, once as a dated fact.
do_not:
- text: average or subtract rent_a and rent_b
columns: [rent_a, rent_b]
facts:
- id: asking-vs-effective
statement: "rent_a is asking rent and rent_b is effective rent (after incentives): compare each with itself over time, not with each other"
as_of: 2026-11-13
severity: blocker
columns: [rent_a, rent_b]
do_notis a rule that is always true for this data.- A fact has a date (
as_of, the day you wrote it), a severity and an id.blockermeans: ignore it and the answer is wrong. It starts asproposedand shows as[unreviewed]until the owner setsstatus: reviewed. - Quote any text that contains
:or,.
Optionally, add a profile block that shapes the coverage profile the agent sees (see
Profile fields):
profile:
period: period_yq
entities: [market_id]
coverage_by: [sector]
series is left out: it defaults to the grain minus period ([market_id, sector]).
6. Check the file¶
Install oryxkb, the first implementation; its install steps are in the oryxkb docs. From the project folder, run:
oryxkb check oryxkb/project.yaml
Suppose step 3 had two slips: unit: USD on rent_a instead of currency: USD, and descripton typed on rent_b.
The check reports both, with file and line:
ERROR oryxkb/project.yaml:30: datasets.Rents.columns.rent_a.unit: 'USD' is a currency code: currency is not a UCUM unit: use currency: USD
ERROR oryxkb/project.yaml:34: datasets.Rents.columns.rent_b: unknown key 'descripton'
1 datasets; 2 warnings (2 ERROR)
Fix them and run it again:
1 datasets; 0 warnings (0 ERROR)
- The summary counts every reported line as a warning, and says how many of them are errors.
- The plain check always lets you carry on.
oryxkb check --strictexits with status 1 when there are errors, for CI. - Checks that need the data itself, such as "every declared column is in the data", run when the tool can read the data. With the file alone, it checks the file.
The full file from this page:
version: 1
project:
name: rents-research
owner: data-team
sources:
vendor_a: Quarterly asking-rent file from vendor A
vendor_b: Quarterly effective-rent file from vendor B
datasets:
Rents:
purpose: Quarterly rent per market and sector, from vendors A and B.
grain: [market_id, sector, period_yq]
profile:
period: period_yq
entities: [market_id]
coverage_by: [sector]
dates_asof:
vendor_a:
column: asof_a
cadence: quarterly
vendor_b:
constant: "2026-09-30"
cadence: quarterly
columns:
market_id:
description: market code (text; keep leading zeros)
sector:
description: property sector
period_yq:
description: calendar quarter, written 2026Q3
asof_a:
description: as-of date of the vendor A file this row came from
rent_a:
description: vendor A asking rent per square foot
currency: USD
per: year
as_of_sources: [vendor_a]
rent_b:
description: vendor B effective rent per square foot
currency: USD
per: year
as_of_sources: [vendor_b]
do_not:
- text: average or subtract rent_a and rent_b
columns: [rent_a, rent_b]
facts:
- id: asking-vs-effective
statement: "rent_a is asking rent and rent_b is effective rent (after incentives): compare each with itself over time, not with each other"
as_of: 2026-11-13
severity: blocker
columns: [rent_a, rent_b]
What the agent gets¶
A tool renders this file, plus counts from the data, into a card. For this file the top of the card reads (illustrative; counts are synthetic):
## Rents
Quarterly rent per market and sector, from vendors A and B. (D)
As-of (D; values G): vendor_a 2026-09-30 (quarterly); vendor_b 2026-09-30 (constant) (quarterly).
Entities (G): 55 market_id.
Coverage (G): period_yq 2010Q1..2026Q3.
By sector (G): industrial 2012Q1..2026Q3, 3,410 rows, 55 market_id; office 2010Q1..2026Q3, 4,120 rows, 55 market_id.
Grain (D): one row per market_id x sector x period_yq.
**Hazards** (D)
- do not: average or subtract rent_a and rent_b (columns: rent_a, rent_b)
**Facts** (F: dated lines in oryxkb/project.yaml; 1 unreviewed)
- **blocker** [unreviewed] rent_a is asking rent and rent_b is effective rent (after incentives): compare each with itself over time, not with each other (as of 2026-11-13; columns rent_a, rent_b)
How each line maps to the file: What an agent sees.
Next¶
- See which fields matter most and what to add next: What to write first. This page covered the Critical tier and part of the Important tier.
- Add
use_cases(recipes) andrelationships(joins): Use cases, Relationships. - Have the owner review the fact and set
status: reviewed. - One metric from two vendors can also be one column plus a
vendorcolumn; thengrainincludesvendor. Both shapes work; this page used two columns.