Delete a schema subject version

This page describes how to delete a specific version of a schema subject in a schema registry. You can delete a schema subject version using one of the following methods:

  • Soft-delete marks a subject version as deleted, but its information is retained and can be recovered. You can find soft-deleted subject versions when listing subjects by using the deleted=true query parameter in the projects.locations.schemaRegistries.schemas.versions.list API call.

  • Hard-delete permanently removes a subject version and its associated data.

Required roles and permissions

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

This predefined role contains the permissions required to delete a schema subject version. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to delete a schema subject version:

  • Grant the following permission on the parent subject: managedkafka.googleapis.com/subjectVersions.delete

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

For more information about predefined roles, see the Managed Service for Apache Kafka predefined roles.

Soft delete a schema subject version

Here are some best practices for soft-deleting a schema subject version:

  • Verify that no active producers or consumers are using the schema subject version that you intend to delete.

  • After deleting a schema subject version, monitor your applications to ensure they continue to function as expected.

  • Soft-delete allows recovery of deleted schema subject versions, which is useful if you're unsure about deleting a schema subject version.

To soft-delete a schema subject version, follow these steps.

Console

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

    Go to schema registry

    A list of schema registries in your project is displayed.

  2. Click the name of the schema registry where you want to delete the subject version.

    The Schema registry details page opens. The information displayed on this page is explained in the Schema registry page details section.

  3. From the list of schema subjects in Subjects in this schema registry, click the subject for which you want to delete a schema version.

    The Subject details page opens.

  4. In the Subject details page, for All versions, unselect the schema version in use and select the schema version that you want to delete.
  5. Click the More action vertical menu and then click Delete version.
  6. In the Delete schema version window, click Soft delete.
  7. Confirm the deletion by typing delete and then click Delete.

    You get a successful deletion message.

REST

To soft-delete a schema subject version, make a DELETE request to the projects.locations.schemaRegistries.subjects.versions.delete method.

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials, run the following command: gcloud auth application-default print-access-token.

To soft-delete the schema subject version:

  • Use the following command for the default context: 

    DELETE https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions/VERSION_ID
Authorization: Bearer $(gcloud auth application-default print-access-token)

  • Use the following command for a specific context: 

    DELETE https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions/VERSION_ID
Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT)

Replace the following:

  • PROJECT_ID: your Google Cloud project ID, for example, test-project.
  • LOCATION: the Google Cloud region where the schema registry is located, for example, us-central1.
  • REGISTRY_ID: the ID of your schema registry, for example, test_registry.
  • CONTEXT_ID: the ID of your context, for example, test_context.
  • SUBJECT_ID: the ID of the subject, for example, test_subject.
  • VERSION_ID: the version of the subject to delete, for example, 2 or latest.
  • SERVICE_ACCOUNT: the service account, for example, test-service-account@test-project.iam.gserviceaccount.com.

If the request is successful, the API returns a 200 OK status code and an empty response body.

For more information, see the projects.locations.schemaRegistries.subjects.versions.delete method documentation.

Hard delete a schema subject version

Here are some best practices for hard-deleting a schema subject version:

  • Ensure you have a backup or a way to recreate the schema subject version if needed.

  • Verify that no active producers or consumers are using the schema subject version you intend to delete.

  • Always test schema subject version deletions in a development or staging environment before applying changes to production.

  • After deleting a schema subject version, monitor your applications to ensure they continue to function as expected.

  • Use hard-delete when you need to permanently remove a schema subject version.

To hard-delete a schema subject version, follow these steps.

Console

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

    Go to schema registry

    A list of schema registries in your project is displayed.

  2. Click the name of the schema registry where you want to delete the subject version.

    The Schema registry details page opens. The information displayed on this page is explained in the Schema registry page details section.

  3. From the list of schema subjects in Subjects in this schema registry, click the subject for which you want to delete a schema version.

    The Subject details page opens.

  4. In the Subject details page, for All versions, unselect the schema version in use and select the schema version that you want to delete.
  5. Click the More action vertical menu and then click Delete version.
  6. In the Delete schema version window, click Hard delete. This action soft-deletes the subject version before permanently deleting it.
  7. Confirm the deletion by typing delete and then click Delete.

    You get a successful deletion message.

REST

To hard-delete a schema subject version using the REST API, you must first soft-delete it. Once soft-deleted, you can proceed with the hard-deletion.

To hard-delete a schema subject version, make a DELETE request to the projects.locations.schemaRegistries.subjects.versions.delete method. To hard-delete the schema subject version, include the hardDelete=true query parameter:

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials, run the following command: gcloud auth application-default print-access-token.

To hard-delete the schema subject version:

  • Use the following command for the default context: 

    DELETE https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions/VERSION_ID?hardDelete=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

  • Use the following command for a specific context: 

    DELETE https://managedkafka.googleapis.com/v1main/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions/VERSION_ID?hardDelete=true
Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT)

Replace the following:

  • PROJECT_ID: your Google Cloud project ID, for example, test-project.
  • LOCATION: the Google Cloud region where the schema registry is located, for example, us-central1.
  • REGISTRY_ID: the ID of your schema registry, for example, test_registry.
  • CONTEXT_ID: the ID of your context, for example, test_context.
  • SUBJECT_ID: the ID of the subject, for example, test_subject.
  • VERSION_ID: the version of the subject to delete, for example, 2 or latest.
  • SERVICE_ACCOUNT: the service account, for example, test-service-account@test-project.iam.gserviceaccount.com.

If the request is successful, the API returns a 200 OK status code and an empty response body.

For more information, see the projects.locations.schemaRegistries.subjects.versions.delete method 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.