Skip to content

For data vendors

Your clients' agents already read your data. This page says what to write so they read it correctly.

What changes for a client's agent

A client asks their agent: "Which markets had the strongest office rent growth last quarter?"

Without the file. The agent reads your column rent_growth, sees 0.012, and the header says "(%)".

"Office rent growth was flat everywhere: the top market grew 0.031%. Data is the latest available."

Two mistakes: the values are fractions (0.031 is 3.1%), and "latest" is a guess.

With the file. The agent's card says rent_growth has the unit decimal, and the as-of line says "vendor_a 2026-09-30 (constant) (quarterly, ~20 days after period end)". It also lists a fact: office includes flex space from 2026Q2.

"Market C led with 3.1% quarter-on-quarter office rent growth (release as of 2026-09-30). Note: office includes flex space from 2026Q2, so this quarter is not directly comparable with 2025."

What you write

One file, oryxkb/project.yaml, next to the data you deliver. For a vendor, one project is usually one data product, and each table in it is a dataset. Start with these six things for each dataset:

What Key Example
What one row is grain grain: [market_id, sector, period_yq]
The unit of each number columns.<name>.unit, or currency + per unit: decimal; currency: USD with per: year
Which release this is dates_asof constant: "2026-09-30"
Things not to do do_not "do not compare rent across sectors without adjusting for lease length"
What a client must know, with a date facts "office includes flex space from 2026Q2"
Terms of use license "Licensed to subscribers; not for redistribution."

Everything else is optional. A complete vendor file: Examples.

Your release is your source. In dates_asof, name your product once (for example vendor_a) and give the as-of date of the release you are shipping. The simplest form is constant: "2026-09-30", updated with each release. If a column already holds the date, use column: asof_date. See As-of dates.

How much work

Mostly writing, not engineering. Start from your data dictionary and your support notes: the units, the definition changes and the common client mistakes are already written down somewhere. The work is making each statement specific (which column), dated, and placing it in the file. No code is needed to write the file.

You do not need every field. What to write first ranks them in four tiers by what a missing field does to an agent's answer, and gives a minimum file: the Critical tier only.

Then run a checker over it. It reports typos, unknown keys and invalid units with line numbers. See Write your first file for a walk-through.

If your data comes out of Python pipelines, most of the file can be generated. The open-source oryxflow library writes the file's skeleton when a pipeline saves a dataset: the columns, a proposed grain, and an entry to fill for each new column. On later saves it flags new, renamed and dropped columns and proposes the change. Its Claude Code plugin reminds the AI agent working in the pipeline to fill in the rest as it changes the code: descriptions, units the code shows, aliases for renamed columns, and cautions it finds along the way, such as a column whose format changed. The agent asks your team only for what neither the code nor the data shows, such as the unit of a raw vendor column or a definition change announced by email, and never guesses a unit. For other pipelines and platforms, contact support@oryxintel.com about generating the file from them.

How it reaches clients

  • With file deliveries. Ship the oryxkb/ folder alongside the data files. A tool on the client's side reads it and renders the card for their agent.
  • Through an API or MCP server. Not in the spec yet. The file can be the source of the text your tool descriptions and responses carry; see the guidance on The full picture.

A client's agent benefits only if a tool on their side reads the file. Today there is one such tool: oryxkb.

The spec is a draft; see Status for what is not in it yet, and The full picture for every area.