Versioning

The Ratify Protocol uses semantic versioning with one important twist: the version applies to all four SDKs as a single coordinated release. At any tagged version vX.Y.Z, every SDK produces and verifies byte-identical canonical JSON. You can’t have Go on v1.0.0-alpha.6 and Python on v1.0.0-alpha.5 and expect interop.

Two version concepts

Protocol version

The integer version field on every signed object. Currently 1. This changes only for wire-breaking changes:

New required field in DelegationCert or ProofBundle
Change to delegationSignBytes / challengeSignBytes algorithm
Change to verifier algorithm semantics
Change to a canonical scope’s meaning
Change to canonical JSON serialization rules

Protocol version bumps are rare and always trigger a major version bump in the SDKs. v1 SDKs cannot consume v2 bundles by default; v2 SDKs may accept v1 bundles during a documented migration window.

SDK version

Standard semver MAJOR.MINOR.PATCH[-pre]:

   1.0.0-alpha.6
   │ │ │  │     │
   │ │ │  │     └── pre-release identifier (alpha/beta/rc + counter)
   │ │ │  └──────── patch
   │ │ └─────────── minor
   │ └───────────── major
   └─────────────── protocol version (matches `version` field)

Bump	Triggers	Fixture-byte change?
Patch (`1.0.0` → `1.0.1`)	Bug fixes, performance improvements, doc updates	No
Minor (`1.0.x` → `1.1.0`)	New optional fields, new scopes, new helper functions	No — every v1.0 fixture must still pass byte-identically
Major (`1.x.x` → `2.0.0`)	Protocol-version bump. Wire-breaking.	Yes — new `testvectors/v2/` ships alongside v1
Pre-release (`-alpha.x`, `-beta.x`, `-rc.x`)	Active development before a stable major	Maybe — alpha can change fixtures. Beta/rc cannot.

The alpha → stable ladder

   1.0.0-alpha.1   →  initial drop                          ← fixtures: MAY change
                      hybrid Ed25519 + ML-DSA-65 working
                      conformance suite established

   1.0.0-alpha.N   →  alpha series                          ← fixtures: MAY change
                      bug fixes, polish, design partner
                      feedback. Each alpha documented in
                      the GitHub Release notes if fixtures
                      change.

   1.0.0-beta.1    →  feature-complete, audit started       ← fixtures: FROZEN
                      no more fixture changes; only bugs
                      and security fixes.

   1.0.0-rc.N      →  release candidate                     ← fixtures: FROZEN
                      audit results integrated. Last
                      chance to find regressions.

   1.0.0           →  stable                                ← fixtures: FROZEN FOR v1
                      every external audit passed
                      first design-partner production
                      deployment is live
                      at least 3 SDKs published to
                      mainstream registries

   1.0.1, 1.0.2... →  patches                               ← fixtures: never change
   1.1.0, 1.2.0... →  minor — additive only                 ← fixtures: never change
                      (new fields are optional;
                      v1.0 fixtures still pass)

   2.0.0           →  major — wire-breaking                 ← fixtures: NEW SUITE
                      adds testvectors/v2/
                      v1 fixtures remain for migration

Where we are now: v1.0.0-alpha.6. Fixture bytes may still change between alphas. Consumers should pin to an exact alpha version (==1.0.0a6 in Python, @v1.0.0-alpha.6 in Go, etc.) rather than a range.

SDK version tags

Every SDK release is tagged in git as sdk-<language>-<version> alongside the protocol-level tag:

   v1.0.0-alpha.6                ← protocol-level tag (what Go modules consume)
   sdk-go-v1.0.0-alpha.6         ← Go SDK marker
   sdk-typescript-v1.0.0-alpha.6 ← TypeScript SDK marker
   sdk-python-v1.0.0-alpha.6     ← Python SDK marker
   sdk-rust-v1.0.0-alpha.6       ← Rust SDK marker

All five tags point at the same commit. The protocol-level v* tag is what go get consumes; the sdk-* tags are what the release workflow uses to decide which registries to push to.

Pinning recommendations

Use case	Recommended pin
Alpha consumer	Exact version (`==1.0.0a6`, `@v1.0.0-alpha.6`)
Beta consumer	Exact version, refresh on each beta release
RC consumer	Exact version
Stable (`1.x`) consumer	Caret/tilde range (`^1.0.0` in npm, `~=1.0` in Python). Minor bumps are additive only.
Major (`2.x`) migration	Explicit version bump; read the v2 migration guide

Conformance is the contract

The 59 fixtures in testvectors/v1/ are the canonical conformance set for v1. Any implementation passing all 59 is byte-for-byte interoperable with every other implementation at that version. If a minor release adds a 60th fixture, every v1 SDK must pass it. If a major v2 release ships, testvectors/v2/ replaces v1 for new code and v1 stays for backward-compatible migration paths.

Where to next

SDK packages — current versions per registry
Conformance suite — what the fixtures actually check
Specification — the normative protocol