Get Started Free
course: Schema Registry 101

Understanding Schema Subjects

4 min
Danica Fine

Danica Fine

Senior Developer Advocate (Presenter)

Schema Subject – What Is It?


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



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