Skip to content

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 example unit: decimal for 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 column asof_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_not is 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. blocker means: ignore it and the answer is wrong. It starts as proposed and shows as [unreviewed] until the owner sets status: 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 --strict exits 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) and relationships (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 vendor column; then grain includes vendor. Both shapes work; this page used two columns.