Error Essence — Versioning and Pinning

A consumer of this format is usually a prompt. Prompts fail silently: change a field name under one and it does not throw, it just gets worse at its job, in a way nobody notices until a customer does. That is the whole reason this format is versioned and the version is mandatory rather than optional.

The version is in the document

{ "schemaVersion": "1.0.0", "...": "..." }

schemaVersion is const in the schema. A consumer can assert on it, and a producer that changes shape without changing it has broken the contract, not evolved it.

Semantics

Semver, with the classifications spelled out — the arguments are always at the edges.

Patch — 1.0.0 → 1.0.1

Documents are byte-identical. Only prose, examples, and clarifications that do not change what a producer emits or a consumer may assume.

• fixing a typo in this specification
• adding a worked example
• clarifying wording that two implementers read differently — provided both readings produced the same document

Minor — 1.0.0 → 1.1.0

Additive. A 1.0.x consumer keeps working unchanged.

• a new optional field
• a new member in an enum documented as extensible: hydration[].tool, breadcrumbs[].kind, changeCorrelations[].kind
• a new hydration handle
• relaxing a constraint (a maxLength raised, a required field made optional — see the caveat below)

Consumers MUST ignore unknown enum members gracefully rather than failing. A consumer that hard-fails on an unrecognised breadcrumb kind has opted out of minor upgrades.

The caveat on relaxing. Making a required field optional is additive for a producer and breaking for a consumer that dereferences it. In this format that counts as major. The rule of thumb: if any correct 1.0.0 consumer could crash or silently mis-handle a valid 1.1.0 document, it is not minor.

Major — 1.0.0 → 2.0.0

Everything else:

• removing or renaming a field
• making an optional field required, or a required field optional
• narrowing a type (string → enum, widening null out of a union)
• changing the meaning of an existing value
• changing the token budget in either direction — the budget is the contract, and a consumer sizing its context window around 500 tokens is broken by 800 just as surely as by 300
• changing the trust-label vocabulary or the obligations attached to a label
• changing the reduction ladder's guarantees (e.g. no longer maintaining hiddenFrameCount)

What a producer owes

1. Serve at least the two most recent majors. A customer's prompt library does not migrate on your release schedule.
2. Let a caller request a version explicitly — a header, a query parameter, a tool argument. The mechanism is unspecified; the capability is not.
3. Reject an unknown version. A request for 9.9.9 is an error, never a silent fallback to the newest. Silent fallback is how a pinned consumer discovers a major upgrade in production.
4. Announce a deprecation before it lands, with a date and a migration note.
5. Never change a published version in place. 1.0.0 means one thing forever. This is why the schema generator is covered by a drift test: a "small fix" to the zod schema silently republishes 1.0.0 as something else, and the test is what stops it.

What a consumer owes

1. Pin. Ask for the version your prompts were written against.
2. Assert schemaVersion on receipt. It costs one comparison and turns a silent degradation into a loud failure.
3. Ignore unknown fields. Additive minors are the mechanism the format evolves by; a strict-mode parser opts out of it.
4. Ignore unknown enum members gracefully — treat an unrecognised breadcrumbs[].kind as opaque rather than dropping the breadcrumb.
5. Do not infer from field order. JSON objects are unordered; the generator's key order is stable for diff readability, not for parsing.

URL pinning

The canonical $id carries the version:

https://spec.bucker.io/error-essence/1.0.0/schema.json

That URL is immutable. A newer schema gets a new URL; it never replaces an old one.

History

Status of each version

2.0.0 is not the default. Promoting a default across a major breaks every consumer who had not pinned yet, in the silent way this document opens by describing. 1.0.0 remains the default until its deprecation is announced here with a date.