Message shape

A message shape is the structure of a provider message: which fields it contains, where they sit and how they are nested, regardless of their values. Recognising the shape tells a normaliser which rule to apply. A shape never seen before signals that the provider has changed its format.

How it works

A message shape is read from the keys, not the values. Two illustrative callbacks from the same synthetic provider:

shape 1: { "status", "amount", "currency", "order_id" }
shape 2: { "payment": { "state", "sum", "cur" }, "ref" }

Both report a payment, but a rule written for shape 1 finds no status in shape 2. A reader that ignores shapes would see an empty status and move on. A reader that recognises shapes applies the right rule, or flags the new shape for a person.

Why it matters

Providers do not send one shape each. On one anonymised merchant day Reconora saw 1,198 distinct message forms across 96 providers, with up to 41 forms from a single provider. Callbacks, responses, polls and error replies each look different, and providers change them without notice.

How to spot it

Take one provider and list the field names in a sample of its callbacks. Group messages that share the same set of fields. If you find more groups than your integration expects, or a status field that is sometimes empty, the provider sends more shapes than you read.

Related terms

Normalisation · Canonical status · Callback · Quarantine · The normalizer

Try it on one day of your data

One day of your data, reconciled, and the report stays with you whether or not you continue.

Updated