Skip to content
Cyoda Documentation
Settings

workflows schema-version — wire-format contract for workflow import

cyoda-go version 0.8.2

workflows schema-version

Section titled “workflows schema-version”

NAME

Section titled “NAME”

workflows schema-version — semver MAJOR.MINOR contract identifying the workflow-import DTO shape that a workflow definition was authored against.

SYNOPSIS

Section titled “SYNOPSIS”

Every WorkflowConfigurationDto carries a version field. The server validates it strictly on import and stamps the current contract version on every workflow it exports.

{
  "version": "1.2",
  "name": "my-workflow",
  "initialState": "ready",
  "states": { "ready": {} }
}

SEMANTICS

Section titled “SEMANTICS”
  • MAJOR bumps when a payload valid under the previous MAJOR is no longer valid (or vice-versa) — removing a field, renaming, changing semantics, making an optional field required.
  • MINOR bumps for additive, backward-compatible changes — a new optional field, a new enum value in an existing string-enum, a new condition operator. This is the common case.

Multiple MAJORs may be accepted concurrently during a deprecation window. Within a MAJOR, the server accepts any MINOR in its declared [minMinor, maxMinor] range.

DISCOVERY

Section titled “DISCOVERY”

Authoritative discovery is via the versions action:

cyoda help workflows schema-version versions

HTTP mirror:

GET /help/workflows/schema-version/versions

Both emit the same structured JSON:

{
  "current": "1.2",
  "supported": [
    { "major": 1, "minMinor": 1, "maxMinor": 2 }
  ]
}

VALIDATION ERRORS

Section titled “VALIDATION ERRORS”

On import, an unsupported or malformed version returns HTTP 400 with errorCode: "WORKFLOW_SCHEMA_VERSION_UNSUPPORTED". The message body distinguishes:

  • Malformed ("x", "1", "1.0.0", leading zeros) — not in MAJOR.MINOR form.
  • Major unsupported — the major version is not in any supported range.
  • Minor too new — the major matches but the minor exceeds this server’s maxMinor. Upgrade cyoda-go, or regenerate the file against an older schema.
  • Minor too old — the major matches but the minor is below the server’s minMinor (deprecation window). Re-author the file against a supported MINOR.

EXAMPLE: PINNING

Section titled “EXAMPLE: PINNING”

Pin your authoring tools and CI to the schema version they were tested against:

Terminal window
# in a CI step
current=$(curl -s $CYODA_HOST/api/help/workflows/schema-version/versions | jq -r .current)
test "$current" = "1.2" || { echo "schema drift"; exit 1; }

See also

Section titled “See also”
  • cyoda help workflows — A workflow definition is a named finite state machine attached to an entity model. Workflows are stored per model reference (entityName, modelVersion). A model may have multiple workflow definitions; the engine selects the matching one per entity using the workflow-level criterion field evaluated at entity creation time. When no criterion matches, the engine uses the default built-in workflow.
  • cyoda help errors WORKFLOW_SCHEMA_VERSION_UNSUPPORTED — Every workflow definition must declare a schema version in MAJOR.MINOR format (for example "version": "1.1"). This error is returned when the import request contains a version string that does not match any supported schema version.
  • cyoda help openapi — cyoda-go generates its OpenAPI 3.1 specification from the embedded api/openapi.yaml file compiled into the binary at build time. The spec is served at /openapi.json with runtime-patched server URLs. The Scalar API Reference UI is served at /docs and loads the spec from /openapi.json.

Raw formats

Section titled “Raw formats”