Update compatibility type

When you create a new schema version in a subject, the schema registry requires that the new version is compatible with the current one. Enforcing schema compatibility helps ensure that data producers and consumers can continue to operate correctly even as the structure of the data changes.

The specific compatibility rules enforced for a subject are determined by the compatibility type property set on that subject. If a subject has no compatibility type, the compatibility type of the registry is used.

The supported values for compatibility type are Backward, Backward transitive, Forward, Forward transitive, Full, Full transitive, or None. If not explicitly set at the schema registry level, the compatibility type defaults to Backward.

Compatibility type is managed as a JSON object containing key-value pairs. For example, the following is a sample:

{
  "compatibility": "BACKWARD"
}

When you update a compatibility type for a schema registry or a subject, it applies only to new schema versions registered after the update. Existing schema versions are not re-validated against the new compatibility type, and their individual historical compatibility settings are not changed.

Configurations set at the subject level override those set at the schema registry level. If a compatibility type is not explicitly specified at the subject level, it inherits the value from the schema registry's configuration.

This document shows you how to update the compatibility type for a schema registry or for a specific subject.

Required roles and permissions

To get the permissions that you need to update compatibility type for a schema registry or subject, ask your administrator to grant you the Managed Kafka Schema Registry Editor (roles/managedkafka.schemaRegistryEditor) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to update compatibility type for a schema registry or subject. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to update compatibility type for a schema registry or subject:

  • Grant the following permission on the resource for which you want to update the compatibility type: managedkafka.config.update

You might also be able to get these permissions with custom roles or other predefined roles.

Higher-level roles like Managed Kafka Schema Registry Admin (roles/managedkafka.schemaRegistryAdmin) also include these permissions.

For more information about the predefined roles available for Managed Service for Apache Kafka, see the Access control documentation.

Update compatibility type

Console

To update the compatibility type for the entire schema registry, follow these steps:

  1. In the Google Cloud console, go to the Schema registries page.

    Go to schema registries

    A list of schema registries in your project is displayed.

  2. Click the name of the schema registry for which you want to update the compatibility type.

    The Schema registry details page opens.

  3. In the main details section for the registry, find the Compatibility type setting and click the Edit icon next to it.

    The Edit compatibility type page opens.

  4. From the Compatibility type dropdown menu, select the value.

    For more information about these values, see Schema evolution and compatibility.

  5. Click Save.

To update the compatibility type for a specific subject, follow these steps:

  1. In the Google Cloud console, go to the Schema registries page.

    Go to schema segistries

  2. Click the name of the schema registry that contains the subject.

    The Schema registry details page opens.

  3. In the Subjects in this schema registry table, click the name of the subject for which you want to update the compatibility type.

    The subject details page opens, showing the latest version of the schema. You are updating the compatibility setting for the subject itself, which affects its future evolution, not altering an older, immutable schema version.

  4. Find the Compatibility type setting for the subject and click the Edit icon next to it.

    The Edit compatibility type page opens.

  5. From the Compatibility type dropdown menu, select the value. Choosing a value here overrides the registry-level setting for this specific subject.

    For more information about these values, see About compatibility type.

  6. Click Save.

REST

To update the compatibility type, make a PUT request to the REST API endpoint for the schema registry's configuration or a specific subject's configuration. The SchemaConfig resource is used for this purpose.

Endpoint to update compatibility type for the schema registry (default config):

PUT https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/SCHEMA_REGISTRY_ID/config

Endpoint to update compatibility type for a specific subject (in the default context):

PUT https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/SCHEMA_REGISTRY_ID/config/SUBJECT_ID

Endpoint to update compatibility type for a specific subject in a specific context:

PUT https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/SCHEMA_REGISTRY_ID/contexts/CONTEXT_ID/config/SUBJECT_ID

Replace the following placeholders:

  • PROJECT_ID: your Google Cloud project ID.
  • LOCATION: the region where the schema registry exists.
  • SCHEMA_REGISTRY_ID: the ID of the schema registry.
  • SUBJECT_ID: (For subject-level updates) the ID of the subject.
  • CONTEXT_ID: (For subject-level updates within a specific context) the ID of the context.

Request Body:

Include a JSON object in the request body specifying the new compatibility type. This corresponds to the SchemaConfig resource.

{
  "compatibility": "COMPATIBILITY_TYPE"
}

Replace COMPATIBILITY_TYPE with one of the valid string values. For example—NONE, BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, or FULL_TRANSITIVE.

For more information about these values, see About compatibility type.

Example—set subject user_events compatibility to FORWARD_TRANSITIVE

Request to PUT https://managedkafka.googleapis.com/v1/projects/test-project/locations/us-central1/schemaRegistries/test_registry/config/user_events

With body:

{
  "compatibility": "FORWARD_TRANSITIVE"
}

If successful, the API returns a 200 OK status code and a response body containing the JSON representation of the updated SchemaConfig resource.

For more information, see the REST API documentation.

What's next

Apache Kafka® is a registered trademark of The Apache Software Foundation or its affiliates in the United States and/or other countries.