> ## 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.

# Kafka Schema Registry Key Concepts

> Subjects, versions, schema IDs, and the record wire format—the vocabulary you need before working with the Kafka Schema Registry.

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](/kafka/governance/sr/manage/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](/kafka/governance/sr/fundamentals/serdes#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:

```
[ 1 byte magic ][ 4 bytes schema ID, big-endian ][ serialized payload ]
```

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.

<Note title="Note">
  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.
</Note>

## Subject names and Pulsar coordinates

StreamNative Cloud parses subject names into Pulsar 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`               |

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.

<Warning title="RecordNameStrategy subjects contain dots">
  `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`.
</Warning>

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](/cookbook/kafka-schema-registry-geo-replication).

## Next steps

<CardGroup cols={2}>
  <Card title="Evolution and compatibility" icon="code-compare" href="/kafka/governance/sr/fundamentals/schema-evolution">
    What each compatibility mode permits, and which side to upgrade first.
  </Card>

  <Card title="Serializers and deserializers" icon="code" href="/kafka/governance/sr/fundamentals/serdes">
    Subject name strategies, auto-registration, and normalization.
  </Card>
</CardGroup>