Stay organized with collections
Save and categorize content based on your preferences.
When you create a new schema version, the schema registry checks that the new
version is compatible with previous versions. Enforcing schema compatibility
helps ensure that data producers and consumers continue to work correctly as the
data structure evolves.
The supported values for compatibility type are Backward, Backward
transitive, Forward, Forward transitive, Full, Full
transitive, or None.
Compatibility type is managed as a JSON object. For example:
{"compatibility":"BACKWARD"}
If not explicitly set, the compatibility type for a schema registry defaults
to Backward.
If a compatibility type isn't set on a subject, it inherits the value from
the schema registry.
Configurations set at the subject level override those at the schema
registry level.
Updating the compatibility type only affects new schema versions
registered after the update.
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
SCHEMA_REGISTRY_ID: the ID of the schema registry to update.
LOCATION: the region of the schema registry.
COMPATIBILITY_TYPE: the new compatibility type. Valid values include BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, or NONE.
Example: Update the compatibility type of the test-registry schema registry in the us-central1 region to FORWARD.
SCHEMA_REGISTRY_ID: the ID of the schema registry that contains the subject.
LOCATION: the region of the schema registry.
COMPATIBILITY_TYPE: the new compatibility type. Valid values include BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, or NONE.
Example: Update the compatibility type of the test-subject subject in the test-registry schema registry in the us-central1 region to FORWARD_TRANSITIVE.
Update compatibility for a subject in the default context:
PUT https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/SCHEMA_REGISTRY_ID/config/SUBJECT_ID
Update compatibility for a subject in a specific context:
PUT https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/SCHEMA_REGISTRY_ID/contexts/CONTEXT_ID/config/SUBJECT_ID
Replace the following path parameters:
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: the ID of the subject.
CONTEXT_ID: the ID of the context (if applicable).
Include the following JSON object in the request body:
{"compatibility":"COMPATIBILITY_TYPE"}
Replace COMPATIBILITY_TYPE with a valid value, such as FORWARD_TRANSITIVE.
Example: Set subject user_events compatibility to FORWARD_TRANSITIVE.
Request to PUT https://managedkafka.googleapis.com/v1main/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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Update compatibility type\n\n| **Preview**\n|\n|\n| This product or feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA products and features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nWhen you create a new schema version, the schema registry checks that the new\nversion is compatible with previous versions. Enforcing schema compatibility\nhelps ensure that data producers and consumers continue to work correctly as the\ndata structure evolves.\n\n- The supported values for compatibility type are **Backward** , **Backward\n transitive** , **Forward** , **Forward transitive** , **Full** , **Full\n transitive** , or **None**.\n\n- Compatibility type is managed as a JSON object. For example:\n\n {\n \"compatibility\": \"BACKWARD\"\n }\n\n- If not explicitly set, the compatibility type for a schema registry defaults\n to **Backward**.\n\n- If a compatibility type isn't set on a subject, it inherits the value from\n the schema registry.\n\n- Configurations set at the subject level override those at the schema\n registry level.\n\n- Updating the compatibility type only affects new schema versions\n registered after the update.\n\nFor more information about the compatibility types, see\n[About compatibility type](/managed-service-for-apache-kafka/docs/schema-registry/schema-lifecycle#compatibility-type).\n\nRequired roles and permissions to update compatibility type\n-----------------------------------------------------------\n\n\nTo get the permissions that\nyou need to update compatibility type for a schema registry or subject,\n\nask your administrator to grant you the\n\n\n[**Managed Kafka Schema Registry Editor**](/iam/docs/roles-permissions/managedkafka#managedkafka.schemaRegistryEditor) (`roles/managedkafka.schemaRegistryEditor`)\nIAM role on your project.\n\n\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\nThis predefined role contains\n\nthe permissions required to update compatibility type for a schema registry or subject. To see the exact permissions that are\nrequired, expand the **Required permissions** section:\n\n\n#### Required permissions\n\nThe following permissions are required to update compatibility type for a schema registry or subject:\n\n- Grant the following permission on the resource for which you want to update the compatibility type: ` ``managedkafka.config.update`\n\n\nYou might also be able to get\nthese permissions\nwith [custom roles](/iam/docs/creating-custom-roles) or\nother [predefined roles](/iam/docs/roles-overview#predefined).\n\nUpdate compatibility type for a schema registry\n-----------------------------------------------\n\n### Console\n\nTo update the compatibility type for the entire schema registry, follow these steps:\n\n1. In the Google Cloud console, go to the **Schema registries** page.\n\n [Go to schema registries](https://console.cloud.google.com/managedkafka/schema-registries)\n\n A list of schema registries in your project is displayed.\n2. Click the name of the schema registry for which you want to update the compatibility type. The **Schema registry details** page opens.\n\n3. In the main details section for the registry, find the **Compatibility type** setting and click the **Edit** icon next to it.\n\n The **Edit compatibility type** page opens.\n4. From the **Compatibility type** dropdown menu, select the value.\n5. Click **Save**.\n\n### gcloud\n\nTo update the compatibility type for a schema registry, use the\n[`gcloud alpha managed-kafka schema-registries update`](/sdk/gcloud/reference/alpha/managed-kafka/schema-registries/update) command. \n\n```\n gcloud alpha managed-kafka schema-registries update SCHEMA_REGISTRY_ID \n\n --location=LOCATION \n\n --compatibility=COMPATIBILITY_TYPE\n \n```\n\n- \u003cvar translate=\"no\"\u003eSCHEMA_REGISTRY_ID\u003c/var\u003e: the ID of the schema registry to update.\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: the region of the schema registry.\n- \u003cvar translate=\"no\"\u003eCOMPATIBILITY_TYPE\u003c/var\u003e: the new compatibility type. Valid values include `BACKWARD`, `BACKWARD_TRANSITIVE`, `FORWARD`, `FORWARD_TRANSITIVE`, `FULL`, `FULL_TRANSITIVE`, or `NONE`.\n\n**Example** : Update the compatibility type of the `test-registry` schema registry in the `us-central1` region to `FORWARD`. \n\n```\n gcloud alpha managed-kafka schema-registries update test-registry \n\n --location=us-central1 \n\n --compatibility=FORWARD\n \n```\n\n### REST\n\nTo update the compatibility type for a schema registry, make a `PUT` request to the REST API.\n\nFirst, get an access token: \n\n```\ngcloud auth application-default print-access-token\n```\n\nThen, send a `PUT` request to the registry's config endpoint: \n\n```\nPUT https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/SCHEMA_REGISTRY_ID/config\n```\n\nReplace the following path parameters:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: your Google Cloud project ID.\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: the region where the schema registry exists.\n- \u003cvar translate=\"no\"\u003eSCHEMA_REGISTRY_ID\u003c/var\u003e: the ID of the schema registry.\n\nInclude the following JSON object in the request body: \n\n```json\n{\n \"compatibility\": \"\u003cvar translate=\"no\"\u003eCOMPATIBILITY_TYPE\u003c/var\u003e\"\n}\n```\n\nReplace \u003cvar translate=\"no\"\u003eCOMPATIBILITY_TYPE\u003c/var\u003e with a valid value, such as `NONE`, `BACKWARD`, `FORWARD`, or `FULL`.\n\nIf successful, the API returns a `200 OK` status code.\n\n\u003cbr /\u003e\n\nUpdate compatibility type for a subject\n---------------------------------------\n\n### Console\n\nTo update the compatibility type for a specific subject, follow these steps:\n\n1. In the Google Cloud console, go to the **Schema registries** page.\n\n [Go to schema registries](https://console.cloud.google.com/managedkafka/schema-registries)\n2. Click the name of the schema registry that contains the subject. The **Schema registry details** page opens.\n\n3. In the **Subjects in this schema registry** table, click the name of the subject.\n4. Find the **Compatibility type** setting for the subject and click the **Edit** icon next to it.\n\n The **Edit compatibility type** page opens.\n5. From the **Compatibility type** dropdown menu, select the value. Choosing a value here overrides the registry-level setting for this subject.\n6. Click **Save**.\n\n### gcloud\n\nTo update the compatibility type for a subject, use the\n[`gcloud alpha managed-kafka schema-registries subject update`](/sdk/gcloud/reference/alpha/managed-kafka/schema-registries/subject/update) command. \n\n```\n gcloud alpha managed-kafka schema-registries subject update SUBJECT_ID \n\n --schema-registry=SCHEMA_REGISTRY_ID \n\n --location=LOCATION \n\n --compatibility=COMPATIBILITY_TYPE\n \n```\n\n- \u003cvar translate=\"no\"\u003eSUBJECT_ID\u003c/var\u003e: the ID of the subject to update.\n- \u003cvar translate=\"no\"\u003eSCHEMA_REGISTRY_ID\u003c/var\u003e: the ID of the schema registry that contains the subject.\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: the region of the schema registry.\n- \u003cvar translate=\"no\"\u003eCOMPATIBILITY_TYPE\u003c/var\u003e: the new compatibility type. Valid values include `BACKWARD`, `BACKWARD_TRANSITIVE`, `FORWARD`, `FORWARD_TRANSITIVE`, `FULL`, `FULL_TRANSITIVE`, or `NONE`.\n\n**Example** : Update the compatibility type of the `test-subject` subject in the `test-registry` schema registry in the `us-central1` region to `FORWARD_TRANSITIVE`. \n\n```\n gcloud alpha managed-kafka schema-registries subject update test-subject \n\n --schema-registry=test-registry \n\n --location=us-central1 \n\n --compatibility=FORWARD_TRANSITIVE\n \n```\n\n### REST\n\nTo update the compatibility type for a subject, make a `PUT` request to the REST API.\n\nFirst, get an access token: \n\n```\ngcloud auth application-default print-access-token\n```\n\nUpdate compatibility for a subject in the default context: \n\n```\nPUT https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/SCHEMA_REGISTRY_ID/config/SUBJECT_ID\n```\n\nUpdate compatibility for a subject in a specific context: \n\n```\nPUT https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/SCHEMA_REGISTRY_ID/contexts/CONTEXT_ID/config/SUBJECT_ID\n```\n\nReplace the following path parameters:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: your Google Cloud project ID.\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: the region where the schema registry exists.\n- \u003cvar translate=\"no\"\u003eSCHEMA_REGISTRY_ID\u003c/var\u003e: the ID of the schema registry.\n- \u003cvar translate=\"no\"\u003eSUBJECT_ID\u003c/var\u003e: the ID of the subject.\n- \u003cvar translate=\"no\"\u003eCONTEXT_ID\u003c/var\u003e: the ID of the context (if applicable).\n\nInclude the following JSON object in the request body: \n\n```json\n{\n \"compatibility\": \"\u003cvar translate=\"no\"\u003eCOMPATIBILITY_TYPE\u003c/var\u003e\"\n}\n```\n\nReplace \u003cvar translate=\"no\"\u003eCOMPATIBILITY_TYPE\u003c/var\u003e with a valid value, such as `FORWARD_TRANSITIVE`.\n\n**Example:** Set subject `user_events` compatibility to `FORWARD_TRANSITIVE`.\n\nRequest to `PUT https://managedkafka.googleapis.com/v1main/projects/test-project/locations/us-central1/schemaRegistries/test_registry/config/user_events`\n\nWith body: \n\n```json\n{\n \"compatibility\": \"FORWARD_TRANSITIVE\"\n}\n```\n\nIf successful, the API returns a `200 OK` status code.\n\n\u003cbr /\u003e\n\nWhat's next\n-----------\n\n- [Update schema mode](/managed-service-for-apache-kafka/docs/schema-registry/update-schema-mode)\n- [Create a subject and register schemas](/managed-service-for-apache-kafka/docs/schema-registry/create-subject-version-one)\n- [View details of a schema registry](/managed-service-for-apache-kafka/docs/schema-registry/view-schema-registry)\n\n*Apache Kafka® is a registered\ntrademark of The Apache Software Foundation or its affiliates in the United\nStates and/or other countries.*"]]