How to Choose Kafka Schema Registry Compatibility Modes: BACKWARD / FORWARD / FULL for Real Ops and CCDAK

Schema evolution is at the heart of running Kafka in production. Pick the wrong compatibility mode and consumers will fail to read data mid-rollout. CCDAK in particular loves to ask about which side you update first and how that maps to compatibility modes.

This article walks through the essence of BACKWARD / FORWARD / FULL, the transitive variants, how they line up with deployment strategy, and the common pitfalls — all aligned with the official documentation. The final section includes a REST API example and a practice question.

Compatibility Mode Basics and How to Choose

Compatibility modes are how Schema Registry validates, at registration time, whether a new schema can be safely read and written compared to the previous (or historical) schema. The key question is which side you roll out first.

BACKWARD guarantees that consumers on the new schema can read data produced under the old schema — best when consumers go first. FORWARD guarantees that consumers on the old schema can read data produced under the new schema — best when producers go first. FULL satisfies both directions at once, and is the right choice when the mixed-version window is long or you genuinely need two-way compatibility.

• Updating consumers first → BACKWARD (or BACKWARD_TRANSITIVE)
• Updating producers first → FORWARD (or FORWARD_TRANSITIVE)
• Mixed versions in flight, strict contracts, or long rollouts → FULL (or FULL_TRANSITIVE)
• Avoid NONE by default; only use it for brief, exceptional fixes in production

Rollout direction vs. compatibility mode (conceptual diagram)

時間 -->

消費者先行（BACKWARD）:

  Consumer v2 (new schema)
        ^             ^ 読める
        |             |
  Consumer v1   <-  Data by Producer v1/v2

生産者先行（FORWARD）:

  Data by Producer v2 (new schema)  ->  Consumer v1 (old schema) 読める
                 ^ 生産者を先に切替

FULL（双方向）:

  Producer v1/v2 混在 <-> Consumer v1/v2 混在
  どちらの組み合わせでも読めることを要求

Transitive vs. Non-Transitive: Thinking About History

BACKWARD and FORWARD each come in two flavors: a regular mode that only compares against the immediately previous version, and a transitive mode (_TRANSITIVE) that compares against every version in the history.

For long-lived topics or environments where many applications update incrementally, the transitive mode is the safer default. The regular mode is reasonable when you can guarantee every client will catch up quickly.

• BACKWARD_TRANSITIVE: the new schema must be able to read every historical version of the data
• FORWARD_TRANSITIVE: every historical schema must be able to read data produced by the new one
• FULL_TRANSITIVE: both directions, against the full history — the strictest option
• When in doubt, start with TRANSITIVE — it is especially valuable in organizations where old apps stick around

Safe and Dangerous Patterns for Schema Evolution (Avro / JSON Schema / Protobuf)

Schema Registry supports Avro, JSON Schema, and Protobuf, but compatibility checks follow each format's resolution rules. Below are representative patterns generally considered safe in practice (the details depend on each official spec).

In Avro, default values are critical — they largely determine whether adds and removes are safe. In Protobuf, the no-reuse rule for field numbers and disciplined reservation management are key.

• Avro: adding a field is generally BACKWARD-safe if you include a default. Removing a field is usually safe on the FORWARD side. Type promotions (e.g. int → long) have a defined allowed range.
• JSON Schema: adding optional properties is generally safe. Making fields required or tightening constraints tends to be breaking.
• Protobuf: adding new fields is normally safe (proto3 treats them as optional by default). Changing or reusing field numbers is forbidden. Renaming fields rarely affects wire compatibility, but field numbers are sacred.
• Be careful when removing or changing the meaning of enum values. Design in an UNKNOWN-equivalent handler upfront.
• Making a field required, inverting its meaning, or changing ID semantics can pass the mechanical compatibility check yet still break logical compatibility — always review these manually

Combining Deployment Strategy with Compatibility Modes

If your rollout order lines up with the compatibility mode, you can survive a long mixed-version window without incidents. When they do not match, unreadable data starts appearing partway through the rollout.

Subject naming strategy (TopicNameStrategy / RecordNameStrategy / TopicRecordNameStrategy) also shapes your evolution plan. If you reuse records or share schemas across topics, consider a RecordNameStrategy variant so you can control blast radius at the subject level.

• Consumers first: BACKWARD family. The assumption is that new-schema consumers can interpret old data.
• Producers first: FORWARD family. The assumption is that old consumers can interpret new data.
• Bidirectional or long mixed-version periods: FULL family. You lose some change freedom but operations get noticeably more robust.
• The subject is the unit for minimizing blast radius. Override at the subject level when the global setting is not the right fit.

Configuration and Validation Workflow (Schema Registry REST API)

Compatibility can be set globally and per subject. The safe default is to keep the global setting conservative and only override the exceptional subjects.

Always run a pre-flight check against the compatibility API before applying to production, and wire it into CI.

• Global setting: PUT /config with compatibility.level
• Subject override: PUT /config/{subject}
• Pre-flight check: POST /compatibility/subjects/{subject}/versions/{version} with the new schema
• Register: POST /subjects/{subject}/versions with the new schema

Example: setting compatibility mode and running a pre-flight check (Avro, application/json)

## グローバル互換性をFULL_TRANSITIVEに設定
curl -s -X PUT \
  -H "Content-Type: application/json" \
  --data '{"compatibility": "FULL_TRANSITIVE"}' \
  http://localhost:8081/config

## サブジェクト単位で上書き（topic-valueをBACKWARDに）
curl -s -X PUT \
  -H "Content-Type: application/json" \
  --data '{"compatibility": "BACKWARD"}' \
  http://localhost:8081/config/my-topic-value

## 既存バージョン（latest）との互換性を事前チェック
NEW_SCHEMA='{
  "schema": "{\"type\":\"record\",\"name\":\"User\",\"fields\":[{\"name\":\"id\",\"type\":\"long\"},{\"name\":\"name\",\"type\":\"string\",\"default\":\"\"}]}"
}'

curl -s -X POST \
  -H "Content-Type: application/json" \
  --data "$NEW_SCHEMA" \
  http://localhost:8081/compatibility/subjects/my-topic-value/versions/latest

## 問題なければ登録
curl -s -X POST \
  -H "Content-Type: application/json" \
  --data "$NEW_SCHEMA" \
  http://localhost:8081/subjects/my-topic-value/versions

Exam Tips and Common Pitfalls

On CCDAK, mixing up the compatibility name and the rollout direction is the classic trap. BACKWARD means 'new reads old'; FORWARD means 'old reads new'. Drill the direction until it is muscle memory.

Other frequent topics: TRANSITIVE vs. non-transitive, field defaults, and Protobuf field number rules. Remember that the compatibility check is a mechanical comparison against the previous version or the full history — it cannot detect semantic breakage.

• BACKWARD = consumers first; FORWARD = producers first; FULL = both directions
• TRANSITIVE compares against the full history — valuable for long-lived topics
• Avro additions require defaults. Protobuf field numbers must not change and must not be reused.
• Avoid NONE as a rule, though some teams use it briefly during a transition. Always revert it once the migration is done.

Check Your Understanding

Frequently Asked Questions