Skip to content

The spec

A project describes its data in YAML files in an oryxkb/ folder at the project root. The files declare what each dataset means. A checker reads them, compares them with the data, and reports mistakes.

How to read these pages. Each page has a short purpose, an example, often a "Fields explained" section in plain words, then a Definitions table. The Type, Required and Check columns are normative; the prose explains them. New words are in the Glossary.

Priority (Critical, Important, Useful, None) says what happens to an agent's answer when the field is missing; see What to write first. It is not the same as Required: Required says what the checker needs for the file to be valid; Priority says what the field does for answers. Sub-keys take their parent's tier unless the table says otherwise. Priority is guidance, not a check.

File layout

The declarations live in an oryxkb/ folder at the project root. The folder takes its name from the first implementation, oryxkb; a fixed, specific name means it cannot collide with other tools' folders (models/, model/). Files generated by a tool are written elsewhere, never into it.

<project root>/
  oryxkb/
    project.yaml          # everything by default: project info, datasets, relationships
    datasets/
      <Name>.yaml         # optional: one dataset moved out of project.yaml
    relationships.yaml    # optional: the relationships moved out of project.yaml
  • oryxkb/project.yaml holds everything by default.
  • When it grows, move a dataset to oryxkb/datasets/<Name>.yaml. The file holds that one dataset's entry (the contents of datasets.<Name>, without the name). Move the relationships to oryxkb/relationships.yaml.
  • A tool merges these files when it reads them. The result is the same as one file with all the keys.
  • Declaring one dataset in both project.yaml and oryxkb/datasets/<Name>.yaml is an error.
  • Agents never read these files directly. They get the declarations through a tool, as a card or through an MCP server, so the split is invisible to them.

The rest of the spec shows the keys as they appear in oryxkb/project.yaml.

YAML style. Write maps in block style, one key per line. Do not use {...} flow maps. Short lists of column names may stay inline: grain: [market_id, sector]. Quote any text that contains : or ,.

Minimal example

version: 1
project:
  name: marketdata-example
datasets:
  Rents:
    purpose: Quarterly asking rent per market and sector.
    grain: [market_id, sector, period_yq]
    columns:
      rent:
        description: asking rent
        currency: USD
        per: year

More: Examples. Step by step: Write your first file.

Definitions

Key Type Required Priority Check Description
version integer, must be 1 yes None error if missing; error if not 1 File format version.
project Project no Important - Facts about the project as a whole.
datasets map of name to Dataset no Critical - One entry per dataset, keyed by the dataset's name. A dataset written with no body is allowed. May be split into oryxkb/datasets/<Name>.yaml.
relationships list of Relationship no Critical error on a duplicate name Join rules between datasets. May be split into oryxkb/relationships.yaml.

Pages

Project, Datasets, Columns, As-of dates, Facts, Use cases, Relationships, Pricing, Extensions. When a dataset changes shape or meaning: Schema changes. Messages between projects (imports, change notices, acks, requests, decisions): Communication; they are exchanged through a shared service, not written in the file.

Schema. A dataset's schema is its column names, each column's type (filled from the data by a tool) and physical_type, its unit, the columns' aliases and the dataset's removed_columns.

Versions

There are two version numbers. Spec draft 0.1 (this site) defines file format version 1 (the version: 1 line in the file).

version: 1 is required. A file with another version value is rejected with a message that names the supported version. Within version 1, new optional keys may be added; a reader that does not know a key reports it as an unknown key (see below). A breaking change to a key (for example a rename) is announced in the changelog.

Errors and warnings

Keys are strict: an unknown key at any level is an error, unless it starts with x- (see extensions). The Check column in these pages uses three values:

  • error: a mistake in the file. The message starts with ERROR and carries the file line. A strict run (for CI) fails on it; a normal run reports it and carries on. A value that does not fit its type, or breaks a rule listed on the page, is an error.
  • warning: reported, never blocks. A hint (advice, such as "declare a grain") is a kind of warning.
  • -: the key is carried and shown, but no check looks at it.

A file that cannot be read at all (broken YAML, a top level that is not a mapping) is reported as an error and nothing else is checked.

"In the data" in a Check column means: among the columns of the dataset's data as stored. Those checks need the data itself, not only the file; a checker runs them when it can read the data.

What a checker also reports

These are checker behaviours, not part of the format. They are listed so the warnings do not surprise you.

  • Hand-typed counts. Descriptive text (purpose, descriptions, use cases, hazards) is scanned for counts and spans such as "12,000 rows" or "from 2015", which go stale. The checker warns and suggests letting the tool generate them or writing a dated fact. This is marked "prose lint" in the Check columns.
  • Long entries. A dataset entry longer than about 80 lines gets a warning: move narrative into facts.
  • Booleans. Only true and false are booleans (YAML 1.2), so an unquoted on stays text.