skip to content

Subject Naming Strategies

How a schema gets its subject name, and what that decides about putting multiple event types on one topic. Interviewers ask because the default TopicNameStrategy quietly forbids heterogeneous topics.

part ofApache Kafkaoverview, primer and where to startread it →
on this pageshow

questions

5

In Confluent Schema Registry, what is a 'subject' and what is the default TopicNameStrategy used to derive it?

level: juniorimportance: must knowfreq 70%

answer

  1. Subject = versioned compatibility scope
  2. Default = TopicNameStrategy
  3. <topic>-key / <topic>-value
  4. key/value.subject.name.strategy config
  5. compatibility checked per subject

basics

~10 s

A subject is the named scope under which schema versions are registered and evolution is checked. The default TopicNameStrategy names it after the topic plus a suffix: <topic>-key for keys and <topic>-value for values.

solid answer

~30 s

A subject is the namespace in Schema Registry under which a sequence of schema versions lives; compatibility checks run per subject. The serializer decides which subject to register a schema under via a SubjectNameStrategy. The default, TopicNameStrategy, derives the subject from the topic name: it appends -key for the message key schema and -value for the value schema. So topic 'orders' produces subjects 'orders-key' and 'orders-value'. This default ties one schema lineage to one topic, which is simple and the right choice when a topic carries a single record type. The strategy is selected with key.subject.name.strategy and value.subject.name.strategy on the serializer.

go deeper

for a junior

Know that subject = where schema versions live, and the default names it <topic>-key / <topic>-value.

for a middle

Explain that compatibility is per-subject and the strategy is set via key/value.subject.name.strategy.

for a senior

Articulate why the default ties evolution to a topic and when that becomes a limitation.

for a principal

Frame the subject as the unit of governance and evolution, and reason about how strategy choice shapes schema lifecycle across an organization.

## What a subject is Confluent Schema Registry stores schemas and assigns each a globally unique integer **schema ID**. But schemas don't evolve in a global pool — they evolve within a named scope called a **subject**. A subject is essentially a versioned timeline: registering a schema under subject `orders-value` creates version 1; registering a compatible evolution creates version 2; and so on. **Compatibility checks (BACKWARD, FORWARD, FULL, etc.) are evaluated per subject** — the registry compares the incoming schema against existing versions of *that subject*. ## How the subject is chosen: SubjectNameStrategy When a Kafka producer serializes a record with `KafkaAvroSerializer` (or Protobuf/JSON Schema equivalents), the serializer must decide *which subject* to register/look up the schema under. That decision is made by a pluggable `SubjectNameStrategy`. Two config keys select it independently for key and value: - `key.subject.name.strategy` - `value.subject.name.strategy` ## The default: TopicNameStrategy The out-of-the-box strategy is `io.confluent.kafka.serializers.subject.TopicNameStrategy`. It builds the subject purely from the **topic name** and whether the field is a key or value: - key schema -> `<topic>-key` - value schema -> `<topic>-value` So producing to topic `orders` yields subjects `orders-key` and `orders-value`. The `-key`/`-value` suffix exists because a topic's key and value are independent schemas that must evolve separately. ## Why this default exists It is the simplest mental model: one topic, one value schema lineage. Schema evolution is scoped to that topic, and consumers reading the topic know exactly which subject governs it. It is the correct choice when **each topic carries exactly one record type** — the overwhelmingly common case. ## Edge cases / things to know - The subject name has nothing to do with the schema's own name/namespace under TopicNameStrategy — it is derived solely from the topic. - Because the subject is topic-scoped, you cannot put two unrelated, independently-evolving record types in the same topic under this default without compatibility conflicts (they'd collide in the same `-value` subject). Solving that is what RecordNameStrategy / TopicRecordNameStrategy address.

  • Why are there separate -key and -value subjects for one topic?
    Because a record's key and value are independent schemas that evolve on their own timelines, each needs its own subject so compatibility is checked separately.
  • At what granularity does Schema Registry enforce compatibility?
    Per subject. The incoming schema is compared against prior versions of that same subject, governed by the subject's (or global) compatibility level.

saying these in an interview costs you the question

  • Saying the subject is derived from the schema's name under the default strategy (it's derived from the topic name).
  • Claiming compatibility is checked globally across all schemas rather than per subject.
  • Thinking the schema ID and the subject are the same thing.

context

open as a page

Compare RecordNameStrategy and TopicRecordNameStrategy. What subject does each produce and when would you choose one over the other?

level: seniorimportance: must knowfreq 55%

basics

~10 s

RecordNameStrategy names the subject after the schema's fully-qualified record name, so it's topic-independent and shared across topics. TopicRecordNameStrategy prefixes that with the topic (<topic>-<fqn>), scoping the same record type per topic.

open as a page

Which serializer configs select the subject naming strategy, and how do you set them differently for keys and values?

level: middleimportance: should knowfreq 50%

basics

~10 s

Use key.subject.name.strategy for the key schema and value.subject.name.strategy for the value schema. Each takes a fully-qualified strategy class such as TopicNameStrategy (default), RecordNameStrategy, or TopicRecordNameStrategy.

open as a page

You need to publish several related event types (OrderCreated, OrderShipped, OrderCancelled) to a single topic to preserve their ordering. How do you configure subject naming and serialization to make this work?

level: seniorimportance: should knowfreq 45%

basics

~20 s

Switch off the default per-topic subject by setting value.subject.name.strategy to RecordNameStrategy or TopicRecordNameStrategy, so each event type gets its own subject. Also disable auto-union validation issues by using a schema that allows the multiple types (e.g. an Avro union).

open as a page

As a platform architect standardizing subject naming across many teams, what are the trade-offs of RecordNameStrategy (sharing) versus TopicRecordNameStrategy (isolation), and how would you govern them?

level: principalimportance: should knowfreq 30%

basics

~20 s

Sharing (RecordNameStrategy) gives one canonical type definition reused everywhere but a large blast radius for changes and unclear ownership. Isolation (TopicRecordNameStrategy) limits blast radius per topic but allows drift and many subjects. Govern with ownership, compatibility policy, and CI registration.

open as a page