Is v2 compatible with v1?
No. Protocol v2 deliberately does not preserve v1 signature bytes, key identifiers, challenge rules, or acceptance behavior. A v1 proof is not a v2 proof, and a v2 verifier rejects v1 objects without falling back (SPEC-v2 §1.1).
- v1 and v2 objects are never mixed in a chain, bundle, status feed, receipt chain, or API call.
- Every API boundary selects exactly one version.
- A v1 verifier keeps implementing the immutable v1 contract in
SPEC.md.
Side by side
Section titled “Side by side”Released v1 tags and package artifacts are immutable. Applications that pin v1 keep the v1 contract, and v2 never widens a v1 dependency range. Each ecosystem gives v2 its own import path:
| SDK | v1 | v2 |
|---|---|---|
| Go | github.com/identities-ai/ratify-protocol |
github.com/identities-ai/ratify-protocol/v2 (major-version module path) |
| TypeScript | @identities-ai/ratify-protocol 1.x |
@identities-ai/ratify-protocol 2.x, imported from the /v2 subpath; npm dist-tag next |
| Python | ratify-protocol 1.x (import ratify_protocol) |
ratify-protocol 2.x with the protocol-v2 extra, imported as ratify_protocol.v2 |
| Rust | crate ratify-protocol 1.x |
crate ratify-protocol 2.x, ratify_protocol::v2 module |
| C | ratify-c v1 ABI |
ratify-c 2.x with a v2 ABI (ratify_v2_*) and an ABI version query |
v1 and v2 run side by side in one build or environment in every ecosystem. In Go the two lines
have different module paths, so one module can require both. In TypeScript, Python, Rust, and
C, the 2.x package keeps the v1 API at its root (the npm package root, ratify_protocol, the
crate root, the ratify_* ABI) and adds v2 at its own import path, so upgrading the package
does not remove v1 verification. In Python, import ratify_protocol never loads v2.
Two notes apply to the v1 API inside the 2.x packages:
- Rust: the fields of the root
HybridPrivateKeyare private. Build a key withHybridPrivateKey::from_components(ed25519, ml_dsa_65)and read it with.ed25519()and.ml_dsa_65(). Both buffers are wiped on drop. This is the only source change to a v1 API. Every published crate is a prerelease, so an unpinnedcargo add ratify-protocolresolves to the 2.x beta; to add v1, pinratify-protocol = "=1.0.0-alpha.21". - Python: every published
ratify-protocolversion is a prerelease, so an unpinned install or upgrade resolves to the 2.x beta. The v1 API and requirements are unchanged in it, but to stay on the v1 release line, pinratify-protocol<2.
Exact install lines are on each SDK reference page.
Migration is re-enrollment
Section titled “Migration is re-enrollment”There is no cryptographic continuity from v1 to v2:
- Establish the person or organization identity out of band.
- Generate fresh v2 keys. Importing a v1 key into a v2 identity is prohibited, and no v1 key may authorize a v2 key.
- Configure trust anchors as complete v2 public keys, not key IDs.
- Issue new v2 delegations.
Installing v2 does not migrate keys, delegations, trust anchors, revocation state, or application policy. A v2 key proves possession, not an organization’s identity.
The step-by-step path is in Upgrade from v1.
How long v1 stays available
Section titled “How long v1 stays available”v1 remains available and pinned. Support terms for v1 will be announced with 2.0.0. Some capabilities are still v1-only; see v1-only until 2.1.
