An API contract describes how a consumer interacts with an interface. A data contract records the expectations that make its data usable: meaning, quality, freshness, ownership, and change responsibilities. For a data product delivered through an API, maintain both perspectives and connect them to the same fields, consumers, and release.
This is a practical design convention, not a universal boundary between two kinds of document. An API description can include business definitions and service expectations. A data contract can describe an API delivery interface. The useful question is whether a consumer can understand the interaction, interpret the result, and know what to do when an expectation fails.
Consider an application that routes service work using customer status. A response can be valid JSON with a permitted status value and still represent the wrong business state or an old source snapshot. Conversely, accurate data is unusable if the consumer cannot authenticate or handle the interface’s errors. A review needs to cover both.
What an API contract describes
For this comparison, an API contract is the maintained agreement about the consumer-visible interface: operations, request parameters, response shapes, error behavior, and security requirements. For HTTP APIs, the OpenAPI Specification provides a standard description format for these interface details, including schemas and human-readable descriptions.
An interface review should make a consumer’s integration decisions explicit:
- Which operation serves the task, and which identifier does it accept?
- Which response fields are required, optional, or nullable?
- How are authentication, authorization failures, missing records, and temporary unavailability represented?
- Which interface version is supported, and how does the consumer identify it?
A description of a security requirement does not itself implement access control. Likewise, publishing a response schema does not prove deployed responses conform to it. Link the contract to the implementation and its checks. Keep examples, generated clients, and the supported release aligned.
What a data contract adds about meaning, quality, and ownership
Use the data contract to make the producer’s data commitments and the consumer’s assumptions reviewable. The Open Data Contract Standard (ODCS) is one structured approach; its sections cover schema, quality, support, teams, roles, and service levels. Adopting a format is a separate decision from implementing and monitoring the commitments.
For your own product, ask what a field means in the consumer’s decision. Does active mean an open service account, a recent purchase, or permission to receive marketing? Does a timestamp describe a business event or the source checkpoint represented by a snapshot? Record the answer once in a maintained definition and reference it wherever the field appears.
| Concern | API perspective | Data perspective |
|---|---|---|
| Structure | Request and response fields, types, requiredness, and serialization. | Record grain, keys, relationships, and how source values become delivered fields. |
| Meaning | Descriptions help consumers interpret parameters and responses. | Business definitions resolve status meanings, units, nulls, exclusions, and source authority. |
| Quality | Interface checks examine whether a response matches the declared shape. | Data checks examine agreed rules across records, such as unique keys or valid transformations. |
| Freshness | Expose the agreed timestamp or stale-data error behavior. | Define the timestamp’s basis, acceptable age, measurement, and response to a breach. |
| Ownership | Identify who maintains and supports the interface. | Identify who accepts definitions, fixes source issues, and owns consumer impact. |
| Permissions | Describe the identity and consumer-visible authorization behavior. | Record the approved purpose, records, fields, and scope review responsibilities. |
| Change | Assess effects on existing requests, parsers, and integrations. | Assess changes in meaning, quality, source coverage, and supported use as well. |
These are review prompts, not exclusive capabilities of either document type. A team can keep the information in linked files or one maintained package. For the surrounding ownership and consumption model, see what a data product is and our guide to governed enterprise data delivery.
A side-by-side customer-status example
Synthetic design example: Customer Status for Service Operations supplies a regional routing application with current service state. All identifiers, values, targets, and interface paths below are illustrative. They are not a live endpoint, measured service levels, or Elementrix feature claims.
Connect one response to its interpretation
The proposed operation is GET /v1/customer-status/{customer_id}. This example uses a fixed response projection for regional-routing-app:
{
"customer_id": "CUST-317",
"account_status": "active",
"service_region": "REGION-A",
"product_as_of": "2026-10-25T06:00:00Z"
}
| Decision | Interface agreement | Data agreement |
|---|---|---|
| Customer identity | customer_id is a required string in the response and the lookup path. | Opaque enterprise customer key; one current record per key in the snapshot. Duplicate keys prevent promotion of a candidate snapshot. |
| Service state | account_status is required; allowed values are active, suspended, and closed. | State of the service account in the designated source. It does not express payment standing, consent, or a credit decision. |
| Region | service_region is a required controlled code. | The operational assignment used for the example’s record-scope rule. Delivery must restrict the application to its assigned region. |
| Data age | product_as_of is a required UTC timestamp. The example proposes a documented unavailable response when its age exceeds the limit. | A source completeness checkpoint represented by the snapshot. Proposed maximum age: 15 minutes, measured at delivery. A recent processing clock alone is insufficient. |
| Failures | Specify distinct authentication and unavailable errors; use the same non-disclosing not-found behavior for unknown and out-of-region identifiers. | Hold the last valid snapshot only while it remains within the proposed age limit. The delivery operator investigates failures; the source steward resolves incorrect source meaning. |
| Change responsibility | The interface owner reviews parser and response compatibility. | The product owner and consumer owner review whether changed data still supports routing, and agree any migration before release. |

Walk through two failures before accepting the contract
First, imagine two source records for CUST-317 enter a candidate snapshot. Each record individually matches the response schema. The cross-record uniqueness rule still fails. Under the example’s proposed rule, the operator rejects that candidate, measures the remaining age of the last valid snapshot, and follows the agreed degraded behavior. Schema validation alone would miss this failure.
Second, suppose the source changes the definition of active to include accounts waiting for service activation. The field name, type, and enum remain unchanged. The routing application’s interpretation has changed. The product owner must resolve the definition and consumer impact before release; an unchanged JSON shape is insufficient evidence of compatibility.
Use the data product specification template for a broader worksheet. The comparison here helps reviewers decide where each commitment is maintained and how the two perspectives connect.
Connect field permissions and change rules
Keep a maintained chain from consumer purpose to approved scope, delivered representation, checks, and release evidence. In the example, approval for regional routing covers four fields and assigned-region records. It does not authorize adding email merely because the upstream source now supplies it.
Review every change along three dimensions: can the existing consumer still parse the response; does the result still mean what its workflow expects; and is every delivered record and field still authorized? A technically additive field may change exposure. An added enum value may require consumer behavior changes even though it remains a string.
Assign one authoritative location for each definition. For example, the data dictionary owns status meaning, the interface description owns wire representation, and the approved-scope record owns access decisions. Link them by product ID, contract revision, interface version, and consumer identity. Do not assume those version numbers must advance together; record their supported combination for each release.
Before promotion, propose checks for the approved response, cross-region denial, excluded-field absence, invalid status values, duplicate snapshot keys, and stale data. Record actual outcomes only after executing the checks. A contract document or access rule does not by itself establish that all these checks run.
A contract review checklist you can copy
Bring the interface owner, product owner, delivery operator, and one consumer owner to the review. Fill the record below for one use case. Replace role labels with accepted team contacts and replace proposed thresholds with agreed, measurable commitments.
| Review question | Record before approval |
|---|---|
| Can the consumer integrate? | Operation; interface version; response schema; authentication; documented error behavior; consumer owner. |
| Can the consumer interpret the result? | Grain; identifier meaning; enum definitions; null and missing-record semantics; authoritative definition link. |
| Can someone measure the commitments? | Quality rule or age limit; measurement basis; check location and frequency; accountable responder; failure action. |
| Is the delivered scope approved? | Application or user identity; purpose; record and field scope; approval reference; review trigger. |
| Can a change be released safely? | Affected consumers; parser, meaning, and access review; migration plan; recovery criteria; retirement decision where needed. |
| What is still unverified? | Open issue; owner; due date; implementation or check evidence needed; decision and review date. |
Keep format validation, runtime behavior, and operating evidence separate in this record. For example, ODCS quality rules can express different kinds of quality expectations, including textual and executable forms. Your selected tooling and delivery path still need to implement the relevant checks and route failures. Writing a rule is an input to that work.
Review one consumer contract with the Elementrix team
Bring one consumer task, its response example, the field definitions, approved scope, and the commitments you need to measure. Use an Elementrix demo to review which requirements the current implementation supports, which need integration, and which still need evidence. Start with the unresolved decisions in the checklist so the discussion leads to a concrete design.