Skip to content
Ratify Protocol v2 beta is available and is the recommended starting point for new integrations. Read the v2 documentation.

Versioning

The Ratify Protocol uses semantic versioning with one important twist: the version applies to all five 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.21 and Python on v1.0.0-alpha.5 and expect interop.

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, and v2 verifiers reject v1 objects with no fallback. Protocol v2 is a separate line; see Is v2 compatible with v1?.

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

1.0.0-alpha.21
│ │ │ │ │
│ │ │ │ └── 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.

This ladder is the plan for the v1 line. Protocol v2 has its own prerelease series, now at 2.0.0-beta.1, with its own gates for 2.0.0; see Is v2 compatible with v1?.

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
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 → Protocol v2, a separate line ← fixtures: testvectors/v2/
(now in beta; v1 fixtures unchanged)

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

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

v1.0.0-alpha.21 ← protocol-level tag (what Go modules consume)
sdk-go-v1.0.0-alpha.21 ← Go SDK marker
sdk-typescript-v1.0.0-alpha.21 ← TypeScript SDK marker
sdk-python-v1.0.0-alpha.21 ← Python SDK marker
sdk-rust-v1.0.0-alpha.21 ← Rust SDK marker
sdk-c-v1.0.0-alpha.21 ← C / C++ 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.

Use case Recommended pin
Alpha consumer Exact version (==1.0.0a21, @v1.0.0-alpha.21)
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 upgrade guide

The 79 fixtures in testvectors/v1/ are the canonical conformance set for v1. Any implementation passing all 79 is byte-for-byte interoperable with every other implementation at that version. If a minor release adds an 80th fixture, every v1 SDK must pass it. Protocol v2 has its own corpus in testvectors/v2/; v1 SDKs keep running testvectors/v1/, and the two are never mixed.