A familiar incident: an application team renames a column, or changes a status code from a number to a string. Their tests pass. Two days later the finance dashboard is wrong, a machine learning feature has gone null and an executive is asking why. Nobody did anything unreasonable. The interface between the application and its data consumers was simply never written down.
Data contracts fix that by treating data like an API: documented, versioned and checked.
What a contract contains
The Open Data Contract Standard, maintained by the Bitol project under the Linux Foundation, gives a useful vendor-neutral structure. Version 3 covers a contract's fundamentals, schema, data quality rules, servers, ownership, SLAs and support channels, and extended support beyond relational tables to hierarchical, streaming and unstructured data13. Version 3.1.0 added executable SLAs, relationships between properties and stricter validation, while keeping v3.0 contracts valid2.
| Section | Question it answers |
|---|---|
| Schema | What fields, types, keys and nullability can consumers rely on? |
| Semantics | What does each field mean, in business terms? |
| Quality | What checks must the data pass, and what happens when it doesn't? |
| SLA | How fresh and available is it? |
| Ownership and support | Who owns it, and how do consumers raise problems? |
A standard format matters less for the first contract than the tenth. Once contracts are machine-readable, catalogues, quality tools and CI checks can all read the same file.
The playbook
- Start where it hurts. Pick the two or three datasets behind recent incidents or critical reports. Don't try to contract the whole estate.
- Write the contract with both sides in the room. The producer knows what the data is; consumers know what they depend on. The contract is the overlap.
- Put it in the producer's repository, next to the code that emits the data, so changes to both are reviewed together.
- Fail breaking changes in CI. A pull request that removes a field, narrows a type or changes a key should fail before merge, as practitioners recommend45.
- Version intentionally. Additive changes such as a new nullable field are minor versions. Breaking changes get a new major version, run in parallel with the old one for an agreed deprecation window5.
- Check quality and freshness at runtime, against the same contract, and route failures to the owner named in it.
- Publish contracts in the catalogue, so consumers discover data through its contract rather than by browsing tables.
The contract only works if a breaking change actually fails a build. A contract that lives on a wiki page is documentation, and documentation drifts.
Where contracts sit in the architecture
Contracts are most valuable at the boundaries: where operational systems publish events or change streams, as in change data capture and event streams, and where curated datasets are shared between domains. They pair naturally with table formats that track schema and lineage, such as Apache Iceberg v3, and with semantic definitions from an ontology or semantic layer, which give fields meaning beyond their types.
Why AI raises the stakes
AI systems consume data silently. A dashboard with a broken number may get noticed; a retrieval index or a model feature fed malformed data often doesn't, and the model presents the result fluently. Contracts on the data feeding features, training sets and retrieval indexes are an inexpensive guard against that kind of quiet failure. The Bitol community is also working on making contracts more useful to AI consumers, though that work is still in progress6.
Common objections
- "It slows producers down." Only for breaking changes, which is the point. Additive changes flow through.
- "We have too many datasets." Start with the critical few. Coverage grows as teams see incidents drop.
- "Our tools are different." A standard, machine-readable format is what lets different tools share one definition.
How I can help
I design data platforms where reliability is built in, from contracts and CI checks to catalogues and quality monitoring. As a fractional CTO I can lead the rollout across teams. Or analyse your challenge and bring the result to a call.
- 1
- 2Bitol announces ODCS v3.1.0: stronger, smarter, and stricterBitol, Linux Foundation
- 3Open Data Contract StandardData Contract documentation
- 4
- 5
- 6ODCS v3.2 and ODPS v1.1: making AI smart about your dataData Intelligence Platform (Substack)