An API field change can look harmless to its producer and still break an executive dashboard weeks later. Analytics consumers often depend on meaning, null behavior, units and delivery timing that are invisible in a JSON example. A data contract makes those expectations explicit and gives teams a safer way to evolve them.
A useful contract includes field name, type, required/optional status, null semantics, units, allowed values, owner, sensitivity classification, freshness expectation and compatibility policy. For an event stream, include event identity, ordering assumptions and whether consumers may receive duplicates. For an API, document request and response behavior, errors and pagination as well as shape.
| Change | Structural question | Business question |
|---|---|---|
| Add optional field | Can old readers ignore it? | Will downstream models silently omit a now-important dimension? |
| Rename or remove field | Can old consumers still parse payload? | Which reports and historical queries depend on its meaning? |
| Change number to string | Does the schema validator accept it? | Are sorting, aggregation and units still correct? |
| Change enum values | Are unknown values allowed? | Do dashboards bucket new states correctly? |
| Change timestamp semantics | Is the field still a valid timestamp? | Did timezone or event-time vs processing-time meaning shift? |
Backward compatibility is useful, but the exact rules differ among JSON Schema, Avro and Protobuf and among registry configurations. A structurally valid change can still change business meaning. Keep semantic definitions and examples next to the schema, then test both validation and downstream expectations.
Version contracts in source control, assign a producer owner and list critical consumers. Pull requests should run syntax validation, compatibility checks and representative analytics tests. A breaking change should identify affected consumers, provide a migration window and, where practical, dual-write or publish a new version before retiring the old one.
Preserve raw source records with ingestion time and schema version so a transformation can be replayed after a bug fix. Do not silently coerce malformed values to zero or empty strings; route invalid records to a quarantine path with counts and samples scrubbed of sensitive information.
Measure contract validation failures, unknown fields or enum values, null-rate changes, freshness lag, volume shifts and consumer model failures. Tie an alert to the affected dataset and owner. Record lineage from API endpoint or event topic through staging and transformation to dashboard metric. When a metric changes, operators should be able to answer which contract version and source window produced it.
The producer owns truthful source semantics and change notice; analytics owns transformation and documented business definitions; platform teams own validation, storage and delivery controls. Contracts work when these responsibilities have named owners and a review path, not when a file exists without enforcement.
Related patterns: moving reports from Sheets to SQL and operational reports with APIs, ETL and SQL.
A data contract connects a producer’s API to the analytics decisions built on top of it. Version structural and semantic expectations, check compatibility in CI, preserve replayable raw data and monitor freshness and quality through lineage. Then a schema change becomes a reviewed migration instead of a surprise dashboard incident.