Important

You are viewing documentation for an older version of Confluent Platform. For the latest, click here.

Schema Deletion Guidelines

The Schema Registry API supports deleting a specific schema version or all versions of a subject. On a soft delete, the API only deletes the version and the underlying schema ID would still be available for any lookup.

Soft delete a schema

# Deletes all schema versions registered under the subject "Kafka-value"
  curl -X DELETE http://localhost:8081/subjects/Kafka-value
  [1]

# Deletes version 1 of the schema registered under subject "Kafka-value"
  curl -X DELETE http://localhost:8081/subjects/Kafka-value/versions/1
  1

# Deletes the most recently registered schema under subject "Kafka-value"
  curl -X DELETE http://localhost:8081/subjects/Kafka-value/versions/latest
  1

Hard delete a schema

Both Confluent Platform and Confluent Cloud now support hard delete of a schema with the use of the query string, ?permanent=true. A hard delete removes all metadata, including schema IDs. This can be useful for freeing up space for new schemas on Confluent Cloud, which sets limits on the number of schema versions supported in the registry.

You can perform a hard delete on all schema versions registered under a subject or on a specific version of a subject.

To accomplish a hard delete of a schema (all versions or a specific version), use this two-step process. You must first soft delete the schema, then hard-delete it.

  1. Perform a soft delete of all versions of the schema.

    curl -X DELETE -u <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/my-existing-subject

  2. Perform a hard delete of all versions of the schema by appending ?permanent=true to the command.

    curl -X DELETE -u <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/<my-existing-subject>/versions/<version-id>?permanent=true

The following commands hard-delete all versions of the schema registered under the subject “Kafka-value”:

curl -X DELETE <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/Kafka-value
curl -X DELETE <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/Kafka-value?permanent=true

To hard-delete version 1 of the schema registered under the subject Kafka-value:

curl -X DELETE <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/Kafka-value/versions/1
curl -X DELETE <schema-registry-api-key>:<schema-registry-api-secret> <schema-registry-url>/subjects/Kafka-value/versions/1?permanent=true

Tip

For the version-specific delete, a hard delete requires a version number as input; not just version:latest, which results in a soft delete only.

Guidelines for using these APIs

The above APIs are primarily intended to be used be in a development environment where it’s common to go through iterations before finalizing a schema. While it’s not recommended to be used in a production environment, there are few scenarios where these APIs can be used in production, but with utmost care.

  • A new schema to be registered has compatibility issues with one of the existing schema versions
  • An old version of the schema needs to be registered again for the same subject
  • The schema’s are used only in real-time streaming systems and the older version(s) are absolutely no longer required
  • A topic needs to be recycled
  • You want to free up space for new schemas on Confluent Cloud (with a hard delete of schemas).

It is also important to note that any registered compatibility settings for the subject would also be deleted while using Delete Subject or when you delete the only available schema version.