Lesson 13 · Senior NATS practice

Subject design, wildcard boundaries, and event taxonomy

How to think about subject naming, wildcard capture, event family boundaries, and the long-term cost of messy event taxonomies.

Your win: explain why subject design is not just naming style, and how wildcard scope, stream capture, and event-family boundaries shape long-term fan-out and replay behavior.

Why this page matters more than it first looks

At first, subject naming feels like a low-stakes concern. You pick words, add dots, maybe use a wildcard, and move on. That is the beginner reading. The senior reading starts when you realize those names become part of the system’s long-term structure.

In NATS, subject families affect who can subscribe, what a stream captures, what a wildcard accidentally sweeps in, how replay gets scoped, and how easy it is to explain ownership to the next engineer. That is why this lesson is really about architecture wearing a naming costume.

In plain English Plain English: subject names are the address system, but they also become your future routing and retention boundaries.
The senior shift A subject taxonomy should make routing, wildcard capture, ownership, and future fan-out clearer — not merely shorter or prettier.

Why wildcard boundaries deserve more respect

Wildcards feel convenient because they let one stream or consumer cover a whole event family at once. That convenience is real. The problem is that wildcards quietly create grouping decisions that may live for a long time.

If a wildcard family grows too broad, unrelated events start sharing retention assumptions, ownership assumptions, replay assumptions, and sometimes access assumptions. Once that happens, the system still “works,” but it gets harder to reason about. That is the kind of hidden coupling senior engineers are trained to notice.

So the question is not only “does this wildcard match the events I need?” The better question is “should these events really belong to the same family at all?”

Backend use case In this repo, streams often capture wildcard families like User.* or Notification.*, then consumers narrow back to concrete subjects. The real design judgment is deciding where that family boundary belongs.
Common mistake Treating subject design as a naming convention problem while ignoring how wildcards influence stream scope, consumer filters, and service ownership.
Read this next

Revisit subjects with a design lens

Go back to the official subject and wildcard docs, then compare them with the repo’s centralized constants and stream definitions.

→ NATS subjects
→ Repo NATS map

Check yourself (from memory)

Q1. What is the most senior way to think about subject taxonomy?

Subject names become long-lived system boundaries, not just labels.
Why can a wildcard boundary become a system-design problem?
recall, then click to reveal
Because a wildcard does more than match names: it defines which events get captured, replayed, owned, and reasoned about together. If that boundary is too broad, unrelated events get coupled.
Want a “would you keep these events in one subject family or split them?” design drill? Ask me.

Sources. Official NATS subjects docs; repo NATS map.