Data Contracts: 7 Rules for Dependable Data Handoffs

Data contracts define what a data producer promises to the teams that use its data. They describe meaning, structure, quality, ownership, and change rules. A useful contract lets consumers know what they can rely on and what to do when a promise fails. It turns a vague data feed into a managed handoff.

This guide explains how to write a data contract specification that serves real business work. It covers fields, quality checks, freshness, access, versioning, and incident response. A worked order feed example shows how to test a contract before a small upstream change breaks a report or an application.

1. Start with a consumer decision

Begin by naming the decision that depends on the data. A sales report may guide stock purchases. A service may use an order feed to release goods. The cost of bad data differs between those uses, so one generic quality promise may not be enough.

Ask consumers what they need to know before they act. Does an order total include tax? Can a cancelled order appear? Does one row mean an order, an order line, or a later change? These questions reveal assumptions that a list of column types cannot cover.

Next, agree on the data product’s scope. Name the table, topic, file set, or API that the contract covers. State which sources it draws from and which uses it supports. This helps prevent a team from treating a convenient feed as an approved source for every purpose.

Data contracts are technical and operating agreements. They do not replace legal terms for sharing data or a wider governance policy. Where several teams depend on a feed, connect its contract to the wider data governance process. Keep the actual promises specific enough to test.

2. Define meaning before field types

A schema describes the structure of data. It can state that an order reference is text and a total is a number. However, the same structure can carry very different meaning. A number might represent dollars, cents, or a total in the buyer’s currency.

For each important field, record its meaning, unit, allowed values, and missing value rules. Distinguish unknown from not applicable. If a date uses a time zone, name it. If a timestamp describes the business event rather than data arrival, make that difference clear.

The Open Data Contract Standard provides a shared structure for areas such as schema, quality, roles, and service levels. It can help teams exchange a contract in a consistent format. Still, choosing the format does not decide the business meaning for you.

Include small examples that cover edge cases. An order with a refund, a missing address, and a changed currency may reveal different rules. Use fictional or safe test data. A contract should not spread private customer records merely to show a field format.

Give identity a clear rule

State what uniquely identifies each record and how updates work. Is an order reference unique across all tenants or only within one account? Can the producer reuse it after deletion? A consumer needs these answers to avoid merging unrelated records.

Also explain how a record leaves the feed. A missing row may mean deletion, filtering, or a late load. If consumers cannot tell which, they may erase valid data. Use an explicit change or deletion signal when the workflow needs one.

3. Make quality promises measurable

Choose checks that reflect the consumer’s task. Required identifiers, valid status values, and matching totals can all matter. Yet a check is useful only if the team knows its scope and failure action. A red dashboard with no owner does little to protect a business process.

For example, a dispatch feed may reject a row with no delivery reference. A planning report may accept that row but flag it for review. Agree on the response before building a shared rule. Otherwise, a strict check for one consumer may halt useful work for everyone else.

Separate checks on contract syntax from checks on actual data. A well formed file can describe a feed that violates every promise. The Data Contract CLI command guide distinguishes linting a contract from running schema and quality tests against configured servers. Use both kinds of check where your chosen tools support them.

Some rules need more context than a field check. A total may need to match line amounts within an agreed rounding rule. A status may allow only certain transitions. Write those rules in plain language first, then confirm that your test tool can express them.

4. Treat freshness as a business promise

Data can be valid yet too old to use. Define when the producer expects to publish and how consumers detect late delivery. Distinguish event time, processing time, and the time a consumer last received a complete batch. They answer different questions.

If a daily feed normally arrives before a planning meeting, state the expected cut-off and time zone. Also explain whether the feed is complete at that point. A file with today’s date may still contain only part of the day’s work.

Decide what happens during a delay. A report may show the last complete period with a clear warning. A stock release service may need to stop a risky action and alert staff. The contract should support that choice instead of leaving each team to guess.

Monitor the promise from the consumer’s side as well. A producer may finish its export while a delivery job fails later. End to end checks can show whether the consumer received the expected result. Our guide to observability practices explains how to connect technical signals to a useful operational response.

5. Plan changes before breaking a consumer

A contract needs a version and a change process. State which changes need review, how much notice consumers receive, and how they can test a new version. Renaming a field is an obvious risk. Changing a field’s meaning while keeping its name can be harder to spot.

Do not assume every added field is safe. A strict parser may reject unknown fields. A consumer may depend on a fixed column order. Check the actual consumers and tools before calling a change backward compatible.

A practical process compares the old and new contract, runs consumer checks, and records approval. Keep the old feed long enough for an agreed migration where needed. However, avoid supporting versions forever without owners or a retirement plan.

For shared APIs, contract testing can help catch mismatched expectations. Data contracts add concerns such as batch completeness, field meaning, and freshness. Use related tests together rather than assume one replaces the other.

6. Work through an order feed change

Consider an illustrative retailer that sends orders to a warehouse planner. Each row represents one order line. The contract defines the order reference, line reference, quantity, currency, and status. It also states that quantities describe ordered units, not units already shipped.

The producer plans to include cancelled lines in the next release. Previously, consumers never saw them. The schema stays the same because status already exists as text. Yet the business meaning changes, and the planner could buy stock for orders that no longer need it.

The team updates the allowed status values and adds examples. It agrees that the planner excludes cancelled lines from demand while retaining them for audit. Next, both teams test a file containing mixed states and check the resulting stock plan.

They also test a late cancellation after the planning cut-off. The contract cannot undo a supplier purchase. Instead, it explains the time boundary and identifies a follow-up report for late changes. This turns a hidden assumption into a visible operating choice.

Finally, the team checks a failed delivery. The planner shows the last complete feed date and does not label old demand as current. An alert reaches the named owner, who can replay a batch using stable line references. Duplicate checks prevent the replay from doubling the totals.

7. Put ownership and access into daily practice

Name a producer owner and a consumer contact. Include a support route, expected response window, and escalation path. A personal name alone becomes stale when someone changes roles. Use a maintained team route and test it during a trial incident.

Classify sensitive fields and state approved uses. A consumer that needs totals may not need names or addresses. Keep credentials out of the contract file. Point to the approved access process instead, and review who can read both the data and its examples.

Decide whether a failed check blocks delivery, quarantines rows, or allows a warned result. Record the chosen action for each major rule. If staff override a block, capture who approved it, why, and when the exception ends.

A small rollout that reveals real gaps

Start with one feed that has a known producer and a committed consumer. Run checks in observation mode first, using a safe copy or controlled access. Review failures together to separate genuine defects from incorrect assumptions in the draft contract.

Then enforce the checks that both teams can support. Measure missed deliveries, unresolved defects, and the time needed to assess a change. Avoid judging success by the count of contract files. A short contract that guides real decisions is more useful than a large catalog nobody reads.

Review the agreement when business rules change, not only when code changes. New regions, currencies, and product types can alter meaning without altering field types. Put contract review into the workflow where those choices occur, so it stays close to the source of change.

Choose a clear repair path for bad records

A contract should help the team fix a failure, not just detect one. Suppose a batch contains a missing currency value. Decide whether the producer repairs the source, sends a new batch, or issues a correction record. Each choice has a different effect on consumers.

Give each delivery a stable reference and keep enough history to trace a repair. A consumer should know whether it has already applied the corrected data. If a replay looks like a new sale, a good quality check can still lead to a bad total.

Also state how consumers learn about a correction. A quiet overwrite may leave a cached report unchanged. A clear notice can identify the affected period and the action needed. Avoid including private rows in a broad incident message.

Next, test a repair with one real consumer before rollout. Let that team show how it updates its report or service state. Check totals and duplicate handling after the replay. This reveals assumptions that a producer-only test may miss.

Finally, record the root cause in terms both teams understand. Was the source wrong, the meaning unclear, or the delivery incomplete? Use that answer to improve the right control. Adding another field check will not fix a shared misunderstanding about what the data means.