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