Skip to content
API Design Learn/Event-Driven APIs
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Schema Registries for Events

4 min read

You'll learn to

  • -Explain why event schemas need a registry when producers and consumers deploy separately
  • -Define backward, forward and full compatibility by who can read whose data
  • -Run a compatibility check on three proposed changes and read its verdicts

In a request-response API, a client and server find out about a mismatch at call time: the call simply fails, immediately and visibly. Event-driven systems do not have that luxury. A producer publishes an event today, and a consumer may not process it until minutes, hours or, when an event log is replayed, years later. By then the consumer's idea of the event's shape may have drifted from what was published.

An Analogy: The Library of Forms

Imagine a government office that publishes forms to citizens, and other offices that read the completed forms years later. If someone changes the form without telling the readers, a form filled in last year may be misread, quietly, with no error. A central library of forms, where every new version is checked against the previous one before it can be issued, stops that. That is a schema registry.

What a Schema Registry Does

A schema registry is a central service that stores every version of every event schema, and checks that a new version is compatible with the earlier ones before a producer may publish under it. A breaking change is caught at deploy time, before it reaches a single consumer, not discovered when some downstream consumer fails or silently misreads the new shape.

Compatibility Modes

  • -Backward compatible: a new schema can read data written with the previous schema. Safe to deploy new consumers first.
  • -Forward compatible: an old schema can read data written with the new schema. Safe to deploy new producers first.
  • -Full compatible: both. Safe to deploy producers and consumers in any order, which matters when you cannot guarantee that every consumer upgrades before the producer starts publishing the new shape.
A backward-compatible change: adding an optional field with a default
// v1 event
{"event_type": "order.placed", "order_id": 501, "total": 149.99}

// v2 event - backward compatible: old consumers reading this simply
// ignore the new field they don't know about
{"event_type": "order.placed", "order_id": 501, "total": 149.99, "currency": "USD"}

The mode you need depends on deployment order. If consumers always upgrade before producers publish a new shape, one direction may be enough. If you cannot guarantee that, as is usual with many independent consumer teams, full compatibility is the safer choice. The demo is a miniature registry. It checks three proposed changes to the order event in both directions, and says what each one allows.

Press Run: an optional field is accepted; a required one or a rename is not

Why This Matters More for Events Than Request-Response

A REST or GraphQL incompatibility fails loudly at call time. An incompatible event can fail silently and much later: a consumer may deserialize an event using stale assumptions about its shape, process it wrongly with no error at all, and the mistake shows up far downstream, or never. That is why checking compatibility before a producer may publish matters more here than in synchronous APIs.

This extends the schema-versioning discipline from the database chapters, applied to event schemas flowing between services instead of one database's own changing structure.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Schema Registry in the API Design Lab's gRPC & Event-Driven act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!