# ADR-0002: Workflow Schema Canonicalization and Compatibility Policy

**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.

### 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

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

- Internal:
  - `libs/isis/workflows/src/schemas/workflow.schema.ts`
  - `apps/isis/workflow-registry/src/schemas/workflow.schema.ts`
  - `libs/isis/workflows/src/workflows/`
  - `docs/domains/isis/isis-domain-completeness-audit-2026-02-21.md`
- External:
  - [Zod Documentation](https://zod.dev/)
  - [ComfyUI API format notes (UI export vs API prompt)](https://docs.runcomfy.com/workflow-files)
  - [ComfyUI API example (`prompt` node-id object map)](https://github.com/comfyanonymous/ComfyUI/blob/master/script_examples/basic_api_example.py)
