---
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-06-07T00: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**. 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](/docs/spec/1.x/envelope/).