Handling Schema Evolution

Why this matters

As an API Engineer, your systems will change: new fields get added, types evolve, names get refined. If you change schemas without a plan, you break clients, pipelines, and dashboards. Handling schema evolution lets you ship changes safely and keep integrations stable.

• Real tasks you will face: add optional fields to events without breaking consumers; rename API properties with zero downtime; split a database column while keeping reads and writes working; deprecate enums across services.
• Success looks like: zero-breaking deploys, consumers unaffected, easy rollbacks, and a clear deprecation path.

Who this is for

• API Engineers and Backend Developers maintaining public/internal APIs and event schemas.
• Data/Platform engineers owning contracts between services and data pipelines.

Prerequisites

• Basic understanding of REST/JSON or gRPC/protobuf.
• Familiarity with databases and simple migrations.
• Comfort with CI/CD and gradual rollouts.

Concept explained simply

Schema evolution is how you change the shape of your data (fields, types, names) over time without breaking running systems.

• Backward compatible: new producers work with old consumers (old readers can read new data).
• Forward compatible: old producers work with new consumers (new readers can read old data).
• Fully compatible: both directions work.

Safe changes are usually additive (adding optional fields with defaults). Risky changes remove or change meaning. Plan changes in two phases:

• Expand: make the system accept both old and new shapes.
• Contract: remove old shape after every consumer has moved.

Mental model

Think of change as a bridge with two lanes:

• Write-path: what producers send/store.
• Read-path: how consumers interpret it.

Always upgrade readers before writers. Readers should tolerate unknown fields and missing optional fields. When confident all readers can handle new shape, update writers to emit it. Finally, clean up the old path.

Core patterns and rules

Worked examples

Example 1: Add an optional field to a JSON event

Goal: Add user.locale to UserCreated event.

1. Expand readers: ensure consumers ignore unknown fields or map user.locale with default "en".
2. Expand producers: start emitting user.locale when available.
3. Monitor: error rate and consumer lag.
4. Contract: none needed if field remains optional.

{
  "event": "UserCreated",
  "userId": "123"
}

{
  "event": "UserCreated",
  "userId": "123",
  "user": { "locale": "en" }
}

Example 2: Rename an API field without downtime

Goal: Rename fullName to name in a REST response.

1. Expand: return both fields; keep them consistent.

   { "id": 7, "name": "A Lee", "fullName": "A Lee" }

2. Notify: deprecate fullName with a clear timeline.
3. Cutover: after clients migrate, stop including fullName.
4. Contract: remove fullName from code and tests.

Example 3: Split a column in the database

Goal: Split address into street and city.

1. Expand: add new columns (street, city); keep address.
2. Dual-write: when receiving updates, populate both.
3. Backfill: parse address into street/city for existing rows.
4. Switch reads: update service to read street/city only.
5. Contract: stop writing address; drop column later.

Example 4: Enum evolution in Protobuf

Goal: Add enum value PREFERRED to ContactMethod.

• Safe: add a new enum value at a new numeric tag; do not reuse numbers.
• Readers: default unknown values to a safe behavior (e.g., treat as EMAIL).

Step-by-step change playbooks

1. Inventory consumers: list services, jobs, and dashboards relying on the schema.
2. Choose compatibility target: backward-only, forward-only, or both.
3. Design expand state: dual-read/dual-write, defaults, upcasters.
4. Roll out readers first: deploy tolerant parsers and feature flags.
5. Roll out writers: start producing the new shape.
6. Backfill and verify: run checksums, sample comparisons, and canaries.
7. Cutover and contract: flip reads, then remove legacy paths.
8. Post-change: add lints/guards to prevent regressions.

Exercises

Do these and compare with the solutions below. The Quick Test at the end helps you check understanding. Everyone can take it; only logged-in users get saved progress.

Exercise 1: Plan an additive change safely

Scenario: A GET /orders response needs a new optional field deliveryWindow { start, end } without breaking existing mobile apps that ignore unknown fields.

• Classify the change (compatibility type).
• Write an expand-contract plan in 5–7 steps.
• List 3 monitoring checks during rollout.

Exercise 2: Rename a field across API, DB, and events

Scenario: customer.fullName should become customer.name. There is a Postgres table, a REST response, and a CustomerUpdated event used by analytics.

• Provide an end-to-end plan covering read/write paths, dual-write, and backfill.
• Define a rollback plan.

• I confirmed consumers handle unknown fields
• I have a backfill and a rollback plan
• I monitor errors and schema compliance during rollout

Common mistakes and self-check

• Changing meaning without a new name: always introduce a new field when semantics change.
• Removing fields before auditing consumers: inventory first, contract last.
• Not versioning enums/IDs in binary formats: never reuse tags.
• Skipping reader-first rollout: update parsers before producers.
• Backfill without idempotency: make backfills re-runnable and verifiable.

Practical projects

• Build a tiny service that evolves a user profile schema through three changes: add optional field, rename, split column. Include scripts for backfill and contract tests.
• Create an event upcaster library that maps old events to the latest model; include unit tests for unknown fields.
• Implement a feature-flagged rollout that dual-writes to two tables and flips reads via a config toggle.

Learning path

• Before this: API contract testing; CI/CD basics; data modeling.
• Now: schema compatibility, expand/contract, online migrations.
• Next: consumer-driven contracts, CDC-based migrations, replay strategies and idempotent processing.

Mini challenge

Your payments service must change amount from integer cents to decimal with currency. Draft a 6–8 step expand-contract plan covering API, DB, and events. Include monitoring and a rollback trigger.

Next steps

• Take the Quick Test below to check your understanding. Available to everyone; only logged-in users get saved progress.
• Apply one worked example to a side project and practice a full expand-contract cycle.

Glossary

• Expand/Contract: phased change adding compatibility first, removing legacy last.
• Upcaster: code that upgrades older messages to the current model when reading.
• Dual-write: temporarily writing both old and new representations.
• Backfill: migrating historical data to the new shape.