Confluent Schema Registry compatibility API

Apicurio Registry provides a compatibility API layer that enables applications using Confluent Schema Registry clients to work seamlessly with Apicurio Registry. This chapter describes the supported features, limitations, and migration considerations.

Overview of the compatibility API
Supported features
Behavioral differences from Confluent
Unsupported features
Migration considerations

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 using Confluent Schema Registry client libraries can use Apicurio Registry as a replacement by simply 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

The following Confluent Schema Registry features are fully supported in Apicurio Registry:

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 CRUD operations for subjects including listing, registration, lookup by content (`POST /subjects/{subject}`), lookup by version (`POST /subjects/{subject}/versions/2024.Q2`), 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 no explicit rule is configured, matching 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`, unknown JSON properties in request bodies are ignored. This provides forward compatibility for clients sending 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 mapping between Confluent schema IDs and Apicurio Registry internal IDs is controlled by the apicurio.ccompat.legacy-id-mode.enabled configuration property:

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 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, the default content ID mode is recommended because it matches Confluent’s 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 group concatenation is enabled.

Behavioral differences from Confluent

While the ccompat API aims for full compatibility, there are some behavioral differences to be aware of when migrating from Confluent Schema Registry.

Avro schema formatting

Avro schemas returned through the ccompat API are normalized to compact single-line JSON, matching Confluent’s behavior. This means:

Pretty-printed Avro schemas submitted during registration are returned in compact form.
Avro primitive type wrappers are simplified (for example, {"type": "string"} becomes "string").
Field ordering follows Avro’s 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 no explicit compatibility rule is configured at the artifact, group, or global level, the ccompat compatibility check endpoint (POST /compatibility/subjects/{subject}/versions/2024.Q2) defaults to BACKWARD compatibility. This matches Confluent Schema Registry’s default behavior.

This default only applies to the compatibility check endpoint. Schema registration does not enforce this default unless a compatibility rule is explicitly configured via 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:

{
  "compatibilityLevel": "BACKWARD"
}

Note the different field name (compatibility vs compatibilityLevel) between the update and get responses. This matches Confluent’s 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

The following Confluent Schema Registry features are not supported in Apicurio Registry. Applications relying on these features will need to 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 functionality 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	`metadata` and `ruleSet` fields are accepted in requests but NOT enforced or stored via the ccompat API. Schema rules are not executed.	Use Apicurio Registry native Data Contracts feature (`apicurio.contracts.enabled=true`) for contract metadata and rulesets. See Data Contracts.

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: When using Kafka storage, schemas are stored in a Kafka topic that can be replicated using Kafka’s native replication features.
GitOps workflows: Store schemas in Git and use CI/CD pipelines to sync across environments.

Data Contracts

Confluent Data Contracts provide governance features including:

Metadata: Key-value pairs attached to schemas (owner, email, tags)
RuleSets: Validation and transformation rules using CEL or JSONata

In Apicurio Registry, these fields are accepted in ccompat API requests for client compatibility but are not processed or stored through the ccompat layer. Instead, Apicurio Registry provides its own native Data Contracts feature with richer functionality:

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: Configure validity, compatibility, and integrity rules
Groups: Organize artifacts by group for governance

See Data Contracts for full documentation on the native data contracts feature.

Migration considerations

When migrating from Confluent Schema Registry to Apicurio Registry, consider the following:

Table 9. Migration checklist
Area	Consideration
Basic Operations	Schema registration, retrieval, and compatibility checks work identically. No changes required.
Client Configuration	Update `schema.registry.url` to point to Apicurio Registry ccompat endpoint.
Schema Types	Avro, JSON Schema, and Protobuf are fully supported.
Schema IDs	Apicurio Registry uses `contentId` by default (same schema content = 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 no rule is configured, matching Confluent. Set an explicit global compatibility level via `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 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