> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Confluent Schema Registry API Compatibility
> Which Confluent Schema Registry endpoints and features StreamNative Cloud implements, which it doesn't, and where behavior differs.
The StreamNative Kafka Schema Registry implements a subset of the
[Confluent Schema Registry API](https://docs.confluent.io/platform/current/schema-registry/develop/api.html).
Standard Confluent serializers, deserializers, and REST clients work against it unchanged for the
operations listed below.
This page is the reference for what's supported, what isn't, and—most importantly—the places
where an endpoint exists but behaves differently than you'd expect coming from Confluent.
## Supported endpoints
### Schemas
| Method | Path | Query parameters |
| ------ | ---------------------------- | ---------------- |
| GET | `/schemas/types` | |
| GET | `/schemas/ids/{id}` | `subject` |
| GET | `/schemas/ids/{id}/schema` | |
| GET | `/schemas/ids/{id}/versions` | `deleted` |
| GET | `/schemas/ids/{id}/subjects` | `deleted` |
### Subjects
| Method | Path | Query parameters |
| ------ | ----------------------------------------------------- | ------------------------ |
| GET | `/subjects` | `deleted`, `deletedOnly` |
| POST | `/subjects/{subject}` | `normalize`, `deleted` |
| DELETE | `/subjects/{subject}` | `permanent` |
| POST | `/subjects/{subject}/versions` | `normalize` |
| GET | `/subjects/{subject}/versions` | `deleted`, `deletedOnly` |
| GET | `/subjects/{subject}/versions/{version}` | `deleted` |
| DELETE | `/subjects/{subject}/versions/{version}` | `permanent` |
| GET | `/subjects/{subject}/versions/{version}/schema` | |
| GET | `/subjects/{subject}/versions/{version}/referencedby` | |
### Compatibility
| Method | Path | Query parameters |
| ------ | ------------------------------------------------------ | ---------------- |
| POST | `/compatibility/subjects/{subject}/versions/{version}` | `verbose` |
| POST | `/compatibility/subjects/{subject}/versions` | `verbose` |
These are **POST** endpoints, not GET. `POST /compatibility/subjects/{subject}/versions` checks the
candidate schema against every version, according to the subject's configured mode.
### Config and mode
| Method | Path | Notes |
| ------ | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| GET | `/config` | Returns a fixed value—see [Behavior differences](#behavior-differences). |
| GET | `/config/{subject}` | Compatibility level only. |
| PUT | `/config/{subject}` | Compatibility level only. |
| GET | `/mode` | Global mode. |
| PUT | `/mode` | Global mode. Accepts `force`. Availability depends on the cluster—see [Behavior differences](#behavior-differences). |
### Content types
The registry accepts `application/vnd.schemaregistry.v1+json`,
`application/vnd.schemaregistry+json`, `application/json`, `application/octet-stream`, `*/*`, or a
missing `Accept` header. Any other value returns **412 Precondition Failed**.
## Unsupported endpoints
These return **404 Not Found**:
| Endpoint | Confluent feature |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `PUT /config` | Setting the global default compatibility level. Set it per subject instead. |
| `DELETE /config/{subject}` | Resetting a subject to the global default. |
| `GET`, `PUT`, `DELETE /mode/{subject}` | Per-subject mode. Only the global `/mode` exists. |
| `GET /schemas` | Listing every schema in one call. |
| `GET /contexts` | Schema contexts. |
| `/exporters/*` | Schema Linking. |
| `/dek-registry/*` | Client-side field level encryption (CSFLE), and the registry of data and key encryption keys it depends on. |
| `/subjects/{subject}/versions/{version}/tags` | Stream Catalog tags. |
Unsupported query parameters—`format`, `fetchMaxId`, `latestOnly`, `subjectPrefix`,
`defaultToGlobal`—are ignored rather than rejected.
## Unsupported features
| Feature | Status | Use instead |
| ----------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------- |
| **Data Contracts** (`metadata`, `ruleSet`, Common Expression Language (CEL) rules, JSONata migration rules, field-level transforms) | Not supported | N/A |
| **Client-side field level encryption (CSFLE)** | Not supported | N/A |
| **Schema Linking** (exporters) | Not supported | [Universal Linking](/cookbook/kafka-schema-registry-geo-replication) replicates schemas between clusters. |
| **Schema Contexts** | Not supported | N/A |
| **Stream Catalog**, tags, business metadata | Not supported | N/A |
| **AsyncAPI export** | Not supported | N/A |
| **Private networking for the registry** | Not applicable | The registry shares the cluster's endpoint. See [Networking](/cloud/networking/networking). |
A schema registration that includes `metadata` or `ruleSet` **succeeds**. The request is accepted,
those fields are discarded, and the schema is stored without them. No error is returned. If you're
migrating from Confluent and rely on schema rules, they will stop being enforced without any signal
that anything changed.
## Behavior differences
Endpoints that exist but don't behave the way the Confluent documentation describes.
### `GET /config` always reports NONE
The global `GET /config` returns `{"compatibilityLevel":"NONE"}` regardless of the compatibility
level actually in force. The real default is **`BACKWARD`**.
Use `GET /config/{subject}` to read the level that applies to a subject.
### Subject names map to Pulsar coordinates
Subject names are parsed into tenant, namespace, and topic components:
| Subject | Interpreted as |
| ------------------------------ | ------------------------------- |
| `my-topic-value` | `public/default/my-topic-value` |
| `tenant.ns.topic-value` | `tenant/ns/topic-value` |
| `persistent://tenant/ns/topic` | `tenant/ns/topic` |
A `RecordNameStrategy` subject like `com.acme.MyRecord` is parsed as tenant `com`, namespace `acme`,
topic `MyRecord`—not as a single opaque name. If you use `RecordNameStrategy` or
`TopicRecordNameStrategy`, verify that the resulting tenant and namespace exist and that your
credentials cover them.
Subject names are limited to the characters `[a-zA-Z0-9._-]` and 249 characters. Anything else
returns error code **42208**.
### Normalization is partial
`?normalize=true` performs real normalization for **Avro** and **Protobuf** schemas. For **JSON
Schema** it's a no-op—the schema is stored as submitted.
On the `/compatibility/*` endpoints, `normalize` is parsed and then discarded for every format.
### There is no undelete
A soft-deleted schema stays readable through `?deleted=true` and `?deletedOnly=true`, but there is no
operation that restores it. Re-registering the same schema string after a soft delete creates a
**new version** rather than reviving the old one.
Hard delete (`?permanent=true`) requires a prior soft delete; calling it first returns **40405** for
a subject or **40407** for a version. Hard-deleted data is unrecoverable.
### Deletes are blocked by references
Deleting a schema that another schema references returns error code **42206**. Delete the referencing
schemas first, or use `GET /subjects/{subject}/versions/{version}/referencedby` to find them.
### `PUT /mode` availability varies
Mode changes—`READONLY`, `READONLY_OVERRIDE`, and `IMPORT`—depend on how the registry is deployed
for your cluster. On clusters that don't support it, `GET /mode` always returns `READWRITE` and
`PUT /mode` fails.
`IMPORT` mode is normally set by
[Universal Linking replication](/cookbook/kafka-schema-registry-geo-replication) on the standby
cluster, not by client applications.
### JSON `$ref` cannot reach external URLs
A JSON Schema `$ref` pointing at an external URL is rejected. Use
[schema references](/kafka/governance/sr/fundamentals/schema-references) to compose schemas within
the registry instead.
### Broker-side validation uses different property names
Schema ID validation is configured with `kop.kafka.*` topic properties, not Confluent's
`confluent.*` properties. See
[Schema ID validation](/kafka/governance/sr/manage/schema-id-validation).
## Extensions beyond Confluent
| Feature | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `ALWAYS_INCOMPATIBLE` compatibility mode | Rejects every new schema once a subject has at least one version. Useful for freezing a subject. |
## Limits
| Limit | Value |
| ---------------------------- | -------------------------------------- |
| Maximum request body | 5 MB—the effective maximum schema size |
| Maximum subject name length | 249 characters |
| Maximum versions per subject | No limit |
| Maximum subjects | No limit |
| Storage quota | No limit |
## Error codes
| Code | Meaning |
| ----- | ------------------------------------------------------------------------ |
| 40401 | Subject not found |
| 40402 | Version not found |
| 40403 | Schema not found |
| 40404 | Subject already soft-deleted |
| 40405 | Subject not soft-deleted—hard delete requires a soft delete first |
| 40406 | Version already soft-deleted |
| 40407 | Version not soft-deleted—hard delete requires a soft delete first |
| 409 | Incompatible schema, including a change of format on an existing subject |
| 42201 | Invalid schema |
| 42206 | Another schema references this one |
| 42208 | Invalid subject name |
| 412 | Unsupported `Accept` content type |