Data Contract

A data contract states what a producer supplies and what consumers may rely on. It covers meaning as well as structure: one row per order — the grain — a stable order identifier, an amount in the named currency’s minor units, and the time basis for each date. A list of column types cannot express all of those promises.

What the data may be used for

Structure, grain and freshness describe what arrives. They say nothing about what a consumer may legitimately conclude from it, and that gap is where the expensive misuse happens — most often with outputs that are estimates rather than observations.

A forecast dataset is the clearest case. Its columns look exactly like measured demand: a date, a product, a number. Nothing in a schema stops a consumer from treating the number as what happened, comparing it with actuals as though both were observations, or reading a model’s feature weights as the effect of changing that feature. For an estimate, the contract therefore has to carry a few more fields.

• What it is an estimate of, stated as a quantity — units shipped, or orders placed, or revenue recognized — and for which population.
• The horizon and the vintage: how far ahead it predicts and which issued forecast is being evaluated. Preserve an identifiable forecast snapshot and its issuance time, whether in the delivered data or reliably linked version metadata, so later evaluation cannot accidentally use a revised forecast or future information.
• Its uncertainty, in a representation consumers can reliably retrieve and interpret, such as a forecast interval or linked, versioned evaluation metadata. State which forecast and population it covers. A recent aggregate error measure describes past performance; it is not an interval for each individual forecast. The contract should make that distinction usable without prescribing a column where another representation works better.
• Decisions it is fit for, such as planning inventory at a weekly level.
• Supported interpretations: a forecast is not an observation. Comparing it with matched actual outcomes is valid for measuring forecast error or variance against plan, provided timing, population, and units agree. That difference alone does not explain why the outcome occurred, and a predictive association does not establish an intervention’s effect.

Two habits keep this from being decorative. Write the prohibited readings the way you would write a check — specific enough that someone can tell whether a given dashboard violates it. And put the limitation where the data is consumed, in the column descriptions and the table’s documentation, rather than only in a contract document nobody opens while building a report.

Name the producer and responsible owner, expected freshness, accepted updates and deletions, quality checks, and the response when a check fails. Where the contract carries a number rather than a column, the agreed metric definition is part of it. A daily total also needs a defined population: a timely file can still omit orders. State which checks block publication and which produce a visible warning.

Version the contract and identify affected consumers before a change — which is the compatibility question, decided against real readers rather than against a rule of thumb. Adding a nullable column may preserve named-column queries but break a positional export. Changing the meaning of paid revenue can break a consumer without changing any column. Test actual readers and agree migration and notification steps.

Declared consumers and observed reads

An access log shows reads through the paths and time window it records. It can discover an unregistered dashboard, but a quarterly export outside that window or an offline copy will not appear. Absence from the log therefore does not establish that a dataset has no consumers.

A stated promise remains part of the contract even when a consumer’s reads are not instrumented. It does not reveal who that consumer is. Ask consumers to register the dataset and contract version they depend on, an owner, and a notification route; agree a notice period for incompatible changes. Reconcile that register with logs, lineage, and owner inquiries. Registration preserves a declared dependency that observation can miss, while logs can reveal readers who never registered. Neither list is complete on its own.

A contract document is not enforcement. Producers need checks and operating procedures that implement it, and consumers need a way to detect violations. The Open Data Contract Standard provides a structured representation; adopting a representation does not by itself prove that delivered data satisfies it.

Further reading

• Bitol: Definition — Open Data Contract Standard (ODCS)

See the worked examples in Designing End-to-End Data Architecture.