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.