Schemas and compatibility

An event topic without a schema story is an informal API that breaks at 2 a.m.

Treat events as public APIs

Consumers will depend on field names, types, and meaning. Changing them casually is a breaking release — even if no HTTP status code is involved.

Prefer:

• a schema registry (Avro, Protobuf, or JSON Schema) with explicit subjects
• compatibility rules agreed up front (usually backward for consumers)
• additive changes first: optional fields, new event types
• explicit versioning when meaning changes

Compatibility that actually helps

Backward compatible producers can write new schemas that old consumers still read. That is the usual goal when many consumers lag behind.

Forward compatible matters when old producers still run against new consumers.

Breaking renames, type changes, and “reuse this field for something else” are how silent corruption enters projections. Prefer a new field or a new event type.

Ownership

The producing domain owns the schema. Consumers may request fields; they do not silently fork the meaning. Document:

• which service publishes
• compatibility mode
• deprecation windows
• how to introduce a replacement event

Testing contracts

Contract tests against sample payloads (and registry subjects) catch drift before production. Replay a golden set of events through consumer deserialization in CI.

If you cannot answer “what breaks if we remove this field?”, you are not ready to remove it.