Overview¶
What it is¶
The AI-Ready Data spec is an open draft format for writing down what an AI agent must know to use a dataset correctly. You write it in a small YAML file next to the data. A tool checks the file against the data and shows it to agents, with ids they can cite.
The problem¶
Agents read everything in front of them, follow it literally, and fail on whatever is implicit. Three examples:
- They read
0.012as 0.012 percent when it means 1.2 percent. - They call last quarter's release "the latest".
- They join on a key that repeats on the other side, and a total doubles.
Worked through, with the fix for each: Why. Fourteen kinds of failure from real projects: Common failures.
How it works¶
Write. The file declares, for each dataset: what one row is (the
grain), the unit of each column, which release of each vendor source it reflects (the
as-of date), what not to do with it, recipes for common uses, and dated
facts. It is one file by default (oryxkb/project.yaml); it can be split.
Check. A checker compares the file with the data: a declared column that is missing, a unit that is not a unit, a typo in a key. It reports errors and warnings with line numbers. Warnings never block anyone; a strict mode can fail a CI run on errors.
Deliver. A tool renders a short card per dataset (purpose, grain, as-of dates, coverage, hazards, facts, joins, columns) and shows it where the agent works. Each fact has a stable id, so an answer can cite it.
Coordinate. Agents on different parts of a pipeline tell each other about changes: a rebuild sends a change notice to every importing project, a consumer asks the producer for a fix, and a person settles decisions that every agent then reuses. The spec fixes these messages' fields; the file carries what they point at (renames, types, decision facts, ids). See Communication.
A minimal file¶
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
rent_growth:
description: quarter-on-quarter rent growth
unit: decimal
Which fields matter most: What to write first. Step by step, with the check: Write your first file. Complete files: Examples.
Who it is for¶
- Data vendors and data product teams who ship data that agents will read. See For data vendors.
- Internal data teams who share datasets between projects and want the next analyst, or agent, to use them correctly.
- People building or using AI agents for analysis, who want the agent to know the rules of the data rather than guess them.
How it relates to other formats¶
The spec does not replace data contracts or semantic-model formats. It covers what they have no place for: an as-of date per source, a date, status and severity on every statement, recipes and hazards for agents, and citation ids. Where they overlap (pricing and relationships) it uses their field names. See Mappings.
Status¶
Draft v0.1, one implementation, Apache-2.0. Details: Status.
What the spec covers today, what tooling covers and what is still open: The full picture.