Message Naming Conventions

One of the first design decisions teams starting with messaging are presented with are - what the heck do we name these things? When building out request/response types for typical API/web applications, I name the responses usually after the resource they represent, or the route, or controller/action. There's something already "around" my message that tells me what to name it.

Durable messages are a bit different - they stand alone, transported on the wire, unencumbered by a "controller" to help guide the name.

Most messaging systems I work with have some sort of class to assist with serialization/deserialization, and it's the name of this class that I use to represent the "name" of the message.

But first, let's look at the different classifications of messages to see how we might name the types.

Message classifications

For my systems, messages can be broadly classified into two major categories:

• Commands
• Events

Commands are an instruction, telling a system to "do something". Approve the invoice. Reject the policy. Turn the light off. Hop on one foot. Commands can be validated, approved/rejected, processed, replied.

Events on the other hand reflect an immutable fact. Invoice approved. Policy rejected. Light turned off. Ankle broken. We can't approve/reject events in the past, even if we would love to turn back the clock on certain recent elections.

With this in mind, how might we name our messages?

Naming commands

Commands typically have two parts:

• Verb
• Subject

The verb is usually the imperative mood, present tense. "Give me a beer". The verb is "give", the mood is "imperative", and the subject, "Beer" (the indirect subject is "me").

I like to include the subject and the verb in the name of the command:

<Verb><Subject>

GiveBeer

Anything else would be information inside of the body of the message. But that's not the only thing we can include, other options include:

<Subject><Verb>

BeerGive

This style is useful when our systems are subject first similar to controller actions. If I had an API controller, I might have many actions:

BeerController
- Give()
- Drink()
- Pour()

In this manner we do the subject first, then the verb. It's a bit awkward to read, however.

Finally, we sometimes include a suffix:

<CommandName>Command

GiveBeerCommand

The reason why we might want the suffix is:

• To make it easy at a glance to see the command
• Quickly view all of our commands (if we're not namespacing already)
• For scanning/serialization purposes (identify all messages as named "*Command"

Commands can also have a response, or a reply, which is logically coupled to the command itself. For these, I use the command name as the prefix, then the suffix of "Reply" or "Response" or "Result", depending on what's appropriate:

GiveBeer
GiveBeerResult

Event naming conventions

While commands are an imperative mood, events represent something that happened in the past, so we typically see events represented as a past-tense verb, along with a subject:

• Past-tense verb
• Subject

Similar to the commands, I include both the verb and the subject as part of the message name, but reversed:

<Subject><Verb>

BeerPoured

In english, it's more natural to have the verb second after the subject for past-tense, direct opposite of our commands.

Other options could include:

<Verb><Subject>

PouredBeer

I find this style a bit more awkward than the reversed Command style.

Finally, we can suffix our name as well:

<EventName>Event

BeerPouredEvent

For similar reasons as we might want in our commands.

I'm personally on the fence on suffixes - on one hand, they can help metadata-driven systems easily identify the events in a system...but on the other hand, with the verb already indicating what kind of message this is, isn't the suffix redundant?

What naming conventions do you use in your systems?