Event Versioning

Strategies for evolving event schemas over time without breaking existing consumers.

Event versioning is the practice of changing event schemas over time while keeping existing consumers working. It's the event-driven equivalent of API versioning, but often harder because events are stored and replayed.

When you publish an event, you make a promise about its structure. Consumers depend on it. If you rename a field, remove it, or change its type, things break. Unlike HTTP APIs where you control request and response, events are consumed by services you may not even know about.

The safest approach is to only make backward-compatible changes. Add new fields, but don't remove or rename existing ones. This is the same idea behind Protobuf's field numbering: old consumers ignore fields they don't recognize, and new consumers handle missing fields with defaults.

When backward compatibility isn't enough, you have a few options:

• New event types. Instead of changing OrderPlaced, create OrderPlacedV2. Both can coexist, with consumers subscribing to the version they support.
• Schema registries. Tools like Confluent Schema Registry enforce compatibility rules at the infrastructure level, rejecting changes that would break consumers.

The right strategy depends on your system. If events are ephemeral (consumed and forgotten), versioning is simpler. If you use Event Sourcing, where events are the source of truth and must be replayed from the beginning, every schema change needs careful handling.

Protobuf and Avro are popular serialization formats for events because they have built-in support for schema evolution. JSON works too, but the compatibility rules are informal and easy to break by accident.

Treat event schemas as a public API. The same discipline you apply to REST endpoints (don't break existing clients) applies to events, sometimes even more strictly, because broken events can sit unprocessed in a message broker queue for a long time before anyone notices.