Skip to main content
Schemas change. Fields get added, renamed, and dropped, and each change risks breaking applications that are already reading the topic. A compatibility mode turns that risk into a rule the registry enforces at registration time, so an incompatible change fails when you deploy it rather than when a consumer hits a record it can’t decode.

​
Compatibility modes

Each subject has one mode. When a producer registers a new schema, the registry compares it against the versions already in that subject according to the mode. BACKWARD is the default for every format.
ALWAYS_INCOMPATIBLE has no Confluent equivalent. Use it to freeze a subject—the first schema registers normally, and every subsequent registration is rejected. Confluent client libraries may not accept it as a value, in which case set it through the REST API.

​
The transitive property

The non-transitive modes check only against the latest version. The transitive modes check against every version in the subject. The difference matters over a series of changes that are each individually fine but collectively aren’t. Under BACKWARD, you can delete field a in v2 and re-add it with a different type in v3: each step passes against its immediate predecessor, but a consumer on v3 can’t read v1 data. Under BACKWARD_TRANSITIVE, v3 is rejected. Use a transitive mode when consumers may lag far behind, when you replay history, or when a topic retains data long enough that old versions stay reachable.

​
Order of upgrading clients

The mode determines which side you deploy first. Getting this backwards breaks consumers in production even though every schema passed its check. BACKWARD is the default because the consumer-first order matches how most teams deploy: roll out readers, then flip writers.

​
Per-format rules

The three formats do not share one definition of “compatible.” A change that’s safe in Avro can break JSON Schema, and Protobuf has rules that come from its field-numbering model rather than from the registry. For Avro, compatibility follows the Avro schema resolution rules. Defaults are what make a field addition backward compatible—a field with no default has nothing for the reader to fall back on. For JSON Schema, additionalProperties governs almost everything. A schema that allows additional properties has an open content model, and adding a required property to one is a breaking change, which produces the “open content model” error at registration. For Protobuf, field numbers are identity. Never reuse a number you’ve retired—reserve it.
The compatibility table on Overview lists FORWARD, FORWARD_TRANSITIVE, FULL, and FULL_TRANSITIVE as unsupported for Protobuf. The API accepts those values on a Protobuf subject rather than rejecting them, but the combination isn’t validated or supported. Use BACKWARD or BACKWARD_TRANSITIVE for Protobuf subjects.
Changing a subject’s format—registering a JSON schema on a subject holding Avro versions—is always rejected with HTTP 409, in every mode.

​
Set the compatibility mode

Set the mode on a subject:
Read it back:
The global GET /config always returns {"compatibilityLevel":"NONE"} regardless of what’s actually in force. The real default is BACKWARD. Always read the per-subject GET /config/{subject} instead.There is also no PUT /config—the global default can’t be changed through the API. Set the mode per subject.

​
Test a schema before you register it

Check a candidate schema against a subject without registering it. This is the call to put in CI:
Add ?verbose=true to get the reason a check failed rather than just false. To check against every version rather than one, post to /compatibility/subjects/{subject}/versions instead. Both endpoints are POST.

​
Next steps

Key concepts

Subjects, versions, schema IDs, and the wire format.

Confluent compatibility

Behavior differences that affect compatibility handling.