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.yamlholds everything by default.- When it grows, move a dataset to
oryxkb/datasets/<Name>.yaml. The file holds that one dataset's entry (the contents ofdatasets.<Name>, without the name). Move the relationships tooryxkb/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.yamlandoryxkb/datasets/<Name>.yamlis 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
ERRORand 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
trueandfalseare booleans (YAML 1.2), so an unquotedonstays text.