Wire Contract

BabelQueue is, at its core, one contract: a strict, language-neutral definition of the bytes that travel on the queue. Every SDK — PHP, Python, Go, Node.js, Java and .NET — produces and consumes exactly this shape, so a message written in one language is read natively in another, over the broker you already run.

This section is the source of truth for that contract. If an SDK, an example, or a marketing page ever disagrees with these pages, the contract wins.

What the contract covers

• The envelope — the JSON document on the wire: job, trace_id, data, meta, attempts, plus the cross-language data rules (encoding, numbers, time) and the producer/consumer rules every SDK obeys.
• URN naming — how a message is identified by a stable urn:babel:<context>:<event> string instead of a class name, so any language can route on it.

The three things every message carries

1. Identity — what the message is: the job field, a URN, never a class name.
2. Correlation — how to trace it across services: a required trace_id.
3. Payload + bookkeeping — the business data, descriptive meta, and the transport attempts counter.

Frozen at schema_version: 1

The envelope is frozen: within schema_version: 1, the existing envelope fields, their types and their meanings do not change — no field is renamed, removed or retyped, and the required fields keep their meaning. A new field may be added only as an optional, ignorable field and only through an architecture decision record and an explicit version decision. A consumer that does not understand an unknown field MUST still process the message correctly and SHOULD preserve that field when it re-emits the message. Renaming, removing or retyping a field requires a bump of meta.schema_version. Consumers MUST reject or quarantine any schema_version they do not understand.

This stability is the whole point — a v1 producer stays readable by every v1 consumer, in any language, indefinitely.

Cross-SDK parity

Every SDK ships against a shared suite of golden envelope fixtures: two SDKs producing the same logical message emit byte-comparable envelopes (modulo the intrinsically per-message/per-language fields meta.id, trace_id, meta.lang and meta.created_at). Parity is enforced in every SDK’s CI, not just asserted here.

Continue to The envelope.