中文
devexamples
← Workflows

阅读中文版本

Event Schema Evolution Workflow

Version event schemas, migrate producers and consumers compatibly, and use a registry to block incompatible changes before they reach the broker.

intermediate~90 mineventsschemamessaging

Objective

Evolve event schemas across producers and consumers without breaking either side.

Environment

  • A schema registry with compatibility rules
  • Producers and consumers that can be deployed independently

Steps

1. Define the compatibility policy (backward, forward,

Define the compatibility policy (backward, forward, or full).

Expected state: The rule for allowed changes is explicit.

2. Register each schema version and let

Register each schema version and let the registry check compatibility.

Expected state: Incompatible changes are rejected at publish time.

3. Adopt new fields as optional

Adopt new fields as optional with defaults first.

Expected state: Old consumers keep working.

4. Remove fields only after all consumers

Remove fields only after all consumers have moved.

Expected state: Removal is safe.

Decision points

Which compatibility mode?

  • Backward
  • Full

Backward is common; full when you cannot control the order of producer and consumer deploys.

Embed schema or reference the registry?

  • Reference the registry
  • Embed the schema

Reference the registry when you need central governance; embed for resource-constrained producers.

Expected outcome

Events evolve through registered, compatible versions so producers and consumers can deploy independently.

Verification

Confirm the registry rejects an incompatible change, and that old consumers still process events with new optional fields.

Cleanup

Record the compatibility decision and update consumer documentation.

Overview

Evolve event schemas across producers and consumers without breaking either side. Confirm the registry rejects an incompatible change, and that old consumers still process events with new optional fields.

Steps

  1. Define the compatibility policy (backward, forward, or full). Expected state: The rule for allowed changes is explicit.
  2. Register each schema version and let the registry check compatibility. Expected state: Incompatible changes are rejected at publish time.
  3. Adopt new fields as optional with defaults first. Expected state: Old consumers keep working.
  4. Remove fields only after all consumers have moved. Expected state: Removal is safe.
{
  "schema": "{\"type\":\"record\",\"fields\":[{\"name\":\"channel\",\"type\":\"string\",\"default\":\"web\"}]}",
  "compatibility": "BACKWARD"
}

Verification

  • Events evolve through registered, compatible versions so producers and consumers can deploy independently.

Decision points

  • Which compatibility mode? Options: Backward; Full. Recommended: Backward is common; full when you cannot control the order of producer and consumer deploys.
  • Embed schema or reference the registry? Options: Reference the registry; Embed the schema. Recommended: Reference the registry when you need central governance; embed for resource-constrained producers.