Skip to content
Software Architecture Guide

Format Indicator

Explanation

Section titled “Explanation”

Senders and receivers must agree on how data looks. The Format Indicator pattern asks how a message’s data format can be designed so it can accommodate future changes. The approach is to mark each message with its format.

The alternative: one channel per type. A Datatype Channel (see the article of that name) gives each data type its own channel. Receivers infer the type from the channel they read. Both patterns address the same problem: the receiver must know how to process the data it gets. Datatype Channel lists Format Indicator as a related pattern.

Reading the tag. A Content-Based Router (see Content-based Router) inspects message content and sends each message to the right recipient. With a format tag, the router reads the tag and forwards the message to a recipient that understands that format.

Unknown formats. Some messages make no sense to a receiver. These go to an Invalid Message Channel (see Invalid Message Channel). That channel is the place for messages whose format nobody recognizes.

Where to put the tag: a Kafka case. In Kafka, a schema ID has traditionally acted as the format identifier. It is a number placed as a prefix in the payload. This ties consumers to the wire format. Older consumers that do not expect the extra bytes can break.

The alternative is to carry the schema ID in Kafka headers. The payload stays unchanged. Producers and consumers no longer need to upgrade in lockstep, so the system evolves more easily.

Example

Section titled “Example”

An order system sends order messages. Version 1 of the format has no discount field. Version 2 adds one. Each message carries a tag such as “order, v1” or “order, v2”. A router reads the tag. It sends v1 messages to the receivers that understand v1 and v2 messages to those that understand v2. A message with a tag nobody knows goes to an invalid message channel.

Trade-offs

Section titled “Trade-offs”

Where the tag lives matters. A tag inside the payload couples consumers to the wire format and can break older consumers. A tag in headers leaves the payload unchanged and avoids lockstep upgrades. Compared with one channel per type, a tag means the receiver side needs a router and a plan for unknown formats.

A router reads the format tag and sends each message to the matching receiver.

Diagram source 
flowchart LR
  P[Producer] -->|message + format tag| C[Single channel]
  C --> R[Router reads tag]
  R -->|v1| A[Receiver for v1]
  R -->|v2| B[Receiver for v2]
  R -->|unknown| X[Invalid message channel]

Checks

Section titled “Checks”
  • The document states where the format identifier is carried (for example, payload prefix or header) and why.
  • A router or other mechanism that reads the format identifier and sends messages to the right recipient is described.
  • Messages with unknown or unprocessable formats have a defined destination, such as an invalid message channel.
  • The choice between a format indicator and one channel per data type is explained.
Section titled “Related”

Sources

Section titled “Sources”