Eve library

ADR-0002: Workflow Schema Canonicalization and Compatibility Policy

ADR

Revision 1

On this page

Status: Accepted
Date: 2026-02-21
Authors: Isis Workflow Team, Isis Registry Team
Reviewers: @oshun/isis-team, @oshun/ml-team, @oshun/docs-team, @oshun/core-team

Context and Problem Statement#

Isis workflows are authored under libs/isis/workflows with a strict schema model, while workflow registry API validation currently accepts broad z.record(z.unknown()) for definitions. This creates schema drift risk between authoring, registry, and execution paths.

Current code evidence:

  • libs/isis/workflows/src/schemas/workflow.schema.ts defines strict typed schema including workflow_info, inputs, and nodes.
  • apps/isis/workflow-registry/src/schemas/workflow.schema.ts uses permissive definition: z.record(z.unknown()).
  • libs/isis/workflows/src/workflows/**/*.json author workflows as node-object maps keyed by node id.

Without a canonical contract, runtime incompatibility can silently remove capabilities or fail at execution time.

Decision#

Establish a single canonical workflow schema and compatibility policy for all Isis workflow surfaces.

Canonical Format Choice#

Canonical node representation is:

  • nodes as an object map keyed by node id strings
  • each node contains class_type, inputs, and optional metadata fields

Rationale:

  • Matches current corpus in libs/isis/workflows/src/workflows.
  • Matches current runtime handler traversal patterns in RunPod worker.
  • Supports deterministic patching/overrides by node id.
  • Aligns with ComfyUI API prompt format used by upstream API examples.

Canonical Ownership#

Schema source-of-truth will be centralized in a shared package and imported by:

  • workflow authoring/validation scripts
  • workflow-registry request validation
  • generation resolver/executor preflight validation
  • CI contract tests

Versioning Policy#

  • Schema versions use semver.
  • MAJOR: breaking structure change; requires migration plan and conversion tests.
  • MINOR: backward-compatible additive fields.
  • PATCH: docs/constraints clarification with no shape change.

Every workflow document must include schema version metadata.

Compatibility Policy#

  • Registry must reject non-canonical payloads unless explicitly routed through a defined adapter.
  • If legacy array nodes/links input is supported, conversion must be reversible and lossless with contract tests.
  • Executor must fail closed on unresolved or incompatible workflow contracts in production.

Decision Drivers#

  • Deterministic workflow resolution and execution.
  • Eliminate hidden contract mismatches between API, registry, and workers.
  • Enable scalable test automation for all 45 workflow IDs.
  • Support safe evolution of schema over time.

Considered Options#

Option A: Keep permissive registry schema (Rejected)#

Pros:

  • Fastest short-term flexibility.

Cons:

  • No compatibility guarantees.
  • Runtime failures discovered too late.

Pros:

  • Familiar to graph tooling.

Cons:

  • Mismatched with existing workflow corpus and current execution traversal approach.
  • Requires broad migration with little operational gain.

Option C: Canonicalize on object-map nodes with strict shared validation (Chosen)#

Pros:

  • Aligns with current Isis assets and execution patterns.
  • Enables deterministic node overrides and diffing.
  • Lowest migration risk with strongest compatibility guardrails.

Cons:

  • Requires adapters for any non-canonical producer.
  • Requires stronger CI gates and validator discipline.

Consequences#

Positive#

  • One schema contract across authoring, registry, and execution.
  • Early failure for invalid workflows.
  • Clear migration/versioning lifecycle.

Tradeoffs#

  • Short-term effort to integrate shared schema package across services.
  • Need to implement and maintain compatibility adapter tests if dual format support is retained.

Implementation Rules#

  • Registry create/update/version endpoints validate with canonical schema.
  • Workflow import/export endpoints preserve canonical shape exactly.
  • CI blocks commits that add non-canonical workflow files.
  • Contract tests enforce:
    • workflow file -> registry validation pass
    • registry export -> executor preflight pass

Rollout Plan#

  1. Publish shared canonical schema package.
  2. Refactor workflow-registry validation to import shared schema.
  3. Add compatibility adapter (only if required) with round-trip tests.
  4. Migrate and verify all workflow files against schema version.
  5. Add CI lint and compatibility gates.

Ticket Traceability#

  • WS00-005
  • F03-001 to F03-010
  • F02-001 to F02-010
  • F14-001 to F14-010
  • F15-001 to F15-010

References#