# Delete Schemas in Confluent Platform The [Schema Registry API](develop/api.md#schemaregistry-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 You can perform a soft delete on all schema versions registered under a subject or on a specific version of a subject. A soft delete removes the specified schema versions but does not free up space in the registry because the schema metadata, including schema IDs, is retained and schema IDs are not reusable. ```bash # 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 Schema Registry support hard delete of a schema with the use of the query string, `?permanent=true`. A hard delete removes all metadata, including schema IDs. 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. ```bash curl -X DELETE -u : /subjects/my-existing-subject ``` 2. Perform a hard delete of all versions of the schema by appending `?permanent=true` to the command. ```bash curl -X DELETE -u : /subjects/?permanent=true ``` The following commands hard-delete all versions of the schema registered under the subject “Kafka-value”: ```bash curl -X DELETE -u : /subjects/Kafka-value curl -X DELETE -u : /subjects/Kafka-value?permanent=true ``` To hard-delete version 1 of the schema registered under the subject Kafka-value: ```bash curl -X DELETE -u : /subjects/Kafka-value/versions/1 curl -X DELETE -u : /subjects/Kafka-value/versions/1?permanent=true ``` ## Recovering a soft-deleted schema You can recover a soft-deleted schema using the Schema Registry `GET /subjects` and `POST /subjects` APIs as follows: 1. Retrieve the schema with `GET /subjects?deleted=true`, as described in [GET /subjects API description](https://docs.confluent.io/platform/current/schema-registry/develop/api.html#get--subjects). (A usage example is shown in [List all subjects](develop/using.md#kafka-key-listing-all-subjects).) For example: ```bash curl -s -X GET -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -u : \ ":/subjects//versions/?deleted=true" ``` The output should resemble: ```bash {"subject":"deletion-test-value","version":1,"id":14,"schema":"{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"},{\"name\":\"field2\",\"type\":\"int\"}]}"} ``` 2. Use [POST/subjects/(string: subject)/versions](https://docs.confluent.io/platform/current/schema-registry/develop/api.html#post--subjects-(string-%20subject)-versions) to re-register the schema. - You can POST from a file using this syntax: ```bash curl -s -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -u : --data '@schema.json' ":/subjects//versions" ``` Example of `schema.json` referred to in the above command: ```bash { "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"},{\"name\":\"field2\",\"type\":\"int\"}]}" } ``` - Or you can input the schema directly: ```bash curl -s -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -u : --data '{"schema":"{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"},{\"name\":\"field2\",\"type\":\"int\"}]}"}' ":/subjects//versions" ``` To learn more, see the [Schema Registry API Reference for Confluent Platform](develop/api.md#schemaregistry-api) and [Schema Registry API Usage Examples for Confluent Platform](develop/using.md#schemaregistry-using). ## Workaround to virtually recover a hard-deleted schema In some cases, a schema is hard deleted but later found to still be required to read messages. If the you have the schema definition, you can re-register it at its previous offset to allow the consumers to keep functioning. If this is the case, you can essentially “restore” the schema by recreating it with the same definition, putting the schema into IMPORT mode, and manually registering it at a specified ID on a Schema Registry. This assumes that the schema ID is not already taken, and is useful in recovery operations when a schema was deleted but is backed up on another cluster. To learn how to “restore” a hard-deleted schema using this method, see [Migrate an Individual Schema to an Already Populated Schema Registry (subject-level migration)](installation/migrate.md#migrate-individual-schemas). ## 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 schemas are used only in real-time streaming systems and the older version(s) are absolutely no longer required. - A topic needs to be recycled. 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. ## Looking under the hood at schema deletion, versioning, and compatibility In reality, deleting a schema removes only the versioned instance(s) of the schema. The actual schema (with the hashed ID) does not go away. The canonical MD5 hash of the schema still exists in the system. This is why you can perform a lookup on a deleted schema in the rest API. If, on a subject that has three versions, you delete the third one but register again the same schema it will be registered under version 3 and the associated schema will have the same ID as before, because the hash matched the existing one. When the Avro serializer serializes Avro data, it stores the ID (not the version, which is specific to the subject). If the version (in a subject) is deleted, the schema and its ID remain in Schema Registry so that the data can still be deserialized using Schema Registry This has implications for versioning and compatibility. Suppose, for a given subject, you have two schemas: - Schema ID: 23, version 1 with fields (a,b) - Schema ID: 45, version 2 with fields (a,b,c) If you delete version 2, version 1 becomes the latest version. If the compatibility level is BACKWARD, the next schema that is registered to the subject need only be backward compatible with version 1, not version 2. ## Use the APIs to determine if a schema is deleted Several Schema Registry REST API endpoints return additional schema metadata, including a `deleted` field that indicates whether a schema has been soft-deleted. This allows you to identify deleted schemas in a single API call rather than making separate lookups for each schema’s deletion status. The following endpoints support these additional response properties: - [GET /schemas](develop/api.md#cp-sr-api-list-schemas) - [GET /schemas/ids/{id}](develop/api.md#cp-sr-api-get-schema-by-id) - [POST /subjects/{subject}/versions](develop/api.md#api-example-avro-schema-references) - [POST /subjects/{subject}](develop/api.md#cp-sr-api-subject-lookup) - [GET /subjects/{subject}/versions/{version}](develop/api.md#cp-sr-api-get-schema-by-version) - [GET /subjects/(string: subject)/metadata](develop/api.md#cp-sr-api-get-latest-version-of-subject-with-metadata) For Confluent Platform, these additional properties are always included in the response. ## Identify and delete unused schemas The [schema deletion tool](https://github.com/confluentinc/schema-deletion-tool) finds and deletes unused schemas in Confluent Platform Schema Registry. The [README](https://github.com/confluentinc/schema-deletion-tool#readme) provides full instructions for building and using the schema deletion tool independently, or as a Confluent CLI plugin. On Confluent Platform, run the tool with the `--platform cp` flag and a configuration file that specifies the Schema Registry connection details and the Kafka clusters to scan: ```bash ./schema-deletion-tool --platform cp --cp-config-file /path/to/cp-config.json --all ``` The tool follows this basic workflow: 1. The tool takes subject names, based on `TopicNameStrategy`, to analyze and detect unused schemas. 2. It identifies topics using the `TopicNameStrategy` and analyzes messages to identify unused schemas in those topics. Any schema IDs not present in the topic’s messages are identified as unused schemas and listed as candidates for deletion, with a confirmation prompt before deletion. ## Related Content - [Schema Registry API Reference for Confluent Platform](develop/api.md#schemaregistry-api) - [Schema Registry API Usage Examples for Confluent Platform](develop/using.md#schemaregistry-using)