Docs Public Knowledgebase Releases Versioning Policy

Overview

The platform uses four independent but coordinated versioning surfaces. Understanding how these versions relate to each other is essential for performing safe upgrades and reasoning about system behavior. Each versioning scheme addresses a different component of the platform, from the core product binaries to the individual API contracts served to consumers.

This decoupled approach allows API publishers to upgrade the underlying platform without being forced to redeploy every service, and conversely, to update a single service's API contract without requiring a full platform upgrade.

The four versioning surfaces are:

1. Product Version: The overall platform release.
2. Database Schema Version: The state of the backing PostgreSQL database schema.
3. Per-Service Mapping Version: The version of an individual SOAP-to-REST mapping.
4. Generated Contract Version: The version of the OpenAPI or WSDL artifact produced for API consumers.

How the Versions Relate

The product release is the top-level container that pins specific versions of its dependencies and provides the runtime for service mappings. The versions are hierarchical but decoupled to provide operational flexibility.

The following diagram illustrates the relationship between the versioning surfaces:

flowchart TD
    A["Product Release (vMAJOR.MINOR)"]
    A -- "pins" --> B["Database Schema Version"];
    A -- "contains" --> C["Platform Component Images"];
    C -- "serve" --> D["Per-Service Mapping Versions"];
    D -- "generates" --> E["Generated API Contract (OpenAPI/WSDL)"];

Versioning Surfaces

1. Product Version

The product version identifies a specific release of the entire platform, including the container images for all services (control plane, runtime, worker), the documentation set, and associated deployment artifacts.

• Format: The version follows a vMAJOR.MINOR pattern, with vMAJOR.MINOR.PATCH used for bug-fix releases.
  • MAJOR: Indicates a significant shift in capabilities or a breaking change to a public API or license contract.
  • MINOR: Adds new functionality in a backward-compatible manner.
  • PATCH: Contains only backward-compatible bug fixes.
• Build Provenance: Each running deployment is stamped with deploy-provenance metadata, which includes the commit SHA, branch, build timestamp, and image tag. This information is emitted in a startup log line, allowing an operator to confirm the exact build in use.

Release notes are published for each product version.

2. Database Schema Version

The platform's PostgreSQL database schema is versioned and managed using Flyway migrations. These migrations are applied automatically when platform services start.

• Immutability: Migrations are forward-only. A shipped migration script, named V<n>__description.sql, is never edited. Any necessary corrections are handled by a new, subsequent migration script.
• Startup Validation: On startup, services verify that the connected database schema is at, or compatible with, the version required by the product release. The service will not serve traffic if the validation fails.
• Upgrade Performance: To prevent long upgrade-related downtime, migrations that involve building indexes on large tables are handled out-of-band.

API publishers do not manage schema migrations manually; they are bundled with each product release.

3. Per-Service Mapping Version

Each service's SOAP-to-REST mapping is independently versioned. This is the version most relevant to the day-to-day operations of an API publisher.

• Immutability: Every change to a service's mapping or its generated contract creates a new, immutable version. Existing versions are never modified.
• Activation and Rollback: At any given time, only one mapping version for a service is active. An API publisher can activate any existing version to make it live or roll back to a previous version. This change takes effect instantly.
• Deterministic Regeneration: Each mapping version records a parser version and a content checksum. This ensures that regenerating a contract from a mapping is a deterministic process. It also means that changes to a backend WSDL are surfaced as a clear diff instead of a silent, unexpected change.

This immutability guarantees that API consumers are never subjected to a silent contract change, as every update requires the deliberate activation of a new version.

4. Generated Contract Version

The API contracts provided to consumers—an OpenAPI v3 document for published REST APIs or a WSDL for consumed SOAP services—are generated from the active per-service mapping version.

Because regeneration is deterministic for any given mapping version, you can reliably reproduce a contract. When planning a breaking change for API consumers, the recommended practice is to create and activate a new service mapping version rather than modifying the live contract. If you version your public API paths, you can expose this new mapping version under a new path (e.g., /v2/myservice).

License Compatibility

The license contract is tied to the MAJOR line of the product version. A product upgrade that changes the MAJOR version (e.g., from v1.x to v2.0) may require a new license file that corresponds to the new license-format version.

Any upgrade that requires a license change will be explicitly noted in the corresponding product release notes.

Troubleshooting

• Service Fails to Start After Upgrade: If a service fails to start and serve traffic after a product upgrade, check its logs. It may be due to a database schema version mismatch. The service validates the schema on startup and will refuse to run if the schema is not compatible with the version it expects.
• Upgrade Stalls: The platform is designed to avoid upgrade stalls caused by long-running database migrations. Index builds on large tables are performed out-of-band to prevent blocking the main upgrade process.

See Also

• Release Notes
• Upgrade Guide
• Publish & Version a Service
• License Model

All SOAP-to-REST docs