SPECIFICATION · COMPATIBILITY

Protocol Compatibility Guarantees

What the AxIA Protocol promises will not change inside a profile, what may change additively, and how breaking changes are versioned.

1. Scope

This document specifies which parts of the Axia public surface are frozen (any change requires a new profile version) and which parts may evolve additively without breaking conforming implementations such as @axia/receipt-verify.

Profiles currently covered: axia.receipt.v1, axia.key.v1, axia.key-chain.v1, axia.inclusion-proof.v1, axia.witnesses.v1.

2. Frozen surfaces

2.1 axia.receipt.v1

The following MUST NOT change without bumping to axia.receipt.v2:

• Canonical payload field order and pipe (|) delimiter.
• Encoding rules (lowercase hex, RFC 3339 UTC with Z + ms precision, empty string for null checkpoint_root).
• Signature scope: Ed25519 over the raw 32-byte SHA-256 of the canonical payload, and nothing else.
• Lifecycle enum values and their semantic meaning (active, rotated, revoked, anonymous, unknown).
• Algorithm identifier strings (ed25519).

2.2 Conformance vectors

The published conformance vectors under /protocol/test-vectors/receipt-v1/ MUST continue to verify successfully (or fail with the same documented reason) across all future implementations claiming axia.receipt.v1 support.

3. Additive evolution (allowed within v1)

• Adding new optional JSON fields to receipt or response documents that do not participate in the canonical payload.
• Adding new endpoints (/key-chain, /witnesses, etc.) under new paths.
• Adding new witness kinds in external_witnesses.kind while keeping existing kinds backwards-compatible.
• Adding new confidence bands as long as none of the existing bands change meaning.
• Tightening server-side validation when it would have rejected previously-undefined behavior.
• Publishing new profiles (axia.key.v1, axia.inclusion-proof.v1, …) on new endpoints.

Implementations MUST ignore unknown JSON fields (Postel's principle) so additive changes never break conforming verifiers.

4. Disallowed without major version bump

• Reordering canonical payload segments.
• Changing the empty-segment convention for nullable fields.
• Changing the hash, signature, or encoding algorithm.
• Changing what the signature commits to.
• Reusing an existing lifecycle enum value with new semantics.
• Removing or renaming any field present in the v1 canonical payload.

Any change in this list MUST ship as axia.receipt.v2 (or the next-major profile for the affected surface) and MUST NOT reuse the v1 identifier on the wire.

5. Deprecation policy

When a profile is superseded:

• The successor profile is published alongside the predecessor.
• Both profiles are listed under supported_profiles in /protocol/versions.json for at least 180 days.
• The deprecated profile is then moved to deprecated_profiles.
• Verifiers MUST continue to validate historical receipts using the deprecated profile indefinitely; only new emissions stop.

6. Where to look

• /protocol/versions.json — current supported / deprecated profile list.
• /specs/changelog — protocol changelog (additive, breaking, deprecation entries).
• /specs/receipt-v1 — frozen receipt spec.