Skip to main content
The Schema Registry has a small vocabulary, and most confusion comes from conflating the four terms in it: topic, schema, subject, and version.

​
How it works

The registry runs alongside your cluster, not inside the broker path. Clients talk to both:
  1. A producer’s serializer takes your object and the schema that describes it.
  2. It registers that schema with the registry—or looks it up if it’s already there—and gets back a schema ID.
  3. It writes the ID into the record’s payload prefix, then appends the serialized data.
  4. A consumer’s deserializer reads the ID from the prefix, fetches the matching schema from the registry, caches it, and decodes the payload.
The broker stores and serves the bytes without interpreting them—unless you turn on schema ID validation, which makes the broker check the ID before accepting the record.

​
Topics, schemas, subjects, and versions

A schema is the definition of a record’s structure: an Avro record declaration, a JSON Schema document, or a Protobuf message. The registry stores each distinct schema once and assigns it a schema ID. A subject is a named scope for schema evolution. Compatibility rules apply per subject, and a subject holds an ordered list of versions. By default the subject name is derived from the topic name—topic orders gets subjects orders-value and orders-key—but that’s a client-side convention, not a rule the registry enforces. See Subject name strategies. Three consequences follow from this model, and each one surprises people:
  • Identical schemas share an ID. Register the same schema definition under two different subjects and you get one schema ID, not two.
  • A schema ID is not a version. The same schema ID can be version 1 of one subject and version 3 of another. IDs are global; versions are per subject.
  • Subjects, not topics, own compatibility. Two topics whose subjects hold the same schema still evolve independently.

​
Schema IDs

Schema IDs increase monotonically but not consecutively—don’t assume the next registration gets the next integer, and don’t parse meaning out of the number. Treat an ID as an opaque handle.

​
The wire format

A serialized record produced by a Confluent-compatible serializer has a fixed prefix:
The magic byte is 0x00. The schema ID is the value the registry returned at registration. This is why schematized data is compact: the record carries a 4-byte reference rather than the schema itself, and every consumer resolves the exact schema the producer used. It’s also why a consumer reading a topic without the right registry credentials fails to deserialize—the payload alone isn’t self-describing.
The prefix means a schematized record is not valid Avro, JSON, or Protobuf on its own. Tools that read the payload directly, such as kafka-console-consumer without a schema-aware formatter— show the leading bytes as garbage or fail outright.

​
Subject names and Pulsar coordinates

StreamNative Cloud parses subject names into Pulsar tenant, namespace, and topic components: Responses convert the internal form back to the dotted name you submitted, so a client using TopicNameStrategy never notices. It matters when a subject name contains dots for another reason.
RecordNameStrategy produces subjects like com.acme.MyRecord, which is parsed as tenant com, namespace acme, topic MyRecord—not as one opaque name. Verify that the resulting tenant and namespace exist and that your credentials cover them before adopting RecordNameStrategy or TopicRecordNameStrategy.
Subject names accept the characters [a-zA-Z0-9._-] up to 249 characters. Anything else returns error code 42208.

​
Storage

Schemas are stored durably by the cluster, outside your topics’ data path, and survive broker restarts. There is no maximum number of versions per subject, no maximum number of subjects, and no storage quota. The one hard limit is a 5 MB request body, which is the effective maximum size of a single schema. To replicate schemas to another cluster, see Schema Registry geo-replication.

​
Next steps

Evolution and compatibility

What each compatibility mode permits, and which side to upgrade first.

Serializers and deserializers

Subject name strategies, auto-registration, and normalization.