Appendix E: Data Contract Template

Purpose

A data contract defines the promises at a producer-consumer boundary. Use one for an API, event, shared table, warehouse model, object export, stream, search document, feature table, or any other data product whose failure can break work outside the producing team.

The schema is only one promise. A consumer also needs to know what a record means, how current it will be, which disorder and duplication to expect, how changes arrive, who can see it, how deletion propagates, and who acts when the promise is broken. If those answers live only in code or team memory, the boundary has no usable contract.

Copy the headings below into the repository or registry that owns the data. Replace every prompt. Link machine-readable schemas and tests rather than copying them into a document that will drift. The producer owns the contract; material consumers review the promises they depend on.

The Contract

Data Contract: [Dataset, Event, or API]

• Version:
• Status: Proposed / Active / Deprecated / Retired
• Producer owner: accountable for meaning, schema, quality, and change
• Operational owner: accountable for delivery, freshness, access, cost, recovery, and incidents
• Source-of-truth owner: accountable for the authoritative fact when that owner differs from the producer
• Contract location: registry or repository path
• Machine-readable schema: versioned link
• Material consumers: names and owners
• Last reviewed:
• Next review or retirement date:

Proposed means consumers must not build production commitments against the contract. Active authorizes reliance on its stated guarantees. Deprecated keeps those guarantees during a migration window. Retired means publication has stopped and the retirement evidence is linked.

Boundary and Authority

Name the fact this data represents in plain language. Identify the business event, command, source record, job, or external observation that creates it. Then name the authority: which system can settle a disagreement when two copies conflict?

Describe the delivery boundary precisely. Include the topic, endpoint, table, bucket prefix, stream, index, or model and the environment, region, tenant, and partition scope that matter. State whether the contract covers a source of truth, a derived view, or a transport copy.

• Fact represented:
• Creation or update event:
• Authoritative source:
• Delivery boundary and scope:
• Derivation from source truth:
• Explicit non-goals:

Do not call a convenient copy authoritative merely because consumers query it. If it can be rebuilt, say what it is rebuilt from. If no surviving source can recreate it, record that durability obligation here.

Meaning and Consumer Reliance

Write the sentence a consumer is allowed to believe when it receives one record. Define what repetition, correction, deletion, and late arrival mean. Reject tempting interpretations that the shape permits but the business meaning does not.

• One record means:
• Identity and idempotency key:
• Event time, effective time, and processing time:
• Repeated record: duplicate / new observation / replacement / other
• Correction: replacement / compensating record / versioned amendment / other
• Deletion: tombstone / hard delete / redaction / expiration / other
• Late arrival: accepted until [bound] and handled by [policy]
• Consumers may rely on:
• Consumers must not infer:

For each material consumer, name the behavior or customer promise that depends on this data. A dashboard used for exploration and an entitlement check may read the same field but do not carry the same contract risk.

Schema and Field Semantics

Link the enforced schema, then keep this human review table for fields whose meaning or compatibility cannot be recovered from types alone.

For every nullable field, define the null state. Unknown, not applicable, not yet computed, intentionally redacted, deleted, and producer defect are different facts. If consumers need to distinguish them, use an explicit state or reason rather than overloading null.

Record key scope, uniqueness, referential expectations, enumeration ownership, precision, time zone, encoding, and maximum size where they affect behavior.

Delivery Behavior

State measurable behavior at the point where the consumer can observe it, not only inside the producer pipeline.

• Freshness target: maximum lag from event time or source truth to consumer visibility, including percentile and measurement window where appropriate
• Freshness SLI: consumer lag, watermark age, oldest visible event, last successful batch, or another owned signal
• Availability target: operation and observation point covered by the target
• Ordering: global / tenant / entity / partition / best effort / none
• Duplicates: when they can occur and which key makes consumption idempotent
• Late data: acceptance bound, correction behavior, and consumer obligation
• Backfills: whether old records may reappear and how they are identified
• Replay: retained interval, ordering behavior, side-effect controls, and authorization
• Failure behavior: pause / retry / quarantine / partial publication / fail closed / other

“Near real time” and “highly available” are not contract terms. Give a bound, an observation point, and the consequence of missing it.

Quality Evidence

For each promised property, record the rule, where it is checked, the consumer-visible signal, the failure threshold, the first safe action, and the owner. Include checks at the producer boundary and reconciliation against source truth. A passing pipeline is not proof that consumers received correct data.

At minimum, decide whether the contract needs evidence for:

• required fields and valid states;
• key uniqueness within its declared scope;
• freshness and completeness;
• source-to-delivery counts or checksums;
• critical business totals and invariants;
• tenant isolation and access decisions;
• deletion and redaction propagation;
• schema conformance and unknown enum values.

One realistic check might read: Active account records have a unique account_id; the producer rejects duplicates, a daily reconciliation compares the delivered set with the account authority, and any mismatch quarantines the affected partition and pages the producer owner. That statement can become a test, a signal, and an incident action. “Validate primary keys” cannot.

Evolution and Compatibility

Choose a versioning scheme and define compatibility before proposing the first breaking change. Record which consumer versions coexist, how consumers are discovered, and who can approve an exception.

For deprecation, state the minimum notice period, communication and escalation channel, dual-publish or compatibility plan, migration owners, and retirement criteria. Access logs and lineage help discover consumers; neither proves that an unobserved consumer is harmless. Retire a promise on evidence and named approval, not silence.

Protection and Permitted Use

Classify the data using the organization’s vocabulary. Name the users, services, jobs, dashboards, and support tools allowed to access it, together with their approved purposes. Record prohibited uses when technically valid access could still violate privacy, security, policy, or user expectations.

• Classification and regulated categories:
• Service and human roles:
• Purpose limits and prohibited uses:
• Authentication and authorization boundary:
• Audit events, retention, review cadence, and alert owner:
• Storage, processing, backup, log, and export residency:
• Encryption or tokenization obligations:
• Break-glass path and review:

Retention, Deletion, and Proof

State how long records remain in the authoritative source, delivery system, backups, logs, and material derived stores. Define user, tenant, policy, and corrective deletion separately when their behavior differs.

Name how a deletion travels: tombstone, command, source scan, expiry, rebuild, or another mechanism. Include retry and late-consumer behavior, tombstone retention, backup expiry, and the point after which replay cannot resurrect the record. Then name the evidence that proves deletion or redaction reached every material consumer.

• Retention by location:
• Deletion and redaction triggers:
• Propagation mechanism and deadline:
• Tombstone or suppression lifetime:
• Backup and replay behavior:
• Proof, exception queue, and owner:

Lineage, Rebuild, and Recovery

Trace the path far enough to answer where wrong data came from and which consumers received it.

• Upstream: source tables, APIs, events, files, external systems, models, and manual inputs
• Transformation: versioned jobs or code, owners, joins, filters, enrichment, and aggregation
• Downstream: known services, dashboards, models, exports, derived stores, and customer-facing features
• Rebuild: authoritative input, procedure, expected duration, capacity limits, and validation
• Recovery: RPO, RTO, restore owner, last tested date, and acceptance queries

If a transform changes the meaning, freshness, or protection of the data, the derived product needs its own contract or an explicit extension of this one.

Incident Response

Define who declares a contract breach and how consumers learn about it. Link the incident process, dashboard, runbook, communication channel, and status surface. For each plausible breach, record the first action that contains harm without destroying evidence.

• Freshness or delivery breach: confirm source truth, lag, and affected consumers; pause dependent publication when stale data would mislead users.
• Schema incompatibility: stop the rollout or quarantine incompatible records; preserve failing examples and notify consumer owners.
• Wrong or incomplete data: stop further spread, identify the affected interval and consumers, repair from authority, and verify before republishing.
• Unauthorized exposure: close the access path, preserve audit evidence, and enter the security and privacy incident process.

Name the producer incident lead, operational responder, source-truth owner, security or privacy contact, and consumer communication owner. “Data team” is not an escalation path.

Activation and Change Gate

Before changing the contract to Active, review it with the producer, operational owner, and material consumers:

1. Can a new consumer state what one record means and what it must not infer?
2. Are identity, null, correction, deletion, ordering, duplicate, late-data, backfill, and replay semantics explicit where relevant?
3. Are freshness and availability observable at the consumer boundary?
4. Does each critical quality promise have an enforced check, a production signal, a threshold, an action, and an owner?
5. Can the compatibility policy stop a semantically or structurally breaking change before release?
6. Are access, purpose, retention, deletion, residency, and audit obligations carried through derived copies?
7. Can operators trace, rebuild, restore, and verify the data from an authoritative source?
8. Will a contract breach reach named responders and affected consumers in time to limit harm?

If any answer is no, leave the contract Proposed and name the missing owner or evidence. For every later change, rerun the questions the change can affect. A contract is useful only while its tests, telemetry, lineage, and owners still describe production.