What should a Kafka topic naming convention communicate?

A Kafka topic naming convention should communicate three things: the domain or business area the topic belongs to, the owning team, and the purpose or event type. A good convention is domain-oriented and hierarchical: <domain>.<entity>.<event-type> or <domain>.<subdomain>.<entity>.<event-type>. For example, orders.order.created, payments.payment.processed, or inventory.stock.adjusted. The domain tells you what part of the business the data belongs to; the entity tells you what object the event is about; the event type tells you what happened. This makes topics discoverable: a new engineer can browse the topic list and understand what exists without reading documentation. It also makes ownership clear: the domain usually maps to a team, so the topic's owner is obvious. A naming convention also supports automation: you can use prefixes for ACLs, quotas, and retention policies. For example, all topics starting with orders. can be owned by the orders team, with a standard retention and compatibility policy. The trade-off is between richness and simplicity. A very detailed convention (e.g., <region>.<env>.<domain>.<subdomain>.<entity>.<event>.<version>) is highly informative but verbose and hard to remember. A simple convention (e.g., <domain>.<entity>) is easy but may not capture enough context. The right balance depends on the organization's size and structure.

The mechanism for enforcing a naming convention is a combination of documentation, automation, and validation. Document the convention and provide examples. Automate topic creation through a self-service control plane that validates the name against a regex or a schema. Use prefixes for access control: ACLs can be granted on a prefix (e.g., orders. prefix) so that a team automatically has access to its topics and not others. Use the same prefix for quotas and retention policies, so that all topics in a domain have consistent settings. The trade-off is between flexibility and consistency. A strict convention makes the platform predictable but may not fit every use case; a loose convention is flexible but leads to inconsistency. For a platform with many teams, strict is usually better. Version note: Kafka does not enforce naming conventions; you enforce them with automation. The control plane should reject names that do not match the convention. Some platforms also use a topic registry or catalog that documents each topic's owner, schema, and retention. This is valuable for discovery and governance. Examples of conventions in the wild include Confluent's recommendation of <domain>.<entity>.<event> and Uber's use of <domain>.<service>.<event>. The key is to be consistent and to document the convention.

A common mistake is to use generic names like events, data, or topic1, which tell you nothing about the content or owner. Another mistake is to include environment or region in the topic name, which forces the same topic to have different names in different environments and complicates replication. A better approach is to use separate clusters or namespaces for environments and keep the topic name consistent. A third mistake is to change the naming convention after topics are created, which breaks ACLs, quotas, and automation. The trade-off is between the cost of establishing a convention and the cost of not having one. A good convention is an investment that pays off as the platform grows. Version note: if you use a schema registry, the subject name is usually derived from the topic name (e.g., <topic>-value and <topic>-key). This means the naming convention affects the schema subjects as well. Keep the convention consistent across topics and schemas. For multi-tenant platforms, the convention should also encode the tenant or team, so that isolation is clear.