Compatibility policies

Learn about the compatibility policies to be able to manage versioning of schemas in Schema Registry.

A key Schema Registry feature is the ability to version schemas as they evolve. Compatibility policies are created at the schema metadata level, and define evolution rules for each schema.

After a policy has been defined for a schema, any subsequent version updates must honor the schema’s original compatibility, otherwise you experience an error.

Compatibility of schemas can be configured with any of the following values:

Backward Compatibility: Indicates that a new version of a schema would be compatible with earlier versions of that schema. This means the data written from an earlier version of the schema can be deserialized with a new version of the schema.; When you have a Backward Compatibility policy on your schema, you can evolve schemas by deleting portions, but you cannot add information. New fields can be added only if a default value is also provided for them.
Forward Compatibility: Indicates that an existing schema is compatible with subsequent versions of the schema. That means the data written from a new version of the schema can still be read with an old version of the schema.; When you have a Forward Compatibility policy on your schema, you can evolve schemas by adding new information, but you cannot delete existing portions.
Full Compatibility: Indicates that a new version of the schema provides both backward and forward compatibilities.
None: Indicates that no compatibility policy is in place.

Validation level

Validation level limits the scope of the compatibility check when you add a new version of the schema. It checks compatibility only against the latest version or all previous versions based on the validation level value configured. Validation level only makes sense when coupled with compatibility. When compatibility is set to None then the validation is also ignored.

The validation level cannot be set from the Schema Registry UI. You can set it through the Swagger REST API. For example,

SchemaMetadata.Builder builder = new SchemaMetadata.Builder("Blah")
        .type("avro")
        .schemaGroup("Kafka")
        .description("test")
        .compatibility(SchemaCompatibility.BACKWARD)
        .validationLevel(SchemaValidationLevel.ALL);

When using the Schema Registry UI, the validation level defaults to ALL.

The supported validation levels are as follows:

All
Schemas are compatible across multiple versions, for example, with Backward Compatibility, data written with version 1 can be read with version 7 too. All is the default validation level.
Latest
There is no transient compatibility, only the latest version is used, for example, with Backward Compatibility, data written with version 1 can only be read with version 2, not with version 7.

Allowed schema changes for different compatibilities

The following table presents a summary of the types of schema changes allowed for the different compatibility types and validation levels, for a given subject.


Compatibility types	Validation levels	Changes allowed	Check against which schemas	Upgrade first
Backward	Latest	Delete fields Add optional fields	Last version	Consumers
Backward	All	Delete fields Add optional fields	All previous versions	Consumers
Forward	Latest	Add fields Delete optional fields	Last version	Producers
Forward	All	Add fields Delete optional fields	All previous versions	Producers
Full	All	Add optional fields Delete optional fields	Last version	Any order
None	All	All changes are accepted	Compatibility checking disabled	Depends