Managing Schemas for Topics in Confluent Cloud

You can manage schemas for topics in Confluent Cloud.

You can:

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

The Schema Registry performs validations and compatibility checks on schemas.

Tip

Viewing a schema in Confluent Cloud

View the schema details for a specific topic.

  1. From the Clusters page, click the cluster you want to work with.

    ../../../_images/cloud-0a-cluster-select.png
  2. From the navigation menu, click Topics.

  3. Click the ellipsis (...) by the topic name and click Schema.

    ../../../_images/cloud-01-topic-schema-menu.png

    The Value schema is displayed by default.

    ../../../_images/cloud-02-view-value-schema.png
  4. Click Key to view the key schema if present.

Creating a topic schema in Confluent Cloud

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. From the navigation menu, click Topics.

  2. Click the ellipsis (...) by the topic name and click Schema. You are prompted to set a message value schema.

    ../../../_images/cloud-03-set-msg-value-schema.png
  3. Click Set a schema. The Schema editor appears.

    ../../../_images/cloud-04-schema-value-editor.png
  4. 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.
    ../../../_images/cloud-05-entered-schema.png
  5. Click Save.

    • If the entered schema is valid, the Schema updated message is briefly displayed in the banner area.

      ../../../_images/cloud-06-schema-updated.png
    • If the entered schema is not valid, an Input schema is an invalid Avro schema error is displayed in the banner area.

      ../../../_images/cloud-07-schema-invalid-avro.png

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.

    ../../../_images/cloud-08-set-msg-key-schema.png
  2. Click Set a schema.

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

Tip

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.

Editing a schema in Confluent Cloud

Edit an existing schema for a topic.

  1. From the navigation menu, click Topics.

  2. Click the ellipsis (...) by the topic name and click Schema.

  3. Select the Key or Value option for the schema.

  4. Make the changes in the schema editor.

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

      ../../../_images/cloud-09-schema-version-updated.png
    • If the schema update is invalid or incompatible with an earlier schema version, an error is displayed.

      ../../../_images/cloud-10-schema-incompatible.png

Comparing schema versions in Confluent Cloud

Compare versions of a schema to view its evolutionary differences.

  1. From the navigation menu, click Topics.

  2. Click the ellipsis (...) by the topic name and click Schema.

  3. Select the Key or Value option for the schema.

  4. Click Version history.

    ../../../_images/cloud-11-schema-version-history.png

    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.

  5. Select the Turn on version diff check box.

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

    ../../../_images/cloud-12-schema-compare.png

Changing the compatibility mode of a schema in Confluent Cloud

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

Caution

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. From the navigation menu, click Topics.

  2. Click the ellipsis (...) by the topic name and click Schema.

  3. Select the Key or Value option for the schema.

  4. Click Edit Schema -> Compatibility Mode tab.

    ../../../_images/cloud-13-schema-compat-mode.png
  5. 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.

  6. Click Save.

Downloading a schema from Confluent Cloud

  1. From the navigation menu in a cluster, click Topics.

  2. Click the ellipsis (...) by the topic name and click Schema.

  3. Select the Key or Value option for the schema.

  4. 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:

    {"subject":"transactions-value","version":1,"id":2,"schema":"{\"type\":\"record\",\"name\":\"Payment\",
    \"namespace\":\"io.confluent.examples.clients.basicavro\",
    \"fields\":[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"amount\",\"type\":\"double\"},
    {\"name\":\"region\",\"type\":\"string\"}]}"}
    

    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.