Skip to content

Codec Specification

Normative specification document — instantiates Round-Trip Code Alignment

The written contract that pins the encoder, decoder, permitted code states, invariants, and error behavior in one normative document, so any implementation on either side of the round trip agrees on what the code means.

Most decode failures trace back to one root cause: the receiver guessed the scheme the sender used. Codec Specification removes the guessing by making the scheme explicit and authoritative — the single source of truth, in words, that every encoder and decoder is written against. It is not code and not tests; it is the normative definition those artifacts derive from. It states what a conforming encoder must produce, what a conforming decoder must accept and reject, which code states are permitted, which invariants must hold across the round trip, and how the two sides must behave at the seams. Because both directions are pinned to one document, independent implementations agree by construction rather than by luck — and stay aligned as teams and years turn over.

Example

A payments platform has a Go service that emits an event envelope and a Python service that consumes it. With no shared document, each team encodes its own assumptions, and the round trip breaks at the seams — the emitter treats a field as optional while the consumer treats it as required, and messages start failing in production. The teams write a codec specification: the exact field layout and types, which fields are required versus optional, ordering rules, the invariants a valid envelope must satisfy, how a decoder must treat an unknown field, a reference to the version-compatibility rule, and a "how to read this" section with worked examples. Written in normative RFC 2119 language — MUST, SHOULD, MAY — the document lets both implementations, and any future third, conform to one contract. Interoperability becomes a property of the design instead of an accident of two codebases.

How it works

  • Normative, not descriptive. It states what conforming implementations MUST and SHOULD do rather than reporting what one implementation happens to do, so conformance is a checkable claim.
  • Both directions and the seams. It pins encoder duties, decoder duties, permitted code states, the invariants that must survive the round trip, and required behavior on malformed or unknown input — not just the happy path.
  • A human-readable key. It carries worked examples and reading guidance so a person, not only a parser, can recover meaning from an encoded artifact.

Tuning parameters

  • Normative precision — how much is fixed as MUST versus left to the implementer. Tighter wording buys interoperability; looser wording buys flexibility and invites drift.
  • Scope of the contract — how much of source content, encoded form, versioning, and error behavior this document pins directly versus delegates to companion mechanisms.
  • Extensibility rules — how unknown or future fields must be handled (ignore-unknown, reserved ranges). This is the dial that makes forward compatibility possible or impossible.
  • Human versus machine emphasis — how much prose and worked example for people versus formal schema for tooling.

When it helps, and when it misleads

Its strength is eliminating the "receiver guessed the scheme" failure at the root: it is the single source of truth from which code generators, parsers, test suites, and human reviewers all derive, and the anchor that holds a format steady across teams and years.

Its failure mode is that a specification is only as live as its enforcement. An unversioned or unenforced spec silently diverges from what the code actually does, and then the document lies while the code rules — the worst of both worlds, because people trust the document. Ambiguity does slower damage: a SHOULD where the interoperation needed a MUST breeds subtle cross-implementation bugs. The classic misuse is writing the spec after the implementation and treating whatever the code emits as the contract, which produces documentation, not specification.[1] The discipline is to version the spec, bind it to conformance vectors, and change code and specification in the same commit so the two can never drift apart.

How it implements the components

Codec Specification realizes the definitional side of the archetype — the normative components the running machinery is built to satisfy:

  • shared_scheme_contract — it is the shared scheme contract, written down and made authoritative for both encoder and decoder.
  • source_content_specification — it defines what valid source content is and which of its distinctions must survive the round trip.
  • human_interpretation_guide — its reading key and worked examples let a human recover meaning from an encoded artifact, not just a machine.

It does not implement the running encoder and decoder it defines (that is the Parser/Emitter Pair), does not pin the concrete reference outputs that witness it (that is Golden Test Vectors), and does not run the version negotiation it specifies (that is Version Negotiation Handshake).

  • Instantiates: Round-Trip Code Alignment — supplies the normative contract every other mechanism derives from.
  • Sibling mechanisms: Golden Test Vectors · Canonicalization Rule · Round-Trip Property Test · Decode Error Taxonomy · Parser/Emitter Pair · Checksum or Hash Validation · Compatibility Matrix · Schema Registry · Lossy Compression Profile · Migration Adapter · Version Negotiation Handshake

References

[1] RFC 2119 fixes the normative meaning of keywords such as MUST, SHOULD, and MAY in specifications. Writing a codec contract in those terms is what makes "conforming implementation" a testable claim rather than a matter of interpretation. ↩