Streaming

Use Schema Registry in Redpanda Console

In Redpanda Console, the Schema Registry menu lists registered and verified schemas, including their serialization format and versions. Select an individual schema to see which topics it applies to.

The Schema Registry is built into Redpanda, and you can use it with the Schema Registry API or with the UI. This section describes Schema Registry operations available in the UI.

Prerequisites

You must add a valid schemaRegistry configuration in Redpanda Console. For help configuring Redpanda Console to connect to Schema Registry, see Configure Message Deserialization in Redpanda Console.

Create or edit a schema

A schema is registered in the registry with a subject, which is a name that is associated with the schema as it evolves. To register a schema, click Create new schema.

  1. On the Create schema page, select the strategy type for how to derive the subject name.

    • Topic (default): The subject name is derived from the Redpanda topic name. See Topic strategy use case.

    • Record: The subject name is derived from the Kafka record name. See Record strategy use case.

    • TopicRecord: The subject name is derived from both topic name and record name, allowing for finer-grained schema organization. See TopicRecord strategy use case.

    • Custom: The subject name is user-defined.

  2. Depending on the strategy, select the Topic name (Topic and TopicRecord strategies) or enter the Subject name (Custom strategy). For the Record strategy, Console derives the subject name from the schema definition.

  3. Select whether the schema applies to the message Key or Value. Console appends -key or -value to the subject name. This selection is required for the Topic strategy, and it is not available for the Custom strategy.

  4. Select the serialization format with the schema definition.

  5. (Optional) Enable Normalize to convert the schema to a canonical form before registering it. Normalization prevents duplicate schema versions caused by formatting differences, such as whitespace or field ordering. Normalization is supported for Avro, JSON, and Protobuf formats.

  6. To build more complex schema definitions, add a reference to other schemas. For example, the two import statements are references to the PhoneNumber and Address schemas:

    {
  syntax = "proto3";
  import "PhoneNumber.proto";
  import "Address.proto";
  message Person {
    string name = 1;
    string email = 2;
    PhoneNumber phone  = 3;
    repeated Address address  = 4;
  }
}

  7. After registering a schema, you can add a new version to it, change its compatibility, or delete it.

Topic strategy use case

The Topic strategy is suitable when all messages in a topic follow the same schema. Suppose you’re tracking product order information in a topic named Transactions. When you create a schema with the Topic strategy, you select the topic and whether the schema applies to the message key or value. The subject name is the topic name plus a -key or -value suffix:

  • Transactions-key

  • Transactions-value

All producers writing to the Transactions topic use the same schemas, and the key and value schemas can evolve independently under their own subjects.

Record strategy use case

The Record strategy is most useful when you have multiple types of records in a single topic and need more granular categorization influenced by the record name. Suppose there’s an Events topic with event types A and B. With the Record strategy, each event type gets its own subject and schema, named after the record rather than the topic. Console derives the record name from the schema definition: the top-level name field for Avro and JSON schemas, or the first message name for Protobuf schemas. For example, for Avro schemas named EventTypeA and EventTypeB, the subjects are:

  • EventTypeA

  • EventTypeB

Console does not include the Avro namespace or Protobuf package in the subject name. To register a fully qualified subject name such as com.example.EventTypeA, either use the full dotted name in the Avro name field or use the Custom strategy.

Most JSON Schema documents have no top-level name field. For JSON schemas, either add a top-level name to the schema definition or use the Custom strategy.

If you select Key or Value when creating the schema, Console appends -key or -value to the subject name (for example, EventTypeA-value).

Because the subjects aren’t tied to a topic, producers can write these record types to any topic, and multiple topics can share the same schemas.

This naming differs from the RecordNameStrategy that server-side schema ID validation enforces, which expects the subject to be the fully qualified record name with no -key or -value suffix. If a topic has schema ID validation enabled with RecordNameStrategy, use the Custom strategy so that the subject name matches exactly.

TopicRecord strategy use case

The TopicRecord strategy is suitable when you want to organize schemas by both topic and record type. Suppose there’s a microservices architecture where different services produce their own event types to a shared topic named SharedEvents. With the TopicRecord strategy, each schema’s subject combines the topic name and the record name:

  • SharedEvents-MicroserviceAEvent

  • SharedEvents-MicroserviceBEvent

If you select Key or Value when creating the schema, Console appends -key or -value to the subject name (for example, SharedEvents-MicroserviceAEvent-value).

This lets multiple record types govern the same topic, with each record type’s schema evolving under its own subject.

This naming differs from the TopicRecordNameStrategy that server-side schema ID validation enforces, which expects <topic-name>-<fully-qualified-record-name> with no -key or -value suffix. If a topic has schema ID validation enabled with TopicRecordNameStrategy, use the Custom strategy so that the subject name matches exactly.

Manage schema metadata

Schema Registry can store arbitrary key-value metadata properties, such as owner or team, alongside each schema version. In Redpanda Console, you can view the metadata on a schema version and set metadata when you register a schema or a new schema version.

Schema metadata requires Redpanda version 26.1 or later and Redpanda Console v3.5.1 or later. If the cluster does not support metadata, the schema is registered without it.

View metadata

To view the metadata on a schema version, select the subject from the Schema Registry menu. On the Definition tab, the Metadata section below the schema definition lists the properties of the selected version. If the version has no metadata, the section shows No properties.

Set metadata when creating a schema

When you register a schema on the Create schema page, use the Schema metadata section to attach optional key-value properties:

  1. Click Add property.

  2. Enter a key (for example, owner) and a value (for example, team-platform). Keys must be unique within a schema version. Rows with an empty key or value are ignored.

  3. Click Save.

Edit or remove metadata

Metadata is stored per schema version, so you cannot change the metadata on an existing version. To change metadata, register a new version:

  1. Select the subject and click Add new version.

  2. In the Schema metadata section, the form is pre-filled with the properties of the latest active version. Edit values, remove properties, or add new ones.

  3. Click Save.

Registering the same schema definition with different metadata properties creates a new schema version with a new ID. The previous version and its metadata remain unchanged.

Configure schema compatibility

Applications are often modeled around a specific business object structure. As applications change and the shape of their data changes, producer schemas and consumer schemas may no longer be compatible. You can decide how a consumer handles data from a producer that uses an older or newer schema, and reduce the chance of consumers hitting deserialization errors.

You can configure different types of schema compatibility, which are applied to a subject when a new schema is registered. The Schema Registry supports the following compatibility types:

  • BACKWARD (default) - Consumers using the new schema (for example, version 10) can read data from producers using the previous schema (for example, version 9).

  • BACKWARD_TRANSITIVE - Consumers using the new schema (for example, version 10) can read data from producers using all previous schemas (for example, versions 1-9).

  • FORWARD - Consumers using the previous schema (for example, version 9) can read data from producers using the new schema (for example, version 10).

  • FORWARD_TRANSITIVE - Consumers using any previous schema (for example, versions 1-9) can read data from producers using the new schema (for example, version 10).

  • FULL - A new schema and the previous schema (for example, versions 10 and 9) are both backward and forward compatible with each other.

  • FULL_TRANSITIVE - Each schema is both backward and forward compatible with all registered schemas.

  • NONE - No schema compatibility checks are done.

Compatibility uses and constraints

  • A consumer that wants to read a topic from the beginning (for example, an AI learning process) benefits from backward compatibility. It can process the whole topic using the latest schema. This allows producers to remove fields and add attributes.

  • A real-time consumer that doesn’t care about historical events but wants to keep up with the latest data (for example, a typical streaming application) benefits from forward compatibility. Even if producers change the schema, the consumer can carry on.

  • Full compatibility can process historical data and future data. This is the safest option, but it limits the changes that can be done. This only allows for the addition and removal of optional fields.

If you make changes that are not inherently backward-compatible, you may need to change compatibility settings or plan a transitional period, updating producers and consumers to use the new schema while the old one is still accepted.

Schema format Backward-compatible tasks Not backward-compatible tasks

Avro

Add fields with default values

Make fields nullable

Remove fields

Change data types of fields

Change enum values

Change field constraints

Change record of field names

Protobuf

Add fields

Remove fields

Remove required fields

Change data types of fields

JSON

Add optional properties

Relax constraints, for example:

  • Decrease a minimum value or increase a maximum value

  • Decrease minItems, minLength, or minProperties; increase maxItems, maxLength, maxProperties

  • Add more property types (for example, "type": "integer" to "type": ["integer", "string"])

  • Add more enum values

  • Reduce multipleOf by an integral factor

  • Relaxing additional properties if additionalProperties was not previously specified as false

  • Removing a uniqueItems property that was false

Remove properties

Add required properties

Change property names and types

Tighten or add constraints

Delete a schema

Select a schema to soft-delete a version of it or all schemas of its subject. Schemas cannot be deleted if any other schemas reference it. A soft-deleted schema can be recovered, but a permanently-deleted schema cannot be recovered. Redpanda does not recommend permanently deleting schemas in a production environment.

Schema Registry contexts

Schema Registry contexts are namespaces that group subjects and schemas within a single Schema Registry instance. For context configuration details and prerequisites, see Schema Registry Contexts.

How Console uses contexts

When Schema Registry contexts are enabled in your cluster, Console provides context-aware subject browsing and management.

Console lists subjects according to their context, using context-capable APIs to ensure subjects and their versions come from the correct namespace.

When you open a subject, Console fetches its schema versions using both the subject name and its context. This avoids ambiguity when the same subject name exists in multiple contexts.

Console surfaces Schema Registry mode and compatibility settings and, where supported, lets you adjust them at:

  • Global level (entire registry)

  • Subject level (within a specific context)

This lets you apply safe defaults globally while fine-tuning behavior for individual subjects in specific contexts.

Automatic feature detection

Console automatically detects whether Schema Registry contexts are available:

  • If contexts are supported, Console shows context-aware UI and uses context-specific APIs.

  • If contexts are not supported, Console falls back to a standard non-context view, so you can continue working with schemas without errors.

Suggested reading