Data Contracts in CI/CD: Schema Compatibility Checks

1. How do you automate data contract checks in CI/CD?

Three checks, three different failure modes, and they are not interchangeable. Run all three or accept that one class of incident stays invisible until a consumer reports it.

A GitHub Actions job that runs all three

name: Data Contract Validation

on:
  pull_request:
    paths:
      - 'contracts/**'
  schedule:
    - cron: '0 6 * * *'     # the data test, once a day

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0    # the diff needs the base commit, not a shallow clone

      - name: Install the datacontract CLI
        run: pip install datacontract-cli

      - name: Lint
        run: datacontract lint contracts/orders.yaml

      - name: Fetch the version currently on main
        run: git show origin/main:contracts/orders.yaml > /tmp/orders-main.yaml

      - name: Fail on a breaking change
        run: datacontract breaking /tmp/orders-main.yaml contracts/orders.yaml

      - name: Human-readable diff in the job log
        if: always()
        run: datacontract changelog /tmp/orders-main.yaml contracts/orders.yaml

      - name: Test the contract against live data
        run: datacontract test contracts/orders.yaml --server production
        env:
          DATACONTRACT_SNOWFLAKE_USERNAME: ${{ secrets.SNOWFLAKE_USERNAME }}
          DATACONTRACT_SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}

Two details decide whether this job is enforcement or decoration. fetch-depth: 0 is required, because the default shallow clone has no base commit to diff against and the step will pass on a repository where it cannot see the old file. And the job has to be a required status check in branch protection. A job that reports red on a mergeable pull request teaches the team to merge red. If you already run docs checks in the pipeline, the contract check belongs in the same required set; docs checks in CI covers how teams keep that set fast enough to stay required.

Where enforcement sits, in order of how early it catches

Before writing your first contract, know your flows. A data pipeline diagram shows which producer-consumer interfaces break most often, and those are the ones worth putting a contract on first.

2. Which schema compatibility mode should the check enforce?

The compatibility mode is the single setting that decides what your check actually refuses. Most teams never change it, run on the default, and are surprised when the default turns out to permit exactly the change that broke them.

The trap is replay. BACKWARD only compares against the version immediately before, so a field deleted in v2 and a different field deleted in v3 both pass, and a consumer re-reading a topic from the beginning hits data neither schema describes. Any dataset that gets replayed, or that has consumers you do not control, wants a TRANSITIVE variant. The mode is set per subject, not per cluster, so a single noisy topic does not force the whole registry into a strict mode. The compatibility rules and what a registry structurally cannot check are laid out in data contract vs schema registry.

3. What counts as a breaking change?

This is the list the compatibility check encodes. Anything on the left needs a major version and a deprecation window; anything on the right ships in a minor or patch release and merges the same day.

One row on that list is invisible to every automated check: changing field semantics. If status = 3 stops meaning shipped and starts meaning partially shipped, the schema is byte-identical and every compatibility mode passes, while every downstream aggregate is quietly wrong. That is why the contract carries a semantics block and why a semantic change is treated as a major version by policy rather than by tooling.

Versioning strategies

# Deprecation workflow for breaking changes

1. ANNOUNCE (Day 0)
   - Create deprecation notice in contract
   - Notify consumers via #data-announcements
   - Update changelog

2. DUAL-WRITE (Day 0-60)
   - Keep old field + add new field
   - Both populated during transition
   - Monitor which consumers migrate

3. WARN (Day 60-90)
   - Log warnings when old field accessed
   - Direct outreach to remaining consumers
   - Offer migration support

4. REMOVE (Day 90+)
   - Remove deprecated field
   - Bump major version
   - Old versions archived but accessible

4. How do you wire contracts into Kafka and Confluent Schema Registry?

On a streaming stack the compatibility half of the contract is already available: the registry does it. Three settings turn it from a schema store into an enforcement point.

<!-- pom.xml: the candidate schema is checked against the registered subject -->
<plugin>
  <groupId>io.confluent</groupId>
  <artifactId>kafka-schema-registry-maven-plugin</artifactId>
  <version>7.6.0</version>
  <configuration>
    <schemaRegistryUrls>
      <param>https://schema-registry.internal:8081</param>
    </schemaRegistryUrls>
    <subjects>
      <orders-value>src/main/avro/order.avsc</orders-value>
    </subjects>
  </configuration>
</plugin>

# In CI, on the pull request:
mvn io.confluent:kafka-schema-registry-maven-plugin:test-compatibility

# On merge to main, once the build is green:
mvn io.confluent:kafka-schema-registry-maven-plugin:register

Confluent also ships a feature named Data Contracts on top of the registry: schema and field level metadata, rulesets with domain validation rules written in CEL, migration rules using JSONata, and tags that drive downstream policy. It closes the value validation gap for streaming, which the schema alone cannot cover. What it does not change is the boundary: it applies to messages on topics, at publish time, for producers using that registry. The warehouse table analysts query, the nightly vendor file, and the freshness of both stay outside it, which is why teams running Confluent Data Contracts still keep contract files for the landed datasets. The reference material is in the Confluent Schema Registry documentation. For the topology itself, a Kafka streaming architecture diagram is the fastest way to show which subjects sit between which services.

5. What is the difference between a data contract and a schema?

A schema describes shape: field names, types, nullability. A data contract wraps that schema in commitments the shape cannot express, and the schema ends up as one section of it, usually the first. The useful mental model is the API contract, which nobody would reduce to a request body.

A schema registry is a tool that stores and validates schemas at publish time. A data contract is a practice that may use one. The registry cannot see a change in the meaning of a field, a shift in value distribution, a pipeline that stopped running, or anything in a warehouse table with no registry in front of it, which is the case for most analytical consumption. The full comparison, including which of the four gaps Confluent closes, is in data contract vs schema registry.

6. What should a data contract specification include?

Seven blocks. Not every contract needs all of them, but a contract missing the owner or the deprecation policy will not survive its first disagreement.

# contracts/orders.yaml
apiVersion: v1
kind: DataContract
metadata:
  name: orders
  version: 2.1.0
  owner: [email protected]
  description: Order transactions from all sales channels
  tags: [commerce, transactions, pii]

schema:
  type: object
  properties:
    order_id:
      type: string
      format: uuid
      description: Unique order identifier
      pii: false
    customer_id:
      type: string
      description: Customer who placed the order
      pii: true
    order_date:
      type: string
      format: date-time
      description: When the order was placed (UTC)
    status:
      type: string
      enum: [pending, confirmed, shipped, delivered, cancelled]
      description: Current order status
    total_amount:
      type: number
      minimum: 0
      description: Total order value in USD
  required: [order_id, customer_id, order_date, status, total_amount]

sla:
  freshness: PT1H          # Data no older than 1 hour (ISO 8601)
  availability: 99.9%      # Uptime target
  updateFrequency: PT15M   # Updates every 15 minutes

quality:
  rules:
    - name: unique_order_id
      type: unique
      column: order_id
    - name: valid_total
      type: range
      column: total_amount
      min: 0
      max: 1000000
    - name: no_future_orders
      type: custom
      sql: "order_date <= CURRENT_TIMESTAMP"

versioning:
  strategy: semantic        # major.minor.patch
  deprecationPolicy: 90d    # 90 days notice for breaking changes
  changeLog: https://wiki.company.com/data/orders/changelog

alerts:
  slack: "#data-alerts"
  pagerduty: commerce-oncall
  email: [[email protected]]

Using the Open Data Contract Standard instead of your own keys

ODCS is a YAML standard maintained by the Bitol project under the Linux Foundation, and it covers the same seven blocks with fixed key names: apiVersion, kind, id, name, version and status at the top, field definitions under schema, connection details under servers, the freshness and availability promises under slaProperties, and ownership under team and roles. The gain is not elegance, it is tooling: a standard file is something a linter, a catalog, and someone else's importer already understand. The datacontract CLI reads and writes it, and exports the same contract to Avro, JSON Schema, dbt, SQL DDL or Great Expectations, so one file can feed the registry and the warehouse tests. The section-by-section layout is in what is in a data contract.

7. Which schema language should the contract use?

The schema is the structural foundation of your contract. It defines what fields exist, their types, and basic constraints. Choose a schema language that your ecosystem supports, because the checker you get for free is the one that matters.

In the warehouse the equivalent of a registry is the dbt model contract: contract: { enforced: true } on the model config makes the run fail when the model output does not match the column names and data types declared in the YAML, which puts the same gate on a table that a registry puts on a topic. It checks shape only, so the quality rules still need Soda, Great Expectations, or dbt tests next to it.

What to include in the schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Order",
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique order identifier"
    },
    "customer_id": {
      "type": "string",
      "pattern": "^CUS-[A-Z0-9]{8}$",
      "description": "Customer ID in format CUS-XXXXXXXX"
    },
    "order_date": {
      "type": "string",
      "format": "date-time"
    },
    "status": {
      "type": "string",
      "enum": ["pending", "confirmed", "shipped", "delivered", "cancelled"]
    },
    "items": {
      "type": "array",
      "items": { "$ref": "#/definitions/OrderItem" },
      "minItems": 1
    },
    "total_amount": {
      "type": "number",
      "minimum": 0,
      "exclusiveMaximum": 1000000
    }
  },
  "required": ["order_id", "customer_id", "order_date", "status", "items", "total_amount"],
  "additionalProperties": false
}

8. How do you put SLAs and quality rules in the contract?

Schema defines structure. SLAs and quality rules define behavior and reliability. These are the promises that make contracts meaningful, and the ones the compatibility check never looks at.

A promise nobody measures is a comment. Freshness and volume SLAs need a monitoring layer that watches arrival times and row counts without being told what to expect, which is what data observability adds on top of explicit tests. Consumers also have to be able to find the contract before they depend on the table, so it belongs next to the dataset in the catalog; data catalog best practices covers how to keep that registration automatic instead of a launch-day chore.

Service level agreements

Quality rules (beyond schema)

9. How do you evolve a schema without breaking downstream consumers?

Expand, then contract. Every safe migration is the same four moves: add the new field alongside the old one, populate both, wait for consumers to move, remove the old one in a major version. The 90-day deprecation workflow above is that pattern with dates attached. Nothing in it is hard. The part teams get wrong is knowing when the wait is over.

Where the picture goes stale is the diagram of who produces and who consumes. Datadef connects read-only to the GitHub, GitLab, or Azure DevOps repository that produces the dataset and redraws the architecture diagram and an architecture.md every day, so the producer-consumer map a reviewer opens during a contract change is the one that shipped rather than a drawing from two quarters ago. A commit that changes nothing structural does not redraw the diagram, and nodes moved by hand keep their position. The diagram embeds as a live image in the README next to the contract file, so the two are read together. See repository sync for what it reads.

10. What to do when a contract check fails

A message along the lines of "the data received does not meet the data contract expectations" means one thing: a validator compared a payload against the registered contract and found a mismatch. The message rarely says which of the three causes it is, and they have different owners.

Rejected records go to a quarantine table or a dead letter queue keyed by the run id, never silently dropped and never waved through into the sink. Quarantine keeps the failure debuggable: you can count how many records failed, see the offending values, and replay them once the producer ships a fix. The one response to avoid is editing the contract to match the data. That is not a fix, it is a rename of the incident, and it removes the only record of what was promised.

11. What tools track schema versions, compatibility, and lineage?

Three layers, and rarely one product. A registry or buf versions the schema and answers the compatibility question. A contract runner (datacontract CLI, dbt contracts, Soda, Great Expectations) runs the checks in CI and against landed data. A catalog holds the lineage that says which consumers a change would reach. Here is what teams are using in 2026.

The gap most stacks have is the third layer. Versioning and testing are solved by the first two rows and the answer is boring; knowing that dropping order_channel hits four dbt models and a finance dashboard is what stops the deprecation from becoming an incident, and that needs lineage down to the column. Data lineage tools compares the options for that layer.

12. How do you roll contracts out across teams?

Consumer-driven, or it does not get written. Producers rarely know which of their hundred columns matter, so a contract they author alone documents everything and commits to nothing. Ask each consuming team to write down the fields and guarantees it actually depends on, merge those into one contract, and leave anything nobody claimed out of scope. Then run the check in the producer repository, so the failure lands on the person who can fix it.

Who is involved

Implementation checklist

13. Frequently asked questions