Skip to content

The full picture

AI-ready data is wider than one file. Data is AI-ready when an agent can use it, be right, and stay right after the data changes, without a person carrying the context in their head. The spec's file covers part of this today; tooling covers more; some areas are open.

What is covered, area by area

Key. In the spec: a field in the file today. Tooling: done by an implementation (see Implementations), not part of the file format. Open: recommended practice, not in the spec or a tool yet.

Area What is needed In the spec Tooling Open
Meaning What one row is; the unit, scale and period of every column; what a blank means; keys that stay text (04567) grain; column description, unit, currency, per - Fields for scale, kind (level, change, rate) and the missing-value marker. Today: write them in the description.
Schema and types The column names; how each value is stored (number, text, date); which columns were renamed or removed Column type (ODCS logical type) and physical_type; column aliases and dataset removed_columns Types filled from the data on every build; a type change, a likely unit or scale jump, or new blanks flagged between two builds (Schema changes) A type for keys that must stay text, beyond string.
Definitions and use Metric formulas, what a metric is confused with, recipes, things not to do use_instead, use_cases, do_not - A structured metric formula.
Joins Which columns join two datasets, which side has many rows; mapping tables with codes, not names relationships (Ossie fields) - Mapping tables (one code mapped to another) as a declared construct.
As-of dates and releases The as-of date of each source; a list of releases, so an agent can say what it read and whether newer data exists dates_asof per source, with cadence and lag_days A build id; a warning when inputs mix as-of dates A per-release file (release id, as-of date, release date, what it replaces).
Restatements Which periods are preliminary, how history moves A dated fact - A revision-policy block; a preliminary / final column.
Change notes Renames with a date; which values changed Dataset aliases, removed_columns, project aliases, retired_names Which rows and values changed between two builds A machine-readable vendor changelog per release.
Known quirks and decisions Quirks as dated, scoped statements with a status and a check; open decisions facts with severity, status, expiry and a probe Discussing and settling decisions -
Provenance Each build records its code version, inputs and settings - Yes -
Citations A number in a report points at the fact or the data cell it came from, and can be re-checked later A stable id on facts and use cases; grain makes a cell addressable Citation ids, lookup and re-check The citation form, published as part of the spec.
Delivery Knowledge arrives where the agent works: in the result of the tool it called, a short brief, a check after it writes - A card per dataset; agent tools The card and tool-result shapes, published on this site.
Change notices When a number moves, the reports that quoted it are told, with old and new values The change notice and ack messages; renames and removals declared with dates Old and new values, read locally from the two builds -
Communication between agents Agents on different parts of the pipeline tell each other about changes, ask the producer for fixes, and reuse decisions a person settled Communication: imports, change notices, acks, requests, decisions, cited files A shared hub that carries them Consent rules for who sees which importers; notices across organisations.
Licence terms for agents May the data go into the buyer's own AI tools, or to outside AI services? A license text - Structured agent-use terms.
Cost Machine-readable pricing; the price of one request before the call pricing plans (ODPS 4.1 fields) - Per-request quotes, cost per run.
Access through MCP or an API Every response carries unit, period, as-of date and status - - Guidance below; outside the file format.

What AI-ready data does not mean

  • Not a new platform or a pipeline rewrite. For most data providers it is a few text files shipped with the data. A data dictionary is the starting point; the work is making it specific, dated and next to the data.
  • Not a bigger memory. Storing the same notes in a general memory store does not help: searches miss, and nothing marks a statement out of date. Structure, dates and checks do.
  • Not auto-editing. Agents change shipped work only after a person agrees.
  • Not blocking. Warn, never block, and record the gap so it gets fixed.
  • Not deciding for the user. Which release to use stays the data user's choice; the spec makes the choice visible.

A maturity ladder for data providers

The ladder uses the same tiers as What to write first.

Level What an agent gets Tiers of the file What it can do safely
0 PDFs, emails and a support desk none Very little; it guesses units, grain and freshness.
1 A data dictionary part of Critical (column descriptions) Read column meanings; still guesses units, releases and changes.
2 Grain, units, as-of dates, hazards and blocker facts Critical Say which data it used; read numbers at the right scale; avoid the traps that make answers wrong.
3 Machine-readable change notes; known quirks as dated facts with checks Critical, Important and Useful Explain why a number moved; avoid known traps and check they still apply.
4 Typed API or MCP access; change notices that agents confirm; citable ids all, plus tooling Fetch, check, quote with a citation and react to changes.

Level 3 is mostly writing, not engineering. The file reaches level 3 for the areas marked "In the spec" above.

Access through MCP or an API (open; guidance only)

For data pulled live, the tool's responses are often the only documentation an agent sees. Not in the spec yet; recommended practice:

  • Every response carries the unit, the period, the as-of date and the status of the values.
  • Real errors, not error text inside a successful response.
  • Tool descriptions that state the key caveats.
  • A way to ask what changed since a given release.

Sharing between data users and providers (a principle, not a field)

A data user's agent that compares deliveries can spot a changed unit or a moved value before a support desk does. Two rules make sharing that safe: method, not values (a report describes how the data behaves and carries a check that runs on the provider's own delivery, never the user's licensed numbers or code), and opt-in only (counts of how many users hit an issue appear only once three or more separate organisations report it). Nothing implements this yet.