Versioning

💼 Business Context

• The business changes constantly — new fields, new event types — and versioning lets the platform evolve without a coordinated, risky big-bang migration
• Protects existing dashboards, models, and integrations from breaking when someone else's team needs a schema change
• Owned by Platform Engineering

🔌 Technical Overview

Every schema change creates a new version rather than mutating the existing one; events declare which schema version they were produced against, and consumers can request a specific version or 'latest'. The registry retains full version history so a consumer built against v2 keeps working even after v3 is published, until it's explicitly migrated — schema changes are additive-by-default, with breaking changes requiring an explicit major-version bump and a migration plan.

💾 Version History Entry

{
  "event_type": "order_paid",
  "versions": [
    { "version": "1", "status": "deprecated", "sunset_date": "2025-12-01" },
    { "version": "2", "status": "active" },
    { "version": "3", "status": "active", "changes": ["added tax_amount field"] }
  ]
}

🔗 Integration Points

• Schema Registry — version history storage and API
• Event Schema & Registry's compatibility checker — validates new versions before acceptance
• Consumers (Analytics API, AI & Insights, Activation API) — declare which schema version they are built against
• Developer portal — surfaces deprecation timelines to integration owners

🧰 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: version history storage grows slowly relative to event volume — a non-issue operationally
• Latency: not applicable — versioning is a design-time concern, not a runtime performance factor
• Reliability: deprecated versions remain functional through their sunset date, giving consumers a real migration window
• Security/Privacy: version history itself has no privacy implications — it is schema metadata only

🎯 Enterprise Example

The Commerce team needs to add a tax_amount field to order_paid. Because it's an additive change, it ships as v3 without breaking any of the dozen existing consumers still reading v2 — they migrate to the new field on their own schedule instead of on a forced deadline.