Topic Naming and Organisation

In one line

Topic names are a shared API: choose a convention that encodes domain, entity or event, and version, keep environments in separate clusters rather than name prefixes where possible, and decide between one topic per entity stream and one topic per event type based on ordering and consumer needs.

0/5 · 0%

Think of it like this

Street addresses. A good address scheme (country, city, street, number) lets anyone find a building without asking. Topic names like commerce.orders.v1 do the same for data.

Key ideas

01
Common patterns: <domain>.<entity> (commerce.orders), <domain>.<entity>.<event> (commerce.orders.created), with a version suffix only for incompatible changes (commerce.orders.v2). Use lowercase with dots or hyphens consistently; avoid mixing . and _ (Kafka metrics names collide between them).
02
Environment separation: prefer separate clusters (or at least separate ACL-scoped namespaces) for dev, staging and prod. prod.orders in a shared cluster invites cross-environment accidents.
03
One topic per entity (orders with an eventType header) keeps all events for an order in one partition, so their relative order is preserved, and consumers filter what they need. One topic per event type (orders.created, orders.paid) gives clean schemas and ACLs but loses ordering between event types for the same order.
04
Versioning: prefer compatible schema evolution within one topic (Phase 8). Create orders.v2 only for breaking changes, and migrate consumers deliberately (dual-publish for a period).
05
Tenant-aware topics (tenant-a.orders) give isolation but explode topic and partition counts; shared topics with a tenant key scale better (Topic 13.2).

Code & diagrams

naming.txttext

Option                           Ordering across event types  Schema per topic  ACL granularity  Consumer filtering
orders (eventType in header)     yes, per order key           union / envelope  topic            consumer filters
orders.created / orders.paid     no                           clean             per event type   by subscription
orders.v1 -> orders.v2           n/a (migration)              breaking change   topic            migrate consumers
prod.orders (shared cluster)     -                            -                 risky            -   (prefer separate clusters)

Interview problem

The problem

orders vs orders.v1 vs orders.created vs prod.orders.created

Your team debates topic names for order events: orders, orders.v1, orders.created, or prod.orders.created. Discuss the trade-offs and recommend a convention.

Explain it without notes

Why can splitting events into one topic per event type break ordering?

Practice

Write a topic naming convention for your organisation in five rules.

Trade-offs

↔
Fewer, entity-level topics keep ordering and reduce partition count; per-event topics simplify schemas and ACLs.

Done when you can

I can choose a naming convention and topic granularity with reasons.

Command Palette