Skip to content

Manage schemas

This feature is only available on the Enterprise plan.

In the Confluent ecosystem, schemas are associated with data via subjects, which are typically derived from a Kafka topic's name. For example, the default strategy, TopicNameStrategy, suffixes the topic name with -value.

Register schemas

You create subjects within the BSR's Confluent Schema Registry by annotating messages with a custom option that identifies the instance and subject name.

The subject is claimed by the module that contains the annotated message, preventing use of that subject by other modules. It's an error to annotate multiple messages in a module with the same instance and subject name.

Note

All references to buf.example.com below should be replaced with the hostname for your private BSR instance.

  1. Add a dependency on the bufbuild/confluent managed module to your Buf workspace's buf.yaml file.

    version: v2
modules:
  path: /path/to/local/directory
  name: buf.example.com/demo/analytics
deps:
  - buf.example.com/bufbuild/confluent

  2. Run buf dep update to verify and lock the dependency.

    $ buf dep update

  3. Add one or more buf.confluent.v1.subject options to a new or existing Protobuf message, including your Confluent Schema Registry instance name and the subject's name.

    syntax = "proto3";

package demo.analytics;

import "buf/confluent/v1/extensions.proto";
import "google/protobuf/timestamp.proto";

message EmailUpdated {
  google.protobuf.Timestamp updated_at = 1;
  fixed64 user_id = 2;
  string previous_email = 3;
  string new_email = 4;
  bool new_email_verified = 5;

  option (buf.confluent.v1.subject) = {
    instance_name: "CSR_INSTANCE_NAME",
    name: "email-updated-value",
  };
}

  4. Run buf push to update the module in the BSR. If successful, the subject is created or updated with the message as its schema.

    $ buf push

    You can check it in the browser using your instance URL (you must be logged into the BSR):

    https://buf.example.com/integrations/confluent/INSTANCE_NAME/subjects/email-updated-value/versions/latest

Deregister a schema

Warning

Deregistering a subject makes it available for use by other messages in the same or different modules. This can lead to compatibility issues if the subject is reused with a different schema.

To deregister a schema, remove the buf.confluent.v1.subject option from the message and re-push the module to the BSR with buf push. The subject's schema no longer updates, but is still accessible from the BSR's Confluent Schema Registry API.