Manage Schemas for Topics

Use the Schema Registry feature in Control Center to manage Confluent Platform topic schemas.

You can:

  • create, edit, and view schemas
  • compare schema versions
  • download schemas

The Schema Registry performs validations and compatibility checks on schemas.


The Schema Registry feature in Control Center is enabled by default. Disabling the feature disables both viewing and editing of schemas.


As of Confluent Platform version 5.2, schemas can be created and edited. Versions prior to 5.2 only have view access to schema information in Control Center, including comparing version history and downloading schemas.

Creating a topic schema in Control Center

Create key and value schemas. Value schemas are typically created more frequently than a key schema.

Best practices:

  • Provide default values for fields to facilitate backward-compatibility if pertinent to your schema.
  • Document at least the more obscure fields for human-readability of a schema.

To create a topic value schema:

  1. Select a cluster from the navigation bar.

  2. Click the Topics menu. The All Topics page appears.

  3. Select a topic.

    Topics list

    The topic overview page appears.

    Topics list
  4. Click the Schema tab.

    You are prompted to set a message value schema.

  5. Click Set a schema. The Schema editor appears.

  6. The basic structure of a schema appears prepopulated in the editor as a starting point. Enter the schema in the editor:

    • name: Enter a name for the schema if you do not want to accept the default, which is determined by the subject name strategy. The default is schema_type_topic_name. Required.

    • type: Either record, enum, union, array, map, or fixed. Required.

    • namespace: Fully-qualified name to prevent schema naming conflicts. String that qualifies the schema name. Optional but recommended.

    • fields: JSON array listing one or more fields for a record. Required.

      Each field can have the following attributes:

      • name: Name of the field. Required.
      • doc: Field metadata. Optional but recommended.
      • default: Default value for a field. Optional but recommended.
      • order: Sorting order for a field. Valid values are ascending, descending, or ignore. Default: Ascending. Optional.
      • aliases: Alternative names for a field. Optional.

    Copy and paste the following example schema:

     "namespace": "io.confluent.examples.clients.basicavro",
     "type": "record",
     "name": "Payment",
     "fields": [
        "name": "id",
        "type": "string"
        "name": "amount",
        "type": "double"
    Schema for a topic entered into Control Center editor
  7. Click Save.

    • If the entered schema is valid, the Schema updated message is briefly displayed in the banner area.
    • If the entered schema is not valid, an Input schema is an invalid Avro schema error is displayed in the banner area.

    If applicable, repeat the procedure as appropriate for the topic key schema.

To create a topic key schema:

  1. Click the Key option. You are prompted to set a message key schema.

  2. Click Set a schema.

  3. Enter the schema into the editor and click Save.


Kafka messages are key/value pairs. Message keys and message values can be serialized independently. For example, the value may be using an Avro record, while the key may be a primitive (string, integer, and so forth). Typically message keys, if used, are primitives, but they can be complex data types as well (for example, record or array). How you set the key is up to you and the requirements of your implementation. For detailed examples of key and value schemas, see the discussion under Serializer in the Schema Registry documentation.

Viewing a schema in Control Center

View the schema details for a specific topic.

  1. Select a cluster from the navigation bar.

  2. Click the Topics menu. The All Topics page appears.

  3. Select a topic.

    Topics list

    The topic overview page appears.

  4. Click the Schema tab.

    The Value schema is displayed by default.

  5. Click the Key tab to view the key schema if present.

Editing a schema in Control Center

Edit an existing schema for a topic.

  1. Select a cluster from the navigation bar.

  2. Click the Topics menu. The All Topics page appears.

  3. Select a topic.

  4. Click the Schema tab.

  5. Select the Key or Value tab for the schema.

  6. Make the changes in the schema editor.

  7. Click Save.

    • If the schema update is valid and compatible with its prior versions (assuming a backward-compatible mode), the schema is updated and the version count is incremented. You can compare the different versions of a schema.

    • If the schema update is invalid or incompatible with an earlier schema version, an error is displayed.


Comparing schema versions in Control Center

Compare versions of a schema to view its evolutionary differences.

  1. Select a cluster from the navigation bar.

  2. Click the Topics menu. The All Topics page appears.

  3. Select a topic.

  4. Click the Schema tab.

  5. Select the Key or Value tab for the schema.

  6. Click Version history.


    The current version number of a schema displays in the upper-right corner of the Schema pane, and is also indicated in the version menus.

  7. Select the Turn on version diff check box.

  8. Select the versions to compare from each version menu. The differences are highlighted for comparison.


Changing the compatibility mode of a schema in Control Center

The default compatibility mode is Backward. The mode can be changed for the schema of any topic if necessary.


If you change the compatibility mode of an existing schema already in production use, be aware of any possible breaking changes to your applications.

  1. Select a cluster from the navigation bar.

  2. Click the Topics menu. The All Topics page appears.

  3. Select a topic.

  4. Click the Schema tab.

  5. Select the Key or Value tab for the schema.

  6. Click Edit Schema -> Compatibility Mode tab.

  7. Select a mode option:

    Descriptions indicate the compatibility behavior for each option. For more information, including the changes allowed for each option, see Schema Evolution and Compatibility.

  8. Click Save.

Downloading a schema from Control Center

  1. Select a cluster from the navigation bar.

  2. Click the Topics menu. The All Topics page appears.

  3. Select a topic.

  4. Click the Schema tab.

  5. Select the Key or Value tab for the schema.

  6. Click Download. A schema JSON file for the topic is downloaded into your Downloads directory.

    Example filename: schema-transactions-v1-Ry_XaOGvTxiZVZ5hbBhWRA.json

    Example contents:


    This is the first version of the schema, and it has an id of 2. The schema is escaped JSON. A backslash precedes double-quotes.

Troubleshoot Schema Registry is not set up message

If the Schema Registry is not set up page appears when you try to access the Topic Schema feature in Control Center, verify that the Schema Registry listeners configuration matches the Control Center confluent.controlcenter.schema.registry.url configuration. Also check the HTTPS configuration parameters.


For more information, see A schema for message values has not been set for this topic.

Enabling and disabling Schema Registry in Control Center

The feature that allows working with schemas in Control Center is enabled by default. The feature can be disabled if an organization does not want any users to access the feature. After disabling the feature, the Topics Schema menu and the Schema tab are no longer visible in the Control Center UI. The ability to view and edit schemas is disabled.

To disable the edit schema feature in Control Center:

  1. Set the confluent.controlcenter.schema.registry.enable option in your file to false.



    Make the change in the appropriate Control Center properties file or files configured for your environments, including or The properties files are located in /path-to-confluent/etc/confluent-control-center/.

  2. Restart Control Center and pass in the properties file for the configuration to take effect:

    ./bin/control-center-start ../etc/confluent-control-center/


    If you are using a Confluent Platform development environment with a confluent local, stop and start as follows:

    ./confluent local stop control-center
    ./confluent local start control-center ../etc/confluent-control-center/

To enable the feature again, set the option back to true and restart Control Center with the updated properties file.

Enabling Multi-Cluster Schema Registry

Starting with version 5.4.1, Confluent Platform supports the ability to run multiple schema registries and associate a unique Schema Registry to each Kafka cluster in multi- cluster environments.

The ability to scale up schema registries in conjunction with Kafka clusters is useful for evolving businesses; and particularly supports data governance, organization, and management across departments in large enterprises.

When multi-cluster Schema Registry is configured and running, you can create and manage schemas per topics in Control Center as usual.

Topic on multi-cluster schema registry

Configuration Properties and Files

A new endpoint /v1/metadata/schemaRegistryUrls has been exposed by Kafka to return the confluent.schema.registry.url field from the Kafka broker configurations. Control Center uses this field to look up the registries from Kafka broker configurations. To use this, you must configure unique listener endpoints for each cluster:

  • In the broker files (unique for each Kafka cluster), specify the REST endpoint with the confuent.http.server.listeners field, which defaults to
  • In the appropriate Control Center properties file, use confluent.controlcenter.streams.cprest.url to define the REST endpoint for controlcenter.cluster.
  • For additional clusters, define REST endpoints using confluent.controlcenter.kafka.{name}.cprest.url. This should be consistent with the Kafka cluster name used for other Kafka Control Center configurations; for example, confluent.controlcenter.kafka.{name}.bootstrap.servers.

A minimal viable configuration touches the following files, and includes settings for these properties (example names and ports are given):

Control Center properties file

The Control Center properties files file includes:

  • confluent.controlcenter.schema.registry.url=http://localhost:8081
  • confluent.controlcenter.streams.cprest.url=http://localhost:8090
  • confluent.controlcenter.kafka.AK1.cprest.url=http://localhost:8091

See Control Center configuration reference for a full description of confluent.controlcenter.schema.registry.url.

Broker configuration file for the Control Center cluster

The Kafka broker configuration file for controlcenter.cluster, such as, includes:

  • confluent.http.server.listeners=http://localhost:8090
  • confluent.schema.registry.url=http://localhost:8081

Broker configuration file for the Kafka cluster

The Kafka broker configuration file for AK1, includes:

  • confluent.http.server.listeners=http://localhost:8091
  • confluent.schema.registry.url=http://localhost:8082

With these configurations, editing the schema through the Control Center UI will connect to http://localhost:8081 for controlcenter.cluster and http://localhost:8082 for AK1.

Defaults and Fallback

If confluent.schema.registry.url fields are not specified for any brokers, the confluent.controlcenter.schema.registry.url Schema Registry URL is applied. For example, if the Schema Registry URL was not provided for AK1, AK1’s associated Schema Registry cluster would also be specified at http://localhost:8081. If confluent.controlcenter.schema.registry.url is not explicitly specified in the Control Center properties file, it defaults to http://localhost:8081.


Following is a detailed example of a functional multi-cluster Schema Registry setup with two Kafka clusters connected to Control Center, one the controlcenter.cluster, and the other named AK1, each with one broker.

The table below shows files and configurations in each for the two cluster example. These are not complete properties files, but rather excerpts from each file that define multi-cluster Schema Registry specifics, port numbers, and configurations that are important to the example setup or generally not found in default properties files.

To run the example, copy default Apache ZooKeeper™, Kafka (, Schema Registry, and Control Center properties files to new files per the example filenames below, add/modify properties as shown, and run the components as described in Run the Example.

Key Configurations

File Properties
  • dataDir=/tmp/zookeeper/zk-0 (fresh logging directory)
  • clientPort=2181 (same as
  • dataDir=/tmp/zookeeper/zk-1(fresh logging directory)
  • clientPort=2182 (since zookeeper0 is already using 2181)
  • listeners=PLAINTEXT://:9092
  • log.dirs=/tmp/kafka-logs-bk-0 (fresh logging directory)
  • zookeeper.connect=localhost:2181
  • confluent.metrics.reporter.bootstrap.servers=localhost:9092
The following configurations are specific to multi-cluster |sr| setup for this broker:
  • confluent.http.server.listeners=
  • confluent.schema.registry.url=http://localhost:8081
  • listeners=PLAINTEXT://:9093
  • log.dirs=/tmp/kafka-logs-bk-1(fresh logging directory)
  • zookeeper.connect=localhost:2182
  • confluent.metrics.reporter.bootstrap.servers=localhost:9093
The following configurations are specific to multi-cluster Schema Registry setup for this broker:
  • confluent.http.server.listeners=
  • confluent.schema.registry.url=http://localhost:8082
  • listeners=
  • kafkastore.connection.url=localhost:2181
  • listeners=
  • kafkastore.connection.url=localhost:2182
  • bootstrap.servers=localhost:9092
  • zookeeper.connect=localhost:2181
  • confluent.controlcenter.kafka.AK1.bootstrap.servers=localhost:9093
  • confluent.controlcenter.kafka.AK1.zookeeper.connect=localhost:2182
  • confluent.controlcenter.streams.cprest.url=
  • confluent.controlcenter.schema.registry.url=http://localhost:8081
  • confluent.controlcenter.kafka.AK1.cprest.url=
  • confluent.controlcenter.schema.registry.SR-AK1.url=http://localhost:8082
The configurations for cpcrest.url, confluent.controlcenter.kafka.AK1.cprest.url, and confluent.controlcenter.schema.registry.SR-AK1.url are new properties, specific to multi-cluster Schema Registry.

Run the Example

To run the example:

  1. Start the ZooKeepers.
  2. Start the Kafka brokers
  3. Start the Schema Registry clusters.
  4. Start Confluent Control Center.

The following example start commands assume the properties files are in the <path-to-confluent>/etc/ directories shown below, and that you are running the commands from <path-to-confluent>.

Start ZooKeepers

./bin/zookeeper-server-start etc/kafka/
./bin/zookeeper-server-start etc/kafka/

Start the Kafka brokers

./bin/kafka-server-start etc/kafka/
./bin/kafka-server-start etc/kafka/

Start Schema Registry clusters

./bin/schema-registry-start etc/schema-registry/
./bin/schema-registry-start etc/schema-registry/

Start Control Center

./bin/control-center-start etc/confluent-control-center/

Manage Schemas for Both Clusters on Control Center

  1. When the example clusters are running and Control Center finishes initialization, open Control Center in your web browser. (Control Center runs at http://localhost:9021/ by default, as described in Control Center User Guide.)
  2. Select a cluster from the navigation bar, click the Topics menu, and explore the schema management options for one or both clusters, starting with Creating a topic schema in Control Center.


Any other configurations used to set up a Schema Registry client with Control Center can be configured for an additional Schema Registry cluster by simply appending the Schema Registry cluster’s name to the confluent.controlcenter.schema.registry prefix. For example, for basic authentication with multi-cluster Schema Registry:

  • Use confluent.controlcenter.schema.registry.basic.auth.credentials.source and to define authentication for the confluent.controlcenter.schema.registry.url cluster.
  • Use confluent.controlcenter.schema.registry.{name}.basic.auth.credentials.source and confluent.controlcenter.schema.registry.{name} for additional Schema Registry clusters (associated with the URL fields by {name}).

To learn more, see Schema Registry authentication properties in the Control Center Configuration Reference under Kafka Encryption, Authentication, Authorization Settings and the section on Schema Registry in HTTP Basic Auth.

Errors and Troubleshooting

If the brokers for the cluster have matching Schema Registry URLs, but these URLs were not defined in the Control Center properties file, an error message is displayed on the cluster overview page.

Multi-cluster schema registry error message on Control Center

Version Compatibility

The deprecated confluent.controlcenter.schema.registry.url configuration in the Control Center properties file is still supported, and acts as a default if a cluster’s broker configurations do not contain confluent.schema.registry.url fields. Multiple Schema Registry clusters may be specified with confluent.controlcenter.schema.registry.{name}.url fields.

Multi-cluster Schema Registry cannot be used with Kafka versions prior to Kafka 2.4.x, the version current with Confluent Platform 5.4.0. However, using a single cluster Schema Registry setup will work with earlier Kafka versions. To learn more, see Confluent Platform and Apache Kafka Compatibility.

Suggested Reading