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.tsdefines strict typed schema includingworkflow_info,inputs, andnodes.apps/isis/workflow-registry/src/schemas/workflow.schema.tsuses permissivedefinition: z.record(z.unknown()).libs/isis/workflows/src/workflows/**/*.jsonauthor 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:
nodesas 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/linksinput 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.
Option B: Canonicalize on array nodes + links model (Rejected)#
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#
- Publish shared canonical schema package.
- Refactor workflow-registry validation to import shared schema.
- Add compatibility adapter (only if required) with round-trip tests.
- Migrate and verify all workflow files against schema version.
- Add CI lint and compatibility gates.
Ticket Traceability#
WS00-005F03-001toF03-010F02-001toF02-010F14-001toF14-010F15-001toF15-010
References#
- Internal:
libs/isis/workflows/src/schemas/workflow.schema.tsapps/isis/workflow-registry/src/schemas/workflow.schema.tslibs/isis/workflows/src/workflows/docs/domains/isis/isis-domain-completeness-audit-2026-02-21.md
- External: