阅读中文版本

Pipeline Schema Contract Enforcement Workflow

Enforce an agreed schema contract between producers and consumers so upstream changes cannot silently break downstream jobs.

Overview

Prevent upstream schema changes from breaking downstream consumers silently.

This workflow is reusable across teams and environments; adapt the commands to your tooling while keeping the sequence and checkpoints intact.

Environment and prerequisites

• A schema registry or contract files
• Producer and consumer pipelines
• CI for schema checks

Procedure

1. Define the contract

Agree on required fields, types, and compatibility rules between producer and consumer.

Expected state: A written, versioned contract exists.

2. Validate producer output

Check producer events against the contract before publishing.

Expected state: Non-conforming events are rejected at the source.

3. Check compatibility on change

Compare proposed schema changes against the contract in CI.

Expected state: Breaking changes fail until consumers are updated.

4. Version and migrate consumers

Introduce a new version and give consumers a migration window.

Expected state: Consumers move to the new contract deliberately.

# fail CI on incompatible schema change
node check-schema-compat.mjs --old schema.json --new schema.next.json

Verification

Confirm a breaking schema change fails CI and the producer rejects non-conforming events.

Decision points

Allow additive changes freely?

• Allow additive, block breaking
• Block all changes

Recommendation: Allow additive changes; block breaking ones until consumers adapt.

Registry or file-based contract?

• Registry for many consumers
• File for small teams

Recommendation: Use a registry when many consumers exist; files suffice for tight teams.

Common failures

• Untracked schema drift breaks consumers overnight.
• Blocking additive changes slows delivery.
• No versioning forces all-or-nothing migrations.