Why document a topic at all?

A topic is a contract between teams. Producers and consumers deploy independently, so a written schema, retry policy, and dead-letter rule prevent silent breakages when one side changes a field or assumes a delivery guarantee the other does not provide.

What is a dead-letter queue?

A dead-letter queue holds messages that could not be processed after the configured retries. Routing failures there instead of dropping or infinitely retrying them keeps the main queue healthy and lets you inspect and replay the failures.

How should I choose a retry policy?

Use exponential backoff with a capped maximum so transient failures recover without hammering a struggling consumer. Set the retry count high enough to ride out brief outages but low enough that a permanently bad message reaches the dead-letter queue quickly.

Does this work for Kafka, RabbitMQ, and SQS?

Yes. The spec is broker-agnostic Markdown. The vocabulary maps to Kafka topics, RabbitMQ exchanges/queues, or SQS queues — adjust the retry and dead-letter sections to your broker's exact features.

Is anything uploaded?

No. The whole spec is generated in your browser from your inputs and is never sent to a server.

What is the Message Queue / Topic Specification Builder?

Builds a message queue topic specification — topic name, JSON payload schema, producer services, consumer services, retry policy, and dead-letter queue configuration — exported as clean Markdown for your architecture docs. It runs free in your browser on Gera Tools, with nothing uploaded.

Message Queue / Topic Specification Builder

Name: Message Queue / Topic Specification Builder
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

Turn a message topic into a clear contract

Event-driven systems break quietly: a producer renames a field, a consumer assumes at-least-once delivery, a poison message loops forever. The fix is a written contract for every topic. This builder generates a complete, broker-agnostic Markdown spec — payload schema, producers, consumers, retry policy, and dead-letter rules — so both sides of the queue agree before they ship.

How it works

You describe the topic and the builder assembles a structured Markdown document with these sections:

Topic — the name and a one-line purpose, plus delivery semantics (at-least-once, at-most-once, or exactly-once).
Payload schema — your fields rendered as a typed JSON example and a field table, so consumers know exactly what to parse.
Producers — the services that publish to the topic, making ownership explicit.
Consumers — the services that subscribe, each effectively a separate contract.
Retry policy — strategy (exponential backoff), max attempts, and base delay.
Dead-letter queue — the target queue name and the condition that routes a message there.

The payload table infers a JSON type from each field’s declared type, and the example object shows a representative value per field so the document doubles as a quick reference.

A worked example

Suppose an order service publishes and a fulfilment service consumes. The spec might look like this:

Topic name: orders.created
Delivery: at-least-once (fulfilment must be idempotent on order ID)
Payload fields: orderId (string, required), customerId (string), totalAmountCents (integer), lineItems (array)
Retry policy: exponential backoff, max 5 attempts, base delay 2 s
Dead-letter queue: orders.created.dlq — routed after 5 failed attempts

With this document in the repo, a new consumer service can onboard without a synchronous meeting — every assumption is written down.

Why the dead-letter queue matters

A dead-letter queue is not a graveyard; it is the mechanism by which a bad message stops blocking the healthy ones. Without it a poison message either loops forever, blocking the consumer, or gets silently dropped, hiding a data-loss bug. Routing failures there instead keeps the main queue flowing and lets engineers inspect, correct, and replay the failed message at any time.

Tips and notes

Name topics for the event that happened, in the past tense (orders.created, payment.failed). Consumers subscribe to facts, not commands.
State delivery semantics explicitly. Most brokers give at-least-once, which means consumers must be idempotent — process the same message twice without side effects.
Size the dead-letter queue’s alerting, not just its existence: a message landing there is an incident signal, not a place data goes to be forgotten.
Version the payload (schemaVersion field or a topic suffix) so you can evolve the schema without breaking older consumers.
Keep producer and consumer lists current. An undocumented consumer is invisible to everyone else, which is exactly the kind of implicit dependency that causes outages when the schema changes.
For Kafka, use a topic suffix like .v2 when the schema changes in a breaking way. For SQS/RabbitMQ, a dead-letter configuration is a first-class setting, so include the actual queue ARN or exchange name in the spec.