What Is a Data Contract? – Definition and How It Works
Learn what a data contract specifies, how it differs from a schema, and how the idea applies when the producer is a website you do not control.
A data contract is an agreement between a producer and consumers of a dataset covering structure, semantics, quality, and change. It is a schema plus everything a schema leaves unstated.
1. What It Specifies Beyond a Schema
| Element | Content |
|---|---|
| Structure | Fields, types, nullability |
| Semantics | What each field means, and its units |
| Quality | Expected completeness, freshness, and validity |
| Delivery | Cadence, format, and location |
| Change policy | How and when breaking changes happen |
| Ownership | Who is responsible, and how to reach them |
The semantics row is the one schemas cannot express and consumers most often get wrong: two fields named price in different datasets may mean list price and paid price.
2. Why It Exists
Without one, consumers infer meaning from field names and observed values. Those inferences are frequently wrong and always fragile — and when a producer changes something, breakage appears downstream with no way to attribute it.
A contract turns implicit assumptions into stated commitments that can be tested.
3. Quality Belongs in the Contract
Structure alone permits a technically valid, useless dataset: correct types with every field empty.
Stating expected completeness, freshness, and value ranges makes those testable, and a contract with automated tests is a contract that holds rather than a document nobody reads.
4. Change Policy Is the Point
A contract's most valuable clause is how change is handled: additive changes permitted freely, breaking changes announced with notice and a migration period, and versioning so consumers can move deliberately.
Without it, every producer change is a potential incident for every consumer.
5. Applying the Idea to Web Sources
The complication is obvious: a website has agreed to nothing. It owes you no notice and no stability.
The idea still applies, inverted. You write the contract you expect, and enforce it at your boundary:
- Declare the schema you extract.
- State the quality you expect — record counts, fill rates, plausible ranges.
- Validate against it on every run.
- Treat a violation as the source having changed, not as data to accept.
That converts an unannounced source change into a detected event.
6. You Are a Producer Too
Whatever you publish downstream — a table, a file, an API — has consumers who will infer meaning if you do not state it.
Publishing a contract for your own output costs little and prevents the class of dispute where two teams computed different numbers from the same dataset because they read a field differently.
7. Keep It With the Data
A contract in a document drifts. Kept with the pipeline, versioned alongside the code, and executed as tests, it stays true.
The practical test is whether a contract violation fails a run. If not, it is documentation.
8. Summary
A data contract specifies structure, semantics, quality, delivery, change policy, and ownership — everything a schema omits.
Web sources sign no contract, so the pattern inverts: declare what you expect, validate at your boundary, and treat violations as detected source changes. And publish one for your own outputs, since consumers will otherwise guess.