Skip to main content
The versioning scheme describes how we assign and increment version numbers. It clarifies the meaning of major, minor, and patch releases, how we handle breaking changes, and the role of pre-release tags.

​
Semantic versioning

We follow a modified semantic versioning scheme in the format X.Y.Z [-designation], where:

​
Breaking changes

A breaking change happens when an update alters or removes behavior in a way that is not fully compatible with previous versions. To keep this process predictable, we follow strict rules and communicate early.
  • We introduce breaking changes only in a major version.
  • They are announced in advance, always with migration guides and examples.
  • Deprecated features emit warnings before removal, so teams have time to adjust.
  • We aim to minimize disruption by grouping breaking changes together and providing alternative solutions whenever possible.

​
Examples

  • Field replacement: routeId (UUID) superseded the free-text route field in transaction payloads. The route field remains accepted for backward compatibility but no longer drives validation.
  • Validation rules: The Ledger Settings API replaced the ACCOUNT_TYPE_VALIDATION and TRANSACTION_ROUTE_VALIDATION environment variables. The API controls accounting validation per ledger without redeployment.
  • Deprecation cycle: We removed the scale field from transaction amounts in v3, when amount handling moved to a numeric system.

​
Pre-release designations

We use the following pre-release designations when applicable:

​
Examples

Potential releases
  • 1.0.0 → Initial stable release
  • 1.0.1 → Patch with bug fixes
  • 1.1.0-alpha.1 → Alpha for next minor
  • 1.1.0-beta.1 → Beta for next minor
  • 1.1.0-rc.1 → Release candidate
  • 1.1.0 → Stable minor release
  • 1.2.0 → Next minor release
  • 2.0.0 → New major version