---
title: "Wire Contract"
description: "The frozen, language-neutral contract every BabelQueue SDK speaks — the envelope, the URN identity, and the rules that keep all six languages byte-compatible."
source: https://babelqueue.com/docs/spec/1.x/introduction/
updated: 2026-10-01T00:00:00.000Z
---

# 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](/docs/spec/1.x/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](/docs/spec/1.x/urn/)** — 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](/docs/spec/1.x/envelope/).