Schema Registry

A schema registry stores versioned event or message schemas and enforces compatibility rules so producers can evolve data without breaking consumers.

data-integration

Definition

A schema registry is a centralized service that stores schemas by subject and version. Producers register a schema before publishing; consumers retrieve it to deserialize. The registry enforces a compatibility policy such as backward, forward, or full compatibility, rejecting a new version that would break existing readers or writers.

Context and scope

Registries are used with Kafka, event-driven systems, and service contracts where many producers and consumers evolve independently. They make schema changes explicit rather than relying on informal coordination.

Common misconceptions

A registry guarantees semantic compatibility — it checks structural rules, not whether a field means the same thing
Any additive change is safe — a new required field can break consumers that construct the event
The registry is optional if the team is small — small teams become large, and unversioned events become permanent contracts

Anti-patterns

Allowing producers to publish arbitrary schemas with no compatibility check
Using one subject for unrelated event types
Breaking changes hidden behind a new event name without migrating consumers

Related concepts

Authoritative source

https://docs.confluent.io/platform/current/schema-registry/fundamentals/index.html

Schemas are contracts

An event is consumed by projections, services, and analytics. If a producer renames customer_id to customerId, every consumer that reads the old field breaks. A registry stores each schema version and rejects changes that violate the chosen compatibility mode.

{
  "subject": "orders-value",
  "version": 3,
  "schema": "{\"type\":\"record\",\"name\":\"Order\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"total\",\"type\":\"long\"}]}",
  "compatibility": "BACKWARD"
}

The exact payload depends on the registry and serialization format. The key idea is a versioned, addressable schema rather than an implicit structure inside each producer.

Compatibility modes

Backward compatibility means new consumers can read old data; forward means old consumers can read new data; full requires both. Additive optional fields are usually backward compatible. Removing a required field or changing its type is not. Choose a mode per subject based on who deploys when, and test a producer upgrade against real consumers.

Keep subjects meaningful

A subject should represent one event type or one topic value schema. Mixing unrelated events in one subject makes compatibility checks meaningless and forces consumers to branch on structure. Version the event name only for a genuine new contract; otherwise evolve the schema under the registry’s rules.

When to use it

Use a registry when multiple producers and consumers evolve independently and a broken event can cause silent data loss or outages. The advantage is enforceable, discoverable contracts; the drawback is another service, serialization overhead, and the discipline of compatibility reviews. Compared to a wiki page with schema examples, a registry enforces the contract in the publish path.