Versioning Policy

SOAP-2-REST by Specaria has four independent but coordinated versioning surfaces. Understanding them is the key to upgrading safely and to reasoning about what…

SOAP-2-REST by Specaria has four independent but coordinated versioning surfaces. Understanding them is the key to upgrading safely and to reasoning about what "a version" means in different contexts.

1. Product version (release version)

The headline version — v1.0, v1.1, v2.0 — identifies a release of the whole platform: the container images for the control plane, runtime, and worker, plus the documentation set, deployment artifacts, and the license contract they expect.

Format: vMAJOR.MINOR (with patch releases vMAJOR.MINOR.PATCH when needed).
MAJOR changes signal a significant capability or contract shift (for example, a license contract change, or a breaking change to a public API).
MINOR changes add capability in a backward-compatible way.
PATCH changes are fixes only.
The running product stamps its build into each deployment via deploy-provenance metadata (commit SHA, branch, build timestamp, image tag), and emits it in a startup log line, so an operator can always confirm exactly which build is running.

Release notes are published per product version under Releases.

2. Database schema version (migrations)

The PostgreSQL schema is managed by Flyway migrations applied automatically on startup. Each migration is a numbered, immutable script (V<n>__description.sql). The schema version advances independently of the product version, but every product release pins a known-good schema version.

Migrations are forward-only and immutable — a shipped migration is never edited; a fix is always a new migration that supersedes it.
On startup the services validate that the schema is at (or compatible with) the expected version before serving traffic.
Large-table index builds are handled out-of-band so an upgrade never stalls on a long migration.

You don't manage migrations by hand — they ship with the release. The upgrade guide describes the operational sequence.

3. Per-service mapping version (immutable, with rollback)

Each converted service's SOAP↔REST mapping is itself versioned. This is the version most relevant to day-to-day operation:

Every change to a service's mapping (or its generated contract) produces a new, immutable version — existing versions are never mutated.
Exactly one version is active at a time; you activate a version to make it live and can roll back to any previous version instantly.
Because versions are immutable, your REST/SOAP consumers never experience a silent contract change — a change is always a new version you deliberately activate.
Each contract snapshot records a parser version and a checksum, so regeneration is deterministic and a backend WSDL change surfaces as a diff rather than a surprise.

See Publish & version a service.

4. Generated-contract versions (OpenAPI / WSDL)

The artifact you hand to consumers — an OpenAPI v3 document (Publish direction) or a WSDL (Consume direction) — is generated from the active mapping version. Regenerating is deterministic for a given mapping version. When you intend a breaking change for consumers, publish it as a new service mapping version (and, where you version your public API path, expose it under a new path) rather than mutating the live contract.

How they relate

Product release (v1.0)
   ├─ pins → Database schema version (Flyway V<n>)
   ├─ runs → Runtime/Admin/Worker images (deploy-provenance stamped)
   └─ serves → Per-service mapping versions (you activate/roll back)
                  └─ generate → OpenAPI v3 / WSDL contract artifacts

Upgrading the product may advance the schema version; it does not change your active mapping versions.
Activating a new mapping version changes one service's behavior; it does not touch the product or schema version.
The two are deliberately decoupled so you can upgrade the platform without re-publishing every service, and re-publish a service without upgrading the platform.

License compatibility

The license contract is tied to the product MAJOR line. A product MAJOR upgrade may require a license that declares the corresponding license-format version. The license model describes the contract; upgrades that change it are called out explicitly in the relevant release notes.

All Specaria SOAP to REST docs

Loading…