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

# Register and Manage Kafka Schemas

> Register schemas, inspect subjects and versions, set compatibility modes, and adopt a workflow that keeps schema changes deliberate.

Day-to-day work with the registry is four operations: register a schema, look at what's registered,
set the rules for how a subject may change, and check a candidate change before it ships.

All examples assume `SR_URL` and `API_KEY` are set—see
[Connect](/kafka/governance/sr/connect).

## Register a schema

```shell theme={null}
curl -u "any-user:$API_KEY" \
  -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schemaType":"AVRO","schema":"{\"type\":\"record\",\"name\":\"Order\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"}]}"}' \
  "$SR_URL/subjects/orders-value/versions"
```

```json theme={null}
{"id":1}
```

Registering the same schema again is idempotent: you get the same ID back and no new version.
Registering a *different* schema runs the subject's compatibility check first.

`schemaType` defaults to `AVRO`. Set it explicitly to `JSON` or `PROTOBUF` otherwise.

<Warning title="A subject cannot change format">
  Registering a JSON schema on a subject that holds Avro versions is rejected with HTTP 409, in every
  compatibility mode including `NONE`. To change format, use a new subject.
</Warning>

## Inspect what's registered

List subjects:

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/subjects"
```

List a subject's versions, then read one:

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions"
curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions/latest"
```

Find which subjects a schema ID belongs to—useful when a consumer reports an ID it can't resolve:

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1/subjects"
```

See [REST API examples](/kafka/governance/sr/reference/rest-api) for the full set.

## Set a compatibility mode

```shell theme={null}
curl -u "any-user:$API_KEY" \
  -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"compatibility":"BACKWARD_TRANSITIVE"}' \
  "$SR_URL/config/orders-value"
```

Read it back with `GET /config/orders-value`.

<Warning title="Read the per-subject config, not the global one">
  The global `GET /config` always returns `{"compatibilityLevel":"NONE"}` regardless of what's in
  force. The real default is `BACKWARD`. There's no `PUT /config`, so the global default can't be
  changed—set the mode on each subject you care about.
</Warning>

## Check a change before you ship it

Test a candidate schema without registering it. This belongs in CI, on every pull request that
touches a schema file:

```shell theme={null}
curl -u "any-user:$API_KEY" \
  -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data "{\"schema\": $(jq -Rs . < order.avsc)}" \
  "$SR_URL/compatibility/subjects/orders-value/versions/latest?verbose=true"
```

```json theme={null}
{"is_compatible":false,"messages":["READER_FIELD_MISSING_DEFAULT_VALUE: total"]}
```

Fail the build on `is_compatible: false` and the incompatible change never reaches a cluster.

## A workflow that holds up

Auto-registration means whichever producer connects first defines the subject. That's fine for
prototyping and poor for a shared platform.

For subjects that matter:

1. **Turn off auto-registration** in producers and set `use.latest.version`:

   ```java theme={null}
   props.put(AbstractKafkaSchemaSerDeConfig.AUTO_REGISTER_SCHEMAS, false);
   props.put(AbstractKafkaSchemaSerDeConfig.USE_LATEST_VERSION, true);
   ```

2. **Keep schema files in version control** next to the code that uses them.

3. **Run the compatibility check in CI** against the target subject.

4. **Register from the deploy pipeline**, using a service account with
   [`schema-writer`](/cloud/security/access/rbac/manage-rbac-roles#schema-writer). Give application
   service accounts `schema-reader` only.

5. **Set the compatibility mode when you create the subject**, rather than discovering the default
   later.

## Replicate schemas to another cluster

Use [Universal Linking](/cookbook/kafka-schema-registry-geo-replication) to replicate schemas from an
active cluster to one or more standby clusters. The standby registry runs in import mode: it accepts
replicated schemas and rejects new registrations from producers.

Schema Linking exporters aren't available—see
[Confluent API compatibility](/kafka/governance/sr/reference/confluent-compatibility#unsupported-features).

## Next steps

<CardGroup cols={2}>
  <Card title="Delete schemas" icon="trash" href="/kafka/governance/sr/manage/delete-schemas">
    Soft delete, hard delete, and what can't be undone.
  </Card>

  <Card title="Schema ID validation" icon="shield-check" href="/kafka/governance/sr/manage/schema-id-validation">
    Enforce registered schemas at the broker.
  </Card>
</CardGroup>