Confluent Schema Registry compatibility API

Apicurio Registry provides a compatibility API layer so that applications with Confluent Schema Registry clients can work with Apicurio Registry. Review the supported and unsupported features, behavioral differences, and migration considerations, and migrate schemas with the export utility.

Overview of the compatibility API

Apicurio Registry implements the Confluent Schema Registry REST API to provide drop-in compatibility for applications and tools designed for Confluent Schema Registry.

Table 1. Supported API versions
Version	Endpoint	Status
v7	`/apis/ccompat/v7`	Fully supported
v8	`/apis/ccompat/v8`	Fully supported

Applications that use Confluent Schema Registry client libraries can use Apicurio Registry as a replacement by changing the schema registry URL to point to the appropriate Apicurio Registry ccompat endpoint.

Example configuration

# Confluent client configuration pointing to Apicurio Registry
schema.registry.url=http://my-registry:8080/apis/ccompat/v7

Supported features

Apicurio Registry fully supports the following Confluent Schema Registry features:

Table 2. Fully supported API endpoints
Feature	Description
Schemas API	Full support for schema management including `GET /schemas`, `GET /schemas/ids/{id}`, `GET /schemas/types`, `GET /schemas/ids/{id}/subjects`, `GET /schemas/ids/{id}/versions`, and `GET /schemas/ids/{id}/schema`. Includes pagination with `offset` and `limit` parameters.
Subjects API	Complete create, retrieve, update, and delete operations for subjects including listing, registration, lookup by content (`POST /subjects/{subject}`), lookup by version (`POST /subjects/{subject}/versions/{version}`), and deletion. Supports pagination with `offset`, `limit`, `deleted`, and `deletedOnly` parameters.
Compatibility API	Schema compatibility checking against specific versions or all versions. Supports `verbose` and `normalize` parameters. Defaults to `BACKWARD` compatibility when you do not configure an explicit rule, matching the Confluent behavior.
Config API	Global and subject-level compatibility configuration. Supports `GET`, `PUT`, and `DELETE` operations, including `defaultToGlobal` parameter for subject config. The `PUT` response includes `compatibility` and `normalize` fields.
Mode API	Global and subject-level mode management (`READWRITE`, `READONLY`, `READONLY_OVERRIDE`, `IMPORT`). Supports `force` parameter for mode changes.
Contexts API	Returns the default context for Confluent client compatibility.

Table 3. Supported schema types
Schema type	Support status
Apache Avro	Fully supported
JSON Schema	Fully supported
Google Protobuf	Fully supported

Table 4. v8-specific features
Feature	Description
X-Confluent-Accept-Unknown-Properties header	When set to `true`, the API ignores unknown JSON properties in request bodies. This provides forward compatibility for clients that send newer API requests.
Enhanced pagination	Full pagination support on schemas and subjects endpoints.

Schema ID mapping

Apicurio Registry uses two internal ID types: globalId (unique per artifact version) and contentId (unique per content hash). Confluent Schema Registry uses a single incrementing schema ID.

The apicurio.ccompat.legacy-id-mode.enabled configuration property controls the mapping between Confluent schema IDs and Apicurio Registry internal IDs:

Table 5. Schema ID mode
Mode	Config value	Behavior
Content ID mode (default)	`false`	Confluent `id` maps to Apicurio Registry `contentId`. Registering the same schema content under different subjects returns the same ID, matching the Confluent behavior.
Legacy ID mode	`true`	Confluent `id` maps to Apicurio Registry `globalId`. Each version registration gets a unique ID regardless of content.

For most use cases, use the default content ID mode, because it matches the Confluent behavior where identical schemas share the same ID across subjects.

Configuration properties

Table 6. Confluent compatibility API configuration
Property	Default	Description
`apicurio.ccompat.legacy-id-mode.enabled`	`false`	Use `globalId` instead of `contentId` for Confluent schema IDs.
`apicurio.ccompat.use-canonical-hash`	`false`	Always use canonical hash for schema content comparison.
`apicurio.ccompat.max-subjects`	`1000`	Maximum number of subjects returned by the `/subjects` endpoint.
`apicurio.ccompat.group-concat.enabled`	`false`	Enable Apicurio Registry group support by concatenating group ID and artifact ID into the subject name.
`apicurio.ccompat.group-concat.separator`	`:`	Separator character used when you enable group concatenation.

Behavioral differences from Confluent

Although the ccompat API provides broad compatibility, some behavioral differences exist when you migrate from Confluent Schema Registry.

Avro schema formatting

The ccompat API normalizes returned Avro schemas to compact single-line JSON, matching the Confluent behavior. This normalization has the following effects:

The API returns pretty-printed Avro schemas submitted during registration in compact form.
The API simplifies Avro primitive type wrappers (for example, {"type": "string"} becomes "string").
Field ordering follows the Avro canonical form.

This normalization applies only to ccompat API responses (/apis/ccompat/*). The native Apicurio Registry v3 API returns schemas in their original submitted format.

Default compatibility level

When you do not configure an explicit compatibility rule at the artifact, group, or global level, the ccompat compatibility check endpoint (POST /compatibility/subjects/{subject}/versions/{version}) defaults to BACKWARD compatibility. This matches the default behavior of Confluent Schema Registry.

This default only applies to the compatibility check endpoint. Schema registration does not enforce this default unless you explicitly configure a compatibility rule by using PUT /config or PUT /config/{subject}.

Config response format

The PUT /config and PUT /config/{subject} endpoints return a response with the following fields:

{
  "compatibility": "BACKWARD",
  "normalize": false
}

The GET /config endpoint returns the following response:

{
  "compatibilityLevel": "BACKWARD"
}

The field name differs between the update response (compatibility) and the get response (compatibilityLevel). This matches the Confluent API behavior.

Error responses

Error responses use Confluent-compatible error codes and message formats:

Table 7. Error codes
Error code	Meaning	HTTP status
40401	Subject not found	404
40402	Version not found	404
40403	Schema not found	404
40408	Subject-level compatibility not configured	404
42201	Invalid schema	422
42203	Invalid compatibility level	422
42206	Schema has existing references	422

Sorted results

List endpoints (GET /subjects, GET /schemas/ids/{id}/subjects, GET /schemas/ids/{id}/versions) return results in sorted order (alphabetical for subjects, numerical for versions).

Unsupported features

Apicurio Registry does not support the following Confluent Schema Registry features. Applications that rely on these features must use alternative approaches.

Table 8. Unsupported features
Feature	Behavior	Alternative
Schema Linking / Exporters	`GET /exporters` returns an empty list. All other exporter operations return an error.	Use Apicurio Registry native import/export functions or external replication tools.
KEKs (Key Encryption Keys)	Endpoints not present (404 error).	Implement encryption at the application layer or use external key management.
DEKs (Data Encryption Keys)	Endpoints not present (404 error).	Implement encryption at the application layer or use external key management.
Cluster Metadata API	Endpoints `/v1/metadata/id` and `/v1/metadata/config` not present.	Use Apicurio Registry system API for registry information.
Data Contracts - Rules Enforcement	The ccompat API accepts `metadata` and `ruleSet` fields in requests but does not enforce or store them. The API does not execute schema rules.	Use Apicurio Registry native Data Contracts feature (`apicurio.contracts.enabled=true`) for contract metadata and rulesets.

Schema Linking / Exporters

Confluent Schema Linking uses schema exporters to replicate schemas between Schema Registry clusters. This is an enterprise feature that requires cluster-to-cluster replication infrastructure.

Apicurio Registry provides alternative approaches for schema replication:

Import/Export API: Use the Apicurio Registry admin API to export all registry content to a ZIP file and import it into another instance.
Kafka-based storage: Use Kafka storage to store schemas in a Kafka topic that you can replicate by using the native replication features of Kafka.
GitOps workflows: Store schemas in Git and use CI/CD pipelines to synchronize across environments.

Data Contracts

Confluent Data Contracts provide the following governance features:

Metadata: Key-value pairs attached to schemas (owner, email, tags)
RuleSets: Validation and transformation rules that use Common Expression Language (CEL) or JSONata

Apicurio Registry accepts these fields in ccompat API requests for client compatibility but does not process or store them through the ccompat layer. Instead, Apicurio Registry provides its own native Data Contracts feature with more capabilities:

Contract Metadata: Standardized metadata (status, owner, domain, classification, stage) managed through the contract/metadata REST API
Contract Rulesets: Domain and migration rules at both artifact and version level, managed through the contract/ruleset REST API
Content Rules: Validity, compatibility, and integrity rule configuration
Groups: Artifact organization by group for governance

Additional resources

Data Contracts

Migration considerations

When you migrate from Confluent Schema Registry to Apicurio Registry, consider the following areas:

Table 9. Migration checklist
Area	Consideration
Basic operations	Schema registration, retrieval, and compatibility checks work identically. No changes required.
Existing schemas	Export subjects, schema versions, references, and compatibility levels from Confluent Schema Registry with the export utility, and then import the ZIP file into Apicurio Registry.
Client configuration	Update `schema.registry.url` to point to the Apicurio Registry ccompat endpoint.
Schema types	Apicurio Registry fully supports Avro, JSON Schema, and Protobuf.
Schema IDs	Apicurio Registry uses `contentId` by default (the same schema content produces the same ID across subjects). Set `apicurio.ccompat.legacy-id-mode.enabled=true` if your application depends on unique IDs per registration.
Avro schema formatting	Avro schemas are returned in compact JSON through ccompat endpoints. If your application compares schema strings directly, be aware of formatting differences.
Default compatibility	The compatibility check endpoint defaults to `BACKWARD` when you do not configure a rule, matching Confluent. Set an explicit global compatibility level by using `PUT /config` if you need a different default.
Config response parsing	The `PUT /config` response uses the field name `compatibility` (not `compatibilityLevel`). Update client code that parses this response.
Authentication	Apicurio Registry supports OpenID Connect (OIDC) authentication. Update client security configuration as needed.
Exporters / Schema Linking	Not supported. Use Apicurio Registry import/export API or Kafka topic replication.
Data Contracts	Metadata and rules from the ccompat API are not enforced. Use Apicurio Registry native Data Contracts feature for contract metadata and rulesets.
Encryption (KEK/DEK)	Not supported. Implement encryption at the application layer.

Example: Migrating a Kafka producer

// Before: Confluent Schema Registry
Properties props = new Properties();
props.put("schema.registry.url", "http://confluent-registry:8081");

// After: Apicurio Registry (using ccompat API)
Properties props = new Properties();
props.put("schema.registry.url", "http://apicurio-registry:8080/apis/ccompat/v7");

Additional resources

Confluent Schema Registry export utility data mapping

The Confluent Schema Registry export utility reads a Confluent Schema Registry through its REST API and writes the data as a ZIP file in the Apicurio Registry import format. Review how the utility maps Confluent Schema Registry data to Apicurio Registry before you migrate.

Table 10. Confluent Schema Registry data in the export file
Confluent Schema Registry data	Apicurio Registry equivalent
Subject	Artifact in the default group, with the subject name as the artifact ID. The artifact type is `AVRO`, `JSON`, or `PROTOBUF`, matching the Confluent schema type.
Schema version	Artifact version that keeps the Confluent version number, so clients can continue to request the same version numbers through the ccompat API.
Schema ID	Content ID. By default, the ccompat API returns content IDs as schema IDs, so existing clients can continue to resolve the schema IDs that are embedded in serialized messages.
Schema reference	Artifact reference to the referenced subject and version.
Subject compatibility level	`COMPATIBILITY` rule on the artifact, written only for subjects that set their own level.
Global compatibility level	Global `COMPATIBILITY` rule.

The export file also contains a global VALIDITY rule set to SYNTAX_ONLY. After the import, Apicurio Registry applies this rule to every artifact in the target instance that does not define its own validity rule.

The utility exports only active subjects and versions. It does not export soft-deleted subjects or versions, subject modes, registration timestamps, or the metadata, tags, and rulesets of Confluent Data Contracts.

Migrating schemas from Confluent Schema Registry by using the export utility

You can copy subjects, schema versions, references, and compatibility levels from Confluent Schema Registry into Apicurio Registry by using the Confluent Schema Registry export utility. The utility writes a ZIP file that you import through the Apicurio Registry admin API.

The export utility is a command-line tool from the Apicurio Registry project. Each Apicurio Registry release publishes it to Maven Central.

Prerequisites

You have Java 17 or later on a machine that can reach the Confluent Schema Registry REST API and the Apicurio Registry API.
If the Confluent Schema Registry requires authentication, you have credentials for it.
You have administrator access to the target Apicurio Registry instance.
You have an empty target Apicurio Registry instance, or you plan to import with new identifiers.

Procedure

Download the apicurio-registry-utils-exportConfluent archive from Maven Central:

$ curl -LO https://repo1.maven.org/maven2/io/apicurio/apicurio-registry-utils-exportConfluent/VERSION/apicurio-registry-utils-exportConfluent-VERSION.tar.gz

Replace VERSION with the version of your Apicurio Registry instance, for example 3.3.3. Use version 3.3.0 or later. Archives for earlier versions extract into a quarkus-app directory, so run the launcher from that directory instead.

To build the utility from source instead, run ./mvnw -Dfull -pl utils/exportConfluent -am -DskipTests package in the Apicurio Registry source repository with JDK 21 or later. The build creates the launcher at utils/exportConfluent/target/quarkus-app/quarkus-run.jar.

Extract the archive into an empty directory:
```
$ mkdir confluent-export
$ tar -xzf apicurio-registry-utils-exportConfluent-VERSION.tar.gz -C confluent-export
$ cd confluent-export
```
The directory contains the quarkus-run.jar launcher with its lib, app, and quarkus directories.
Export the Confluent Schema Registry data:
```
$ java -jar quarkus-run.jar MY-CONFLUENT-URL --output confluent-schema-registry-export.zip
```
MY-CONFLUENT-URL is the URL of the Confluent Schema Registry REST API. For example: http://my-confluent:8081. The URL must be the first argument. The utility prints Export successfully done. when it finishes. If the export fails, the utility exits with status 1 and leaves an incomplete ZIP file that you must not import.

The following options are available:
--output or -o

The name of the ZIP file. The default is confluent-schema-registry-export.zip in the current directory.

--insecure

Accepts any TLS certificate and host name when the URL uses HTTPS. Use this option only for testing, and do not combine it with --client-props, because the client properties restore the default Java trust store. For a certificate from a private certificate authority, pass a trust store as client properties instead: schema.registry.ssl.truststore.location and schema.registry.ssl.truststore.password.

--client-props
Passes Confluent client properties as key=value pairs, for example, to authenticate. Place this option last, because the utility reads every remaining argument as a property. The utility splits each argument at the first = and silently truncates a value that contains another =.

The utility prints the parsed client properties, including any credentials, to the console.

For example, to export from a Confluent Schema Registry that requires basic authentication:
$ java -jar quarkus-run.jar MY-CONFLUENT-URL --output confluent-schema-registry-export.zip \ --client-props basic.auth.credentials.source=USER_INFO basic.auth.user.info=MY-USER:MY-PASSWORD
For Confluent Cloud, use the Schema Registry API key as MY-USER and the API secret as MY-PASSWORD.
Import the ZIP file into the target Apicurio Registry instance:
```
$ curl -X POST "MY-REGISTRY-URL/apis/registry/v3/admin/import" \
  -H "Content-Type: application/zip" -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-binary @confluent-schema-registry-export.zip
```
MY-REGISTRY-URL is the URL of the target Apicurio Registry instance. For example: http://my-registry:8080. Omit the Authorization header if authentication is disabled. You can also import the file by using the web console or the CLI. If the import fails with HTTP 400 because the file exceeds the ZIP import limits, raise apicurio.import.zip.max-entry-count on the target instance and retry. The default is 10000 entries.

By default, the import requires an empty registry and keeps the content IDs and global IDs from the file, so the schema IDs that are embedded in existing Kafka messages stay valid. The file numbers global IDs from 1, so they collide with data that the target registry already holds. To import into a registry that already contains data, add the requireEmptyRegistry=false query parameter and set the X-Registry-Preserve-GlobalId and X-Registry-Preserve-ContentId headers to false, so that Apicurio Registry assigns new identifiers:
```
$ curl -X POST "MY-REGISTRY-URL/apis/registry/v3/admin/import?requireEmptyRegistry=false" \
  -H "Content-Type: application/zip" -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Registry-Preserve-GlobalId: false" -H "X-Registry-Preserve-ContentId: false" \
  --data-binary @confluent-schema-registry-export.zip
```
New content IDs change the schema IDs that the ccompat API returns. Consumers of messages that were produced before the migration can then no longer resolve the embedded Confluent schema IDs through Apicurio Registry. Import into an empty registry whenever those messages must remain readable.

Verification

List the migrated subjects through the ccompat API and compare the list with the output of GET /subjects on the Confluent Schema Registry. The endpoint returns at most apicurio.ccompat.max-subjects subjects, 1000 by default:
```
$ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/ccompat/v7/subjects
```

Retrieve a schema by its original Confluent schema ID:

$ curl -H "Authorization: Bearer $ACCESS_TOKEN" MY-REGISTRY-URL/apis/ccompat/v7/schemas/ids/1

Check the Apicurio Registry server log for import warnings. The import skips an entity that it cannot store, such as a version with a duplicate global ID, and still returns HTTP 204.

Next steps

Update the schema.registry.url property of your Kafka clients to the ccompat API endpoint. See Migration considerations.

Additional resources