A joining team reads a stream's name before any documentation — which segments should the name carry, and why each?
answer
- the name is read before the docs
- four questions a newcomer would ask
- domain, purpose, environment, version
- rules match the name from the left
- nothing that goes stale faster than the stream
basics
~20 sA stream's name should carry the owning domain, its purpose, the environment and a version segment. Each answers a question a joining team would otherwise have to ask a person, and grants and quotas are written against the leading segments.
solid answer
~40 sFour segments carry their weight. The **domain** says which part of the business owns the traffic. The **purpose** says what is in the stream. The **environment** says whether this is real traffic or not. The **version segment** says whether this is the current stream or one being replaced. Order them most-general to most-specific, because a name is not only read by humans: grants, quotas, mirroring rules, dashboards and cost reports are written against the leading segments, and prefix matching reads left to right. So the domain belongs first. What the name should *not* carry is anything that goes stale faster than the stream: the owning team's current name, the producing service, the payload's encoding, a date.
code
yaml · 19 lines# One stream name, split into the segments it is built from
segments:
domain: payments
purpose: authorisation-requested
environment: production
version: v2
# Joined with whatever separator the platform accepts
name: payments-authorisation-requested-production-v2
# What is written against the LEADING segment, not the whole name
grant:
principal: payments-publisher
operations: [write]
applies-to: payments-*
quota:
applies-to: payments-*
set-by: platform-team
last-reviewed: nevergo deeper
Recall the four questions a name should answer without anyone being asked: which domain, what is in it, is this real traffic, is this the current one. Being able to name those four is the whole of what is expected here.
Explain why order matters — grants, quotas, mirroring rules and dashboards match a name from the left, so the segment those rules select on has to come first. Then explain what must stay out of the name and why.
Show that you have seen a convention decay: the abbreviation nobody can expand, the missing environment segment that let a sweep run against real traffic, the team name in a stream that outlived three reorganisations.
Frame the name as an interface with a cost of change. Every segment is a promise to keep something true for the life of the stream, so the design question is which facts are stable enough to be worth encoding at all.
## Why the name is read first A stream's name is the one piece of metadata that turns up everywhere without being asked for: in the code that publishes to it, in the grant that permits that publish, in the quota that caps it, in the dashboard panel someone stares at during an incident, and in the message a stranger sends asking who owns this thing. A catalogue entry is read when somebody goes looking. The name is read whether or not anybody goes looking. That asymmetry is the whole argument for treating a naming convention as an operational control rather than a style preference. The test for a good name is blunt. An engineer from another team, with no context and no catalogue open, should be able to say what flows through the stream, which part of the business owns it, whether it is carrying real traffic, and whether it is the current one. Four segments answer exactly those four questions. ## The four segments | Segment | The question it answers | What its absence costs | |---|---|---| | **domain** | Which part of the business is this? | Grants and quotas have no stable prefix to hang off, so every rule must enumerate individual names. | | **purpose** | What is actually in it? | Every incident starts with a lookup, and two teams independently create two streams for one thing. | | **environment** | Is this real traffic? | The most dangerous omission: real traffic mistaken for test traffic, or an automated sweep that clears one prefix taking the other with it. | | **version segment** | Is this the current one? | A replacement has nowhere to go, so meaning gets changed in place and readers find out from the wreckage. | ## The name is machine-readable too The segments are not only prose for humans. On a running estate the name is routinely the key that these are written against: - **grants** — one binding of a principal to an operation on a stream or a prefix; - **quotas** — a ceiling attached to a name or to the space the name sits in; - **mirroring and routing rules** that select which streams are copied to a second cluster; - **dashboards, saved searches and alert conditions**, which match on a name pattern; - **cost attribution**, which sums stored bytes by prefix; - **automated sweeps**, which act on everything under a pattern. All of those read a name from the left. That is the practical reason segment order is not arbitrary: put what the rules select on first. Domain before purpose, purpose before environment, and the version segment last, where it changes without disturbing anything matching the prefix above it. ## Where platforms differ A convention only exists if the platform will accept it, and platforms in this class genuinely disagree: - some provide a **first-class named space** that scopes names, grants and quotas, so part of what would be a segment is carried by the container instead; others offer only a flat name where the prefix *is* the grouping; - **character sets and length ceilings differ** — separators one platform accepts are rejected or reserved by another, and some fold case; - **grants match differently**: prefix matching on some, exact names only on others, space-level only on a third; - some reserve a prefix for the platform's own internal streams, which your grammar must not collide with. If there is any chance of mirroring onto a second platform, the alphabet you can actually use is the intersection of both. ## Writing the grammar down 1. **Fix the segment order once** and publish it, with an example of a conforming name. 2. **Publish a closed vocabulary for the domain segment**, with the expansion of every abbreviation written down somewhere that outlives the team that coined it. 3. **Pick a separator the platform accepts** and forbid it inside a segment, so the name can be split mechanically. 4. **State what must not appear**, because every stale segment is a lie the name tells for years. ## What the name must not carry - **the owning team's current name** — organisations reorganise far more often than they redraw domains, and the owning team belongs in the stream's owner record, not in its identity; - **the producing service** — services get rewritten, split and replaced while the stream stays; - **the payload's encoding** — that is governed elsewhere and changes on its own schedule; - **a date or a ticket identifier** — meaningful for one sprint, noise for a decade. Everything you decline to encode is something that cannot go stale, and every segment you do encode is one you are promising to keep true.
- Where do the separator and the length of a name stop being a free choice?At the platform. Brokers in this class differ in which characters they accept in a name, how long a name may be, whether case is folded, and which prefixes they reserve for their own internal streams. A grammar the platform rejects is not a grammar. If you may ever mirror onto a second platform, the usable alphabet is the intersection of the two.
- Should the owning team be a segment of the name?No. Teams are renamed, merged and split far more often than business domains are redrawn, and because a rename is a migration you would be paying for every reorganisation. Name the domain, which is stable, and keep the current team in the stream's owner record, where changing it is an edit rather than a migration.
A street address on an envelope: the country, city and street are read left to right by every sorting machine the letter passes, and none of them opens the envelope to find out where it is going.
saying these in an interview costs you the question
- Treats the name as a label that can be changed later
- Encodes the current team or reporting line instead of the domain
- Leaves the environment out because everyone knows this cluster
- Invents a new abbreviation per stream with no published expansion
- Says the version segment tracks the payload's field changes
- Puts the most specific segment first, so no prefix rule is possible