Nats/Jetstream: naming conventions for commands' subjects

Question

I have been working with Nats/Jetstream for a bit now and within a CQRS/Event sourcing project. Recently, it occurred to me that I have not been following any naming conventions for subjects' names that are used for commands (events are pretty much covered). What have been doing so far is, as follows:

myProjectName.internal.pricing

Meaning the myProjectName as my project name, internal as it is internal to a specific service in my project and then ultimately the action performed by that command (e.g. some pricing logic). Are there any widely used naming conventions I can use? I would appreciate if you can share any view or resource I can use to have a better naming across my project.

Thank you

Rhondarhondda

Answer 1

There are good articles about it:

• Subject-Based Messaging
• Kafka topic naming conventions - 5 recommendations with examples
• Kafka Topic Naming Conventions

General recommendations:

• separate.with.dots.lowercase - avoid capitalization.
• Keep your subject short. It is recommended to keep the maximum number of tokens in your subjects to a reasonable value of 16 tokens max.
• Create a structure for grouping. The separation by a dot (.) and the structure in the sense of the Reverse Domain Name Notation (reverse-DNS) has proven itself. Prefer Domain Service Names (see DDD).
• Explicitly mark the data as "private" or "public" with a corresponding prefix - "private" is for internal subjects, "public" - for official.

public.sales.ecommerce.shoppingcarts
private.risk.portfolio.analysis.loans.csvimport

• Suffixing by can be a good way to indicate in advance how to consume a topic for example .avro , .json, .text, .protobuf, .csv, .log.
• You could prefix JetStream subject: js.in.orders.> (where .in/.out is the prefix for inbound or outbound messages).

What should be avoided?

• Appending of a version number - the better way is to add the version number of the used schema as part of the header to the respective record. It is even better to use a schema registry in which all information about the schema, versioning, and compatibility is stored centrally.
• Using application names as part of the topic name.
• Team name/partition numbers or consumer/producer names.
• Namespaces or company names - your colleagues usually know the name of the company where they work

public.com.xeotek.sales.ecommerce.shoppingcarts

Similar question about Kafka topics best practices: What is the best practice for naming kafka topics?

Viccora

Such a brilliant and well articulated answer, thank you so much! – Rhondarhondda

I'm wondering about the first 'avoid' item. According to an example from NATS documentation docs.nats.io/nats-concepts/…, version numbers in the subject are more than acceptable thing. It's also possible to extract the subject in case of wildcard subscription to v1, v2, v3 subjects, so there is a way to know which message schema to use docs.nats.io/using-nats/developer/receiving/wildcards – Wallflower