Kafka Schema Registry FAQ - StreamNative Documentation

General

Is it compatible with Confluent Schema Registry?

For the supported operations, yes—standard Confluent serializers, deserializers, and REST clients work unchanged. Several Confluent features aren’t implemented, and a few endpoints behave differently. Read Confluent API compatibility before migrating.

Which schema formats are supported?

Avro, JSON Schema, and Protobuf. GET /schemas/types returns exactly ["AVRO","JSON","PROTOBUF"].

What’s the minimum permission a client needs?

A producer that registers schemas needs schema-writer. A consumer that only resolves them needs schema-reader. Both are scoped per subject.

How do I find my Schema Registry endpoint?

On a Kafka cluster it’s the cluster’s HTTP service URL. On a Pulsar cluster it’s that URL with /kafka appended. See Get the Schema Registry URL.

Can I use OAuth instead of an API key?

Yes, with the Kafka Java client and the oauth-client dependency. See OAuth2.

Schemas and subjects

What’s the difference between a schema ID and a version?

A schema ID identifies a schema globally—register the same definition under two subjects and you get one ID. A version is the position of a schema within a subject. The same schema ID can be version 1 of one subject and version 3 of another. See Key concepts.

How many schemas can I store?

There’s no maximum number of subjects, no maximum number of versions per subject, and no storage quota. The one hard limit is a 5 MB request body, which caps the size of a single schema.

How do I find which subjects use a schema ID?

curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1/subjects"

Can I recover a deleted schema?

No. A soft delete keeps the schema readable through ?deleted=true, but nothing restores it, and re-registering the same schema creates a new version. Hard-deleted data is gone. See Delete schemas.

Why can’t I delete this schema?

Another schema references it—error code 42206. Find them with GET /subjects/{subject}/versions/{version}/referencedby and delete those first.

Can I change a subject’s format from Avro to JSON?

No. That’s rejected with HTTP 409 in every compatibility mode, including NONE. Use a new subject.

Compatibility

What’s the default compatibility mode?

BACKWARD, for every format.

Why does `GET /config` say NONE?

The global GET /config returns a fixed {"compatibilityLevel":"NONE"} regardless of what’s in force. It’s not reporting a real value. Read GET /config/{subject} instead. See Behavior differences.

How do I change the global default compatibility mode?

You can’t—there’s no PUT /config. Set the mode on each subject with PUT /config/{subject}.

Should I upgrade producers or consumers first?

It depends on the mode. Under BACKWARD (the default), consumers first. Under FORWARD, producers first. Under FULL, either. See Order of upgrading clients.

Can I test a schema change without registering it?

Yes, and you should—put it in CI:

curl -u "any-user:$API_KEY" -X POST \
  -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema":"..."}' \
  "$SR_URL/compatibility/subjects/orders-value/versions/latest?verbose=true"

Note this is a POST, not a GET.

What is ALWAYS_INCOMPATIBLE?

A StreamNative extension with no Confluent equivalent. It rejects every schema change once a subject has at least one version—useful for freezing a subject. Confluent client libraries may not accept the value, in which case set it through the REST API.

Migrating from Confluent

Do Data Contracts work?

No, and the failure is silent. A registration carrying metadata or ruleSet succeeds—the fields are discarded and the schema is stored without them, with no error. If you rely on schema rules, CEL validation, or migration rules, they stop being enforced the moment you switch.

Is Schema Linking supported?

No. /exporters/* returns 404. Use Universal Linking to replicate schemas between clusters instead.

Are schema contexts supported?

No. GET /contexts returns 404, and qualified subject names aren’t recognized.

Is client-side field level encryption supported?

No. There’s no DEK/KEK registry and no encrypt rule executor.

Why did my RecordNameStrategy subjects change meaning?

Subject names are parsed into Pulsar tenant, namespace, and topic components. A RecordNameStrategy subject like com.acme.MyRecord becomes tenant com, namespace acme, topic MyRecord. Confirm those exist and that your credentials cover them. See Subject names and Pulsar coordinates.

Does `?normalize=true` work?

For Avro and Protobuf, yes. For JSON Schema it’s a no-op, so schemas differing only in property ordering register as separate versions. On the /compatibility/* endpoints it’s ignored for every format.

Does the Confluent Maven plugin work?

It talks to the registry over the standard REST API, so the goals that use supported endpoints should work. It isn’t tested against StreamNative Cloud, so verify against a non-production cluster before relying on it in a pipeline.

Operations

Is the Schema Registry a separate service I connect to?

No. It’s served at your cluster’s own endpoint on port 443 over HTTPS, so it inherits the cluster’s network configuration—including private networking.

Why is my subject list empty?

GET /subjects filters to subjects your credentials can read rather than returning a permission error. An empty array means either the registry is empty or your role covers none of the existing subjects.

How do I replicate schemas to another region?

Universal Linking replicates from an active cluster to one or more standby clusters. Standbys run in import mode: they accept replicated schemas and reject new registrations from producers. Replication is one-directional, and deletions aren’t replicated.

Can I make the broker reject records without a schema?

Yes—enable schema ID validation per topic. Note it uses kop.kafka.* properties rather than Confluent’s confluent.* ones, and tombstones always pass.

​General

​Is it compatible with Confluent Schema Registry?

​Which schema formats are supported?

​What’s the minimum permission a client needs?

​How do I find my Schema Registry endpoint?

​Can I use OAuth instead of an API key?

​Schemas and subjects

​What’s the difference between a schema ID and a version?

​How many schemas can I store?

​How do I find which subjects use a schema ID?

​Can I recover a deleted schema?

​Why can’t I delete this schema?

​Can I change a subject’s format from Avro to JSON?

​Compatibility

​What’s the default compatibility mode?

​Why does GET /config say NONE?

​How do I change the global default compatibility mode?

​Should I upgrade producers or consumers first?

​Can I test a schema change without registering it?

​What is ALWAYS_INCOMPATIBLE?

​Migrating from Confluent

​Do Data Contracts work?

​Is Schema Linking supported?

​Are schema contexts supported?

​Is client-side field level encryption supported?

​Why did my RecordNameStrategy subjects change meaning?

​Does ?normalize=true work?

​Does the Confluent Maven plugin work?

​Operations

​Is the Schema Registry a separate service I connect to?

​Why is my subject list empty?

​How do I replicate schemas to another region?

​Can I make the broker reject records without a schema?

​Next steps

Confluent compatibility

Troubleshooting