Get Started Free
‹ Back to courses
course: Schema Registry 101

Understanding Schema Subjects

4 min
Danica Fine

Danica Fine

Senior Developer Advocate (Presenter)

Schema Subject – What Is It?

sr101-m9-01

This module covers the concept of the schema subject, what it is, the different strategies for subject naming, and how to apply them.

When you register a schema you use a subject name to create a namespace or handle for the schema in Schema Registry.

Recall from a previous module all of the ways to register a schema – using the Confluent CLI, the REST API, or the Gradle plugin. In all cases you must provide the subject name.

The schema subject name is used for:

  • Compatibility checks—they are done per subject
  • Linking version numbers to a subject

Also when you evolve a schema by making changes to it, it’s assigned a new ID and version number, but the subject stays the same. Essentially, the subject name is a unique identifier for a schema – a reference to retrieve it from the store.

Subject Name Strategies

When providing a subject name, there are three strategies or ways to provide it:

  • TopicNameStrategy (default setting)
  • RecordNameStrategy
  • TopicRecordNameStrategy

Let’s take a minute to review each one.

TopicNameStrategy

sr101-m9-03

TopicNameStrategy is the default setting. If auto.register.schema is set to true, schemas that are automatically registered by producers will be registered under topic-name-(key or value).

When you register a schema in any of the three ways previously mentioned, you provide the topic name appended with key or value, e.g. topicA-value.

Using TopicNameStrategy effectively limits the topic to one record type, since all records in the topic must adhere to the same schema. Trying to register a schema for a different type would break the compatibility checks.

RecordNameStrategy

sr101-m9-04

To get around the limitation of one record type for a given topic, we can use RecordNameStrategy. It creates the subject name using the fully qualified class name of the record – again followed by key or value depending on whether the schema applies to the key or value of the message.

RecordNameStrategy allows for different schemas in a topic since the individual records only need to comply with a schema that has the subject name that matches its class.

But you have to use the same schema and version across all the topics in a cluster FOR THAT PARTICULAR RECORD TYPE, since there’s no way to tell which topic the record belongs to.

TopicRecordNameStrategy

sr101-m9-05

TopicRecordNameStrategy is a combination of the first two strategies.

Subject names are created using <topic name>-<fully qualified record name> appended with -key or -value.

Since you’ve now scoped the schema to a particular topic you don’t have to use the same version across all topics in the cluster. FOR THAT RECORD TYPE you can evolve the schemas separately.

Using Different Subject Name Strategies

Choosing and using a particular strategy involves two steps:

  1. Registering the schema with the correct subject name format.
  2. Setting the subject strategy on the clients.

Since TopicNameStrategy is the default, clients are already set to use it. To use a strategy other than the default, set key.subject.name.strategy or value.subject.name.strategy on the client as needed.

  • Record Name Strategy - io.confluent.kafka.serializers.subject.RecordNameStrategy
  • Topic Record Name Strategy - io.confluent.kafka.serializers.subject.TopicRecordNameStrategy

Use the promo code SCHEMA101 to get $25 of free Confluent Cloud usage

Be the first to get updates and new content

We will only share developer content and updates, including notifications when new content is added. We will never send you sales emails. 🙂 By subscribing, you understand we will process your personal information in accordance with our Privacy Statement.

Understanding Schema Subjects

Hi, I'm Danica Fine. In this Schema Registry module, we're going to cover the concept of the schema subject. What it is, the different strategies for subject naming, and how to apply them. When you register a schema, you can use a subject name to create a name space or handle for the schema in Schema Registry. Recall that in a previous module, we saw all of the ways to register a schema using the Confluent CLI, the REST API, or the Gradle plugin. In all cases, you must provide the subject name. The subject name is used for compatibility checks, which are done per subject, and linking version numbers to a subject. Also, when you evolve a schema by making changes to it, it's assigned a new ID and version number but the subject stays the same. Essentially, the subject name is a unique identifier for a schema, a reference to retrieve it from the store. But how do we decide how to provide a subject name? Well, there are three main strategies: TopicNameStrategy, RecordNameStrategy, and TopicRecordNameStrategy. Let's take a minute to review each one. First up is the TopicNameStrategy. This is the default setting. If auto.register.schema is set to true, schemas that are automatically registered by producers will be registered using a subject name consisting of the topic, followed by key or value, depending on whether the schema applies to the key or value of the message. So when you register the schema for a value in any of the ways we previously covered, you'd provide the topic name followed by key, or the topic name followed by value. So for example, for topicA, we'd have topicA-value. Using the TopicNameStrategy effectively limits the topic to one record type, since all records in the topic must adhere to the same schema. Trying to register a schema for a different type would break the compatibility checks. to get around this limitation, we can use the RecordNameStrategy, which creates the subject name using the fully qualified class name of the record - again followed by key or value depending on whether the schema applies to the key or value of the message. The RecordNameStrategy allows for different schemas to coexist within a single topic since the individual records would only need to comply with the schema that has the subject name that matches its class. But you would have to use the same schema and version across all the topics in a cluster for that particular record type, since there's no way to tell which topic the record belongs to. And finally, the TopicRecordNameStrategy is a combination of these two strategies. Subject names are created using the topic name followed by the fully qualified record name and then key or value. Since you've now scoped the schema to a particular topic, you don't have to use the same version across all topics in the cluster. For that record type, you're free to evolve the schema separately. Choosing and using a particular strategy involves two steps. First, you must register the schema with the correct subject name format. And then, you need to set the correct subject name strategy from the client side. Again, since TopicNameStrategy is the default, clients are already set up to use that. So to use a strategy other than the default, set the strategy on the client using the "key." or "value.subject.name" strategy configuration parameters. Note that when setting the subject name strategy, you will need to to use the fully qualified name of the strategy. All right, you now have a good idea of the subject naming strategies available to you. In the next module, you'll see a bit more about how a static subject name helps us to validate schemas over time. See you there.