Compatibility
Automated checks that a proposed schema change won't silently break an existing consumer before it's ever allowed to ship.
High-Level Design
Compatibility checking turns schema risk into an automated CI gate.
💼 Business Context
- Turns "did this schema change break anything" from a question discovered in production into one answered automatically before merge
- Gives teams confidence to evolve their event schemas without fear of an invisible downstream breakage
- Owned by Platform Engineering
🔌 Technical Overview
When a schema change is submitted to the Registry, an automated compatibility checker diffs the proposed schema against the current version using standard rules (removing a required field, narrowing a type, or removing an enum value are breaking; adding an optional field is not) and against the Registry's knowledge of active consumers where declared. Breaking changes are rejected unless explicitly submitted as a new major version with a documented migration path.
Breaking Change Examples
💾 Compatibility Check Result
{
"proposed_version": "4",
"compatible_with": "3",
"result": "breaking",
"reason": "field 'currency' changed from optional to required"
}
🔗 Integration Points
- Schema Registry API — hosts the compatibility checker
- CI/CD pipeline — schema changes run through this check before deployment, same as a code review gate
- Versioning system — breaking changes are automatically routed to major-version handling
- Developer portal — surfaces check results to the engineer proposing the change
🧰 Services Consumed
- Owning microservice —
Cxos.Processing.SchemaGovernance.Api(see the Full Application Service Map) - Database — Azure Database for PostgreSQL (relational, ACID)
⚠️ Non-Functional Considerations
- Scale: compatibility checks are fast, schema-diff operations — no meaningful performance concern
- Latency: runs synchronously in CI, adding seconds to a schema-change pull request, not minutes
- Reliability: the checker itself is tested against a suite of known-breaking and known-safe change patterns
- Security/Privacy: no data-privacy implications — this is a structural, not content, check
🎯 Enterprise Example
An engineer accidentally proposes narrowing the discount_percent field from a float to an integer. The compatibility checker flags this as breaking during the pull request, before it ever reaches production and silently truncates every discount value downstream.