{
  "topic": "workflows.schema-version",
  "path": [
    "workflows",
    "schema-version"
  ],
  "title": "workflows schema-version — wire-format contract for workflow import",
  "synopsis": "workflows schema-version — semver `MAJOR.MINOR` contract identifying the workflow-import DTO shape that a workflow definition was authored against.",
  "body": "# workflows schema-version\n\n## NAME\n\nworkflows schema-version — semver `MAJOR.MINOR` contract identifying the workflow-import DTO shape that a workflow definition was authored against.\n\n## SYNOPSIS\n\nEvery `WorkflowConfigurationDto` carries a `version` field. The server validates it strictly on import and stamps the current contract version on every workflow it exports.\n\n```json\n{\n  \"version\": \"1.2\",\n  \"name\": \"my-workflow\",\n  \"initialState\": \"ready\",\n  \"states\": { \"ready\": {} }\n}\n```\n\n## SEMANTICS\n\n- **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.\n- **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.**\n\nMultiple MAJORs may be accepted concurrently during a deprecation window. Within a MAJOR, the server accepts any MINOR in its declared `[minMinor, maxMinor]` range.\n\n## DISCOVERY\n\nAuthoritative discovery is via the `versions` action:\n\n```\ncyoda help workflows schema-version versions\n```\n\nHTTP mirror:\n\n```\nGET /help/workflows/schema-version/versions\n```\n\nBoth emit the same structured JSON:\n\n```json\n{\n  \"current\": \"1.2\",\n  \"supported\": [\n    { \"major\": 1, \"minMinor\": 1, \"maxMinor\": 2 }\n  ]\n}\n```\n\n## VALIDATION ERRORS\n\nOn import, an unsupported or malformed `version` returns HTTP 400 with `errorCode: \"WORKFLOW_SCHEMA_VERSION_UNSUPPORTED\"`. The message body distinguishes:\n\n- **Malformed** (`\"x\"`, `\"1\"`, `\"1.0.0\"`, leading zeros) — not in `MAJOR.MINOR` form.\n- **Major unsupported** — the major version is not in any supported range.\n- **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.\n- **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.\n\n## EXAMPLE: PINNING\n\nPin your authoring tools and CI to the schema version they were tested against:\n\n```bash\n# in a CI step\ncurrent=$(curl -s $CYODA_HOST/api/help/workflows/schema-version/versions | jq -r .current)\ntest \"$current\" = \"1.2\" || { echo \"schema drift\"; exit 1; }\n```\n",
  "sections": [
    {
      "name": "NAME",
      "body": "workflows schema-version — semver `MAJOR.MINOR` contract identifying the workflow-import DTO shape that a workflow definition was authored against."
    },
    {
      "name": "SYNOPSIS",
      "body": "Every `WorkflowConfigurationDto` carries a `version` field. The server validates it strictly on import and stamps the current contract version on every workflow it exports.\n\n```json\n{\n  \"version\": \"1.2\",\n  \"name\": \"my-workflow\",\n  \"initialState\": \"ready\",\n  \"states\": { \"ready\": {} }\n}\n```"
    },
    {
      "name": "SEMANTICS",
      "body": "- **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.\n- **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.**\n\nMultiple MAJORs may be accepted concurrently during a deprecation window. Within a MAJOR, the server accepts any MINOR in its declared `[minMinor, maxMinor]` range."
    },
    {
      "name": "DISCOVERY",
      "body": "Authoritative discovery is via the `versions` action:\n\n```\ncyoda help workflows schema-version versions\n```\n\nHTTP mirror:\n\n```\nGET /help/workflows/schema-version/versions\n```\n\nBoth emit the same structured JSON:\n\n```json\n{\n  \"current\": \"1.2\",\n  \"supported\": [\n    { \"major\": 1, \"minMinor\": 1, \"maxMinor\": 2 }\n  ]\n}\n```"
    },
    {
      "name": "VALIDATION ERRORS",
      "body": "On import, an unsupported or malformed `version` returns HTTP 400 with `errorCode: \"WORKFLOW_SCHEMA_VERSION_UNSUPPORTED\"`. The message body distinguishes:\n\n- **Malformed** (`\"x\"`, `\"1\"`, `\"1.0.0\"`, leading zeros) — not in `MAJOR.MINOR` form.\n- **Major unsupported** — the major version is not in any supported range.\n- **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.\n- **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."
    },
    {
      "name": "EXAMPLE: PINNING",
      "body": "Pin your authoring tools and CI to the schema version they were tested against:\n\n```bash\n# in a CI step\ncurrent=$(curl -s $CYODA_HOST/api/help/workflows/schema-version/versions | jq -r .current)\ntest \"$current\" = \"1.2\" || { echo \"schema drift\"; exit 1; }\n```"
    }
  ],
  "see_also": [
    "workflows",
    "errors.WORKFLOW_SCHEMA_VERSION_UNSUPPORTED",
    "openapi"
  ],
  "stability": "stable",
  "actions": [
    "versions"
  ]
}