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. Adding, renaming, removing or retyping a field is an architecturally significant change: it requires a deliberate decision and a bump of meta.schema_version. Additive, optional, backward-compatible fields keep the version at 1. 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.