Versioning & Compatibility
EventConductor follows Semantic Versioning. From 1.0.0 onward, the guarantees below define what “a breaking change” means for this project — a MAJOR bump — so you can upgrade a PATCH or MINOR release without changing your definitions, configuration or workers.
This page is deliberately explicit about what is covered and what is not. A stability promise is only useful if its boundary is clear.
What is stable (the public contract)
Section titled “What is stable (the public contract)”These are covered by SemVer. A backward-incompatible change to any of them is a MAJOR release.
- The workflow, rule and form definition formats — the JSON/YAML (
*.ec.yaml,.ec) documents you author, as described by the published JSON Schemas. This is the primary contract: it is both the design an analyst reads and the artifact the engine runs. Each format carries a versioned schema$id(urn:eventconductor:workflow-definition-schema:1,…:rule-schema:1,…:form-schema:1) — see Format versioning below. - Configuration properties — the documented
workflow.*,forms.*andrules.*properties on the Configuration page. Documented defaults will not change under a MINOR/PATCH in a way that changes runtime behaviour. - The worker integration contract — how a worker receives a task and reports its result: the
task/reply protocol and, in
kafkamode, the Kafka topics and message envelopes on them. - The embedded entry points — the documented
@WorkflowEmbeddedApplicationannotation and the published integration ports (e.g. theEmbeddedTaskExecutorcallback), as described on the Java API page. - The HTTP message API (
POST /workflow/api/messages) and the MCP tool surface. - Metric names — the
eventconductor.*meters on the Observability page. New meters may be added under a MINOR; existing names/meanings are stable. - Process and step statuses — the status values on the Statuses page. New statuses may be added under a MINOR (treat unknown statuses defensively); existing ones do not change meaning.
What is NOT stable (implementation details)
Section titled “What is NOT stable (implementation details)”These are not part of the public API. They can change in any release, including PATCH. Do not build against them:
- The Java model classes as imported types.
WorkflowDefinition,Stepand the otherio.mateu.workflow.domain.*/dtos.*records are internal. They carry UI-framework annotations and helper wiring, and their shape follows the engine’s needs, not a published contract. Program against the JSON/YAML definition format, not against these Java types. If you construct definitions in code today, treat that as coupling to an internal detail. - Everything under
io.mateu.workflow.infra.*,application.*anddomain.*— use cases, handlers, repositories, services, aggregates. These are wiring, not API. In particular, the callback the embeddedEmbeddedTaskExecutordocumentation mentions is reached through the published port, not by importing internal use-case classes directly. - The database schema. Tables, columns and indexes are managed by Flyway and evolve with the engine. Read process state through the engine (its UI, MCP tools or HTTP API), not by querying the tables. Flyway migrations are forward-only and additive within a MAJOR line (see below).
- Wire formats on internal topics beyond the documented worker envelopes, and the exact text of log messages.
Format versioning
Section titled “Format versioning”Each definition format has a version, carried in its schema $id (the :1 suffix). Version 1
is the 1.0 format.
- Additive, backward-compatible changes stay v1. New optional fields may be introduced under a MINOR release; a document that does not use them keeps validating, and an older engine ignores fields it does not know only where a format explicitly allows it.
- A backward-incompatible format change bumps the schema version (
…-schema:2) and ships with a migration note. The engine will state which format versions it accepts. - The document-level
versionfield on aWorkflowDefinitionis unrelated to the format version: it is the engine-assigned instance revision counter for a stored definition, not the schema version.
Task contracts
Section titled “Task contracts”A task contract (.ectask, schema
urn:eventconductor:task-contract-schema:1) is the shape an ACTION step commits to. Unlike a
workflow, a form or a rule — each stored as a single current definition — contracts are versioned
and append-only: the store keeps every id@version it has imported, and nothing prunes them,
because an in-flight process may still be running against one.
- A step references a contract by
task: <id>ortask: <id>@<version>. When the definition is imported, a bare id is pinned to the latest known version and an explicit version is left as written, so what a definition dispatches is fixed at import and never shifts underneath a running process. That pinned<id>@<version>is what travels to the worker as the task’staskId. - A backward-incompatible change to a contract is a new
version— a removed or renamed field, a tightened type, a movedgroup. The old version keeps being served for the processes and definitions pinned to it; new definitions pick up the new one on their next import. A service may implement several versions at once. - An
idbelongs to exactly onegroup(one generated worker module), for its whole life; moving it to another group is a breaking change, not a new version. The build-timevalidateTasksgoal enforces this, the uniqueness of eachid@version, and that every referenced contract exists. - Removing a
.ectaskfile from its source does not delete the contract: a version a process is pinned to must remain resolvable. Retiring a version is therefore a deliberate operation, not a side effect of deleting a file.
Database upgrades
Section titled “Database upgrades”The engine ships its schema and applies it itself. The migrations live in the engine jar, and
the engine runs them at startup against whatever data source it has — embedded exactly as in the
standalone apps. It records its history in a table of its own (eventconductor_schema_history) and
never writes to flyway_schema_history, so your application’s own migrations and the engine’s stay
independent in the same database. workflow.schema.enabled=false opts out; see
Configuration.
Within a MAJOR line the migrations are forward-only and additive — a newer engine upgrades an older schema in place with no manual step, and no migration drops or rewrites existing data. Always take a backup before a MAJOR upgrade. Run one engine version at a time through the migration; skipping intermediate MAJORs is not supported unless a release note says otherwise.
A MINOR upgrade can be rolled — old and new pods side by side on one database — unless its release
note says otherwise: its migrations keep every column and constraint the previous MINOR reads. 2.33’s,
for instance, keeps process_entity.business_key UNIQUE and builds its new indexes CONCURRENTLY on
PostgreSQL; see Long-running processes.
The migration files themselves are not part of the public contract: their names, numbering and contents are implementation detail, like the schema they build. What is stable is that upgrading the engine upgrades the schema for you.
Deprecation policy
Section titled “Deprecation policy”Something on its way out is marked @Deprecated in the Java surface (where it applies) and called
out in the changelog
and the relevant reference page, with the replacement named. A deprecated part of the public
contract keeps working for at least one MINOR release before it can be removed in a MAJOR. Legacy
aliases already in place (for example the MESSAGE → WAIT_FOR_MESSAGE step-type name) are honored
under this policy.
Pre-1.0 releases
Section titled “Pre-1.0 releases”1.0-beta.* releases predate these guarantees and did not promise compatibility between betas. The
guarantees on this page begin at 1.0.0.