A naming convention is a written agreement about how every topic in your organization is named.

Start with the basic words. Apache Kafka is a system that stores streams of messages and lets many programs read and write them. A message, also called a record, is one small piece of data, such as “order 1001 was paid”. A topic is a named place where messages of one kind are stored, like a labeled folder. Programs that write messages are producers, and programs that read them are consumers. Servers that hold the data are brokers.

A naming convention is a set of rules that says how a topic name is built. For example: “the name has four parts separated by dots, in lowercase: environment, domain, entity, and version”. If every team follows the rule, a name such as prod.sales.order-paid.v1 tells you at a glance where the data comes from, what it is, and which edition you are looking at.

The convention is not a Kafka feature. Kafka only checks a few basic character rules. The convention is a human and process agreement, ideally backed by tools that check it automatically. Think of it as the grammar of your cluster.

A topic name is used everywhere: in code, in security rules, in dashboards, in alerts and in conversations between people.

Three facts make topic names special. First, a topic cannot be renamed. To change a name you must create a new topic, copy the data, and move every producer and consumer. Second, the name is copied into many other places: application configuration, access control rules, monitoring queries, schema subjects, connector settings and documents. Third, names are read by humans in an emergency at three in the morning, when clarity matters most.

What good names give you

A good name is built from a few small parts placed in a fixed order, like beads on a string.

Most conventions choose from the same set of parts. Not every organization needs all of them. The art is picking the smallest set that answers the questions people really ask.

flowchart LR
  A["Environment"] --> B["Domain or business area"]
  B --> C["Subdomain or service"]
  C --> D["Data type"]
  D --> E["Entity name"]
  E --> F["Version"]

Read the figure from left to right. The name starts broad and becomes more specific, just like an address that moves from country to house number. Each part answers one question.

Putting these together might give prod.sales.checkout.event.order-paid.v1. That is long but complete. Many teams shorten it by dropping parts that are already known. A cluster that serves only production does not need an environment part. A small company with one domain does not need a domain part.

Before designing rules, know the limits of the platform. Your convention must live inside them.

The dot and underscore collision

Kafka turns topic names into metric names for monitoring. In that process, a dot and an underscore can look the same. A topic called orders.paid and another called orders_paid may produce clashing metric names, and Kafka refuses to create a topic whose name collides this way with an existing one. This is a technical reason to pick one separator style and stay with it, rather than mixing dots and underscores in the same cluster.

Case sensitivity

Because names are case sensitive, “Orders” and “orders” can exist together, which invites confusion. Choose lowercase for everything. Lowercase names are easier to type, easier to match with patterns, and safe on systems where file names ignore case, since topics are stored as folders on disk.

Small style choices, made once, prevent thousands of small arguments later.

A separator is the character that splits the parts of a name. The three legal choices are the dot, the hyphen and the underscore. Each has strengths.

A popular combination

Many teams use dots between levels and hyphens inside a level. So sales.checkout.order-paid.v1 has three levels split by dots and a compound word joined by a hyphen. This gives you a clear hierarchy and readable words, and it avoids mixing dots with underscores.

Other style rules worth writing down

There is no single correct convention. Here are the main families, with their good and bad sides.

Which family should you choose?

For most growing organizations, domain first works best. Business domains such as sales, billing, shipping and identity are more stable than team names or technologies. Data outlives the team that first wrote it. A domain-based name still makes sense after three reorganizations.

Domain-based naming ties each topic to a part of the business, so ownership and meaning are obvious.

A domain is an area of the business with its own language, rules and people, such as payments, inventory or customer identity. The idea comes from a design approach that splits a large system into domains, each owned by one team. The team is responsible for the data it publishes, just as a department is responsible for its reports.

Choosing domain names

Subdomains and services

Inside a domain, a second level often names a subdomain or a service, for example sales.checkout and sales.catalog. Be careful with service names: services are split and merged over time. Where possible, name the subdomain by business function, not by the current application that happens to implement it.

Not all messages are alike. A good name tells readers what kind of message a topic holds.

Three kinds of data appear again and again in Kafka systems, and mixing them causes confusion.

Ways to show the kind in the name

The reason to show the kind is that each kind is treated differently. Events are usually kept for a time period, commands are short-lived, and state is often compacted. Setting the right default for each kind is easier when the name reveals the kind.

Some topics are promises to the whole company. Others are private details of one application. Names should show which is which.

A public topic, sometimes called a shared or contract topic, is meant to be read by other teams. Its format is a promise: the owner will keep it stable, document it and version it carefully. A private topic is used only inside one application or team. Its format can change freely because no outsider depends on it.

flowchart LR
  A["Service A private topics"] --> B["Service A logic"]
  B --> C["Public topic: sales.order-paid.v1"]
  C --> D["Team B consumer"]
  C --> E["Team C consumer"]
  F["Team B private topics"] --> D

The figure shows that service A keeps its own working topics private, and publishes only one clean public topic that teams B and C read. If service A changes its internal design, only its private topics change, and the public promise stays.

Marking visibility in names

Besides business topics, many helper topics appear. They also need clear names.

A pattern for retry and dead letter names

A common approach is to add a suffix to the source topic name and to include the consumer group, because two different consumers of one topic may fail on different messages. For example, a topic sales.order-paid.v1 read by the group billing-invoicer could have sales.order-paid.v1.billing-invoicer.retry-1 and sales.order-paid.v1.billing-invoicer.dlt. The suffix approach keeps related topics sorted together in listings and lets access rules treat them as a family.

Data shapes change. A version marker lets you introduce a breaking change without breaking every reader on the same day.

A version in a name, such as v1 or v2, marks a major edition of the message format. It is not needed for every small change. Kafka teams usually keep a schema registry that checks compatibility of changes. Adding an optional field, for example, can happen without a new topic. But some changes are breaking: removing a field, changing a meaning, or changing a type in a way old readers cannot understand. For breaking changes, a new topic name gives everyone a clean path.

flowchart TD
  A["Producer writes v1 topic"] --> B["Breaking change needed"]
  B --> C["Create v2 topic"]
  C --> D["Producer writes both v1 and v2"]
  D --> E["Consumers migrate one by one"]
  E --> F["All consumers on v2"]
  F --> G["Stop writing v1 and retire it after retention"]

The figure shows the dual-write period. The producer writes the same fact in both formats for a while. Each consuming team switches when ready. When nobody reads v1 any more, the producer stops writing it, and the old topic expires under its retention rules and is then deleted.

Where to put the version

Use major versions only

A name should carry only the major version, like v1 and v2, never v1.2.3. Minor changes should be compatible and therefore need no new topic. If names carry minor versions, every small change forces every consumer to switch, which defeats the purpose.

Should the environment, such as production or test, be part of the topic name? It depends on how you run your clusters.

An environment is a stage of software life: development, testing, staging, production. A cluster is a group of brokers working together. There are two main designs.

Separate clusters are the cleaner design. The application uses the same topic name in test and production, and only the connection address differs. This means the name is a stable business identity, not a deployment detail. It also reduces mistakes where a test program accidentally writes to a production topic.

If you must share a cluster

Use a short prefix such as dev, stg and prd, and make the prefix come from configuration, not from code. Add access rules so that test identities cannot touch production prefixes. Be strict about it, because a shared cluster removes the safety wall that separate clusters give.

Cluster and region names

When data is copied between clusters, for example for disaster recovery or for sharing across regions, replication tools often add the source cluster name to the topic name, such as us-east.sales.order-paid.v1. Plan for this. Your convention should not fight the prefix rules of the replication tool you choose, and you should decide whether consumers read the local copy, the remote copy, or both.

Names and security work together. A good hierarchy lets one short rule cover many topics.

Kafka uses access control lists, called ACLs, to decide who may read from or write to a topic. An ACL rule can name one exact topic, or it can use a prefix, which matches every topic whose name begins with a given text. With prefix rules, “team billing may write to every topic starting with billing.” is one line. Without a good naming design, the same policy needs hundreds of lines that must be updated with each new topic.

The first part of the name is the most valuable

Prefix rules can only look at the beginning of the name. Therefore, the part you most need to secure by, usually the domain or a visibility marker, must come first. Put a part at the end and it can be used for reading but not for prefix-based access rules.

Some topics carry personal or secret data. The name can signal how carefully to treat them, but it must never leak the data itself.

Data classification is a label that says how sensitive data is, for example public, internal, confidential and restricted. Companies use classification to decide encryption, retention, who may read it and how it may be copied.

Why a topic per customer is a trap

Each topic has partitions, and each partition has files and memory costs on the brokers. Tens of thousands of tiny topics slow down cluster management. Naming problems come with it: customer identifiers land in names, logs and metrics. The better design is a single topic keyed by customer identifier, with access to the data controlled through application logic and encryption where needed.

A name is short. Much of what people need to know belongs in metadata attached to the topic.

Names should carry only what is stable and needed for rules. Everything else, such as owner, contact channel, description, retention reasons, data classification and links to documents, should live in a topic catalog. A catalog is a searchable list of topics with details. It can be a dedicated tool, a shared repository of configuration files, or a simple registry.

Topics as code

Many teams keep topic definitions in a repository as configuration files. A definition lists the name, partitions, replication, retention and metadata. Changes go through review, and a tool applies them to the cluster. The repository then becomes the catalog and the audit trail. Naming rules can be checked automatically during review.

Names are read by people and typed into tools. Keep them long enough to be clear and short enough to be usable.

Kafka allows 249 characters, but that is a ceiling, not a target. Long names are hard to fit into dashboards, hard to say in meetings, and easy to mistype. A practical target is under about fifty characters, with each part a short word or two.

Sorting is a design tool

Lists of topics are usually sorted alphabetically. Because of this, the order of parts decides how things are grouped. With the domain first, all sales topics sit together. With the entity first, all order topics from different domains sit together, and ownership is scattered. Pick the order that matches how people browse.

Matching by pattern

Consumers can subscribe to topics by a pattern, and tools can select topics by pattern. Well-structured names make patterns simple. A pattern that means “every version one event topic in sales” is easy if parts are regular. It is impossible if names follow no shape.

Topics are not alone. Consumer groups, connectors, schemas and applications should follow related rules.

Schema subjects and topic names

A schema registry stores the message formats. Each format is saved under a subject. The default strategy builds the subject from the topic name plus “-key” or “-value”. That means topic names flow into schema subject names, so a clean topic name gives clean subjects. Other strategies use the record type name instead, which allows several kinds of events in one topic. Decide the strategy at the same time as the topic convention, since they affect each other.

Consumer groups tell the story of who reads what

When something is slow, people look at consumer groups. A group name such as “app1” says nothing. A name like “billing-invoicer” tells the reader who is behind the reading. Aligning group names with service names, and with the same domain words used in topics, makes incident work far quicker.

A convention only works if topics are created through a controlled path. Otherwise the rules are suggestions.

Turn off automatic topic creation

Kafka can be set to create a topic automatically the first time a program writes to or reads from a name. This feature is handy in demos and harmful in production, because a single typo creates a real topic with default settings. Set the broker option for automatic creation to false in production clusters, so topics come into being only on purpose.

Choose a creation model

What the checks should verify

Rules that only exist in a document are forgotten. Rules that exist in a tool are followed.

flowchart TD
  A["Team writes topic definition"] --> B["Pull request opened"]
  B --> C["Automated name and settings check"]
  C -->|"Fails"| D["Feedback to the team"]
  D --> A
  C -->|"Passes"| E["Owner and platform review"]
  E --> F["Merge"]
  F --> G["Tool creates topic on the cluster"]
  G --> H["Catalog and access rules updated"]

In the figure, a team writes the definition as a file and opens a request for review. A robot checks the name and settings at once and returns errors in seconds. Humans review only the meaning. After the merge, a tool creates the topic and updates the catalog and access rules, so the cluster, the documents and the security stay in step.

Layers of enforcement

Let us design a convention for a fictional online store step by step.

The store has several teams: catalog, checkout, payments, shipping and customer identity. It runs one production cluster and one test cluster. Data is shared between teams and there are a few sensitive topics that hold personal data.

Decisions

Resulting names

Notice how much a stranger can learn. The first word gives the owning area, the middle gives the object, the entity name says event or state, and the end gives the edition. Access rules also become short: the payments team may write to everything starting with “payments.”, and everyone may read public event topics through a small, reviewed list.

Most teams do not start from a blank page. They inherit hundreds of topics with names nobody dares to touch. Here is a safe way forward.

Because a topic cannot be renamed, “fixing” a name means creating a new topic and moving traffic. That is real work with real risk, so it must be chosen carefully. Not every bad name deserves a migration. A useful rule is to migrate only when a bad name causes ongoing pain, such as security gaps, confusion in incidents, or blocked automation.

flowchart TD
  A["Scan all topics"] --> B["Classify: good, tolerable, harmful"]
  B --> C["Freeze new bad names"]
  C --> D["Pick harmful topics by value and risk"]
  D --> E["Create new named topic"]
  E --> F["Copy old data and dual write"]
  F --> G["Move consumers one by one"]
  G --> H["Retire old topic after safe period"]

Steps in plain words

Aliases through documentation

Kafka has no built-in alias feature. For topics you cannot migrate, record the “good name” in the catalog next to the real one, so people can search by the name they expect. Documentation is a weak substitute for a proper name, but it costs almost nothing.

When names reveal the kind of topic, you can apply the right settings by default.

Different kinds of topics want different settings. Retention decides how long messages stay. Compaction keeps only the newest message per key. Replication decides how many copies exist. Partitions decide how much parallel work is possible. If the name shows the class, templates can apply sensible defaults and reviewers can spot odd choices.

The numbers above are typical starting points, not rules. Your legal, business and cost needs decide the real values. The table simply shows how a naming class can lead to a settings template, so that the person creating a topic answers one question, “which class is this?”, and inherits a tested set of defaults.

Every metric, log line and alert mentions a topic name. Good names make monitoring smarter.

Monitoring systems group and filter by text. With regular names, you can build one dashboard per domain, one alert per class, and one report per team without listing topics by hand. New topics appear in the right dashboards automatically because they match the pattern.

What to watch per topic

When many teams share a cluster, names help share it fairly.

Multi-tenancy means several teams, called tenants, use one cluster. To keep them from harming each other, operators use quotas, which limit how much traffic a client may send or receive, and access rules. Quotas are attached to client identities and users, not to topic names, yet naming discipline supports them: a client identifier that matches the owning service and a domain prefix that matches the owning team make it easy to see who is heavy and who to talk to.

Tenant prefixes

In some organizations every team gets a prefix, and all topics of that team begin with it. The team can then be given permission to create, alter and delete topics under its prefix and nowhere else. This delegates safe self-service: the team moves fast inside its own area, and the platform team does not review each name.

Cost attribution

Storage and traffic cost money. When each topic maps to one domain and each domain to one owner, you can total storage and throughput by domain and show each owner their share. People who see the bill tend to fix forgotten topics and oversized retention very quickly.

A convention influences how many topics you create, and topic count has a real cost.

Each topic has one or more partitions, and each partition is stored as files on brokers and tracked in cluster metadata. Very large numbers of partitions increase memory use, recovery time after failures, and the load on the cluster’s control system. Modern Kafka versions handle far more partitions than older ones, but the cost is still real, and limits differ between self-managed and cloud services.

How naming design affects the count

The choice between one topic for many event types and many topics

If events must be read in exact order, such as “order created”, “order paid”, “order shipped” for one order, putting them in one topic keyed by order identifier preserves order. If events are independent, separate topics are simpler for consumers, who then only read what they need. Your convention should name the “family” topic by the entity, for example sales.order.v1, and the separate-event topics by event, for example sales.order-paid.v1. Pick one style per domain, and record why.

A strict convention brings order, and it also brings costs. Weigh both honestly.

Key trade-offs

Naming mistakes show up as strange incidents. Here is how to recognize them.

flowchart TD
  A["Unexpected topic or access problem"] --> B{"Is the name valid and in pattern"}
  B -->|"No"| C["Find creator; fix definition; migrate or delete"]
  B -->|"Yes"| D{"Does an access rule cover the prefix"}
  D -->|"No"| E["Adjust the prefix rule or the name"]
  D -->|"Yes"| F{"Does a schema subject match"}
  F -->|"No"| G["Register schema under the right subject"]
  F -->|"Yes"| H["Check client configuration and client identity"]

Patterns that repeatedly work, and mistakes that repeatedly hurt.

A short list to take away and check against your own cluster.

These are illustrations of common situations, not reports about specific companies.

Use this outline as the skeleton of your own written convention.

Tips for adoption

Plain meanings for the words used in this guide.

Short answers to questions that come up again and again.

A topic name is a small piece of text that carries a large share of a cluster’s clarity, safety and cost.

Kafka permits many names but offers no guidance on choosing them. A good convention fills that gap: it picks one style, orders the parts from broad to specific, shows the kind and visibility of the data, marks versions only when needed, treats internal and helper topics with the same care, and is checked by tools instead of memory. Because names cannot be changed, the early decisions matter most, and the cheapest time to make them is before the cluster grows.

Remember also that a convention is a living agreement. Review it after incidents, listen to the teams who use it, keep the written guide short and full of examples, and let automation carry the boring checks so that people can spend their attention on the meaning of the data. Start today with one page, one checker script and one honest inventory of your existing topics.