Eve library

Isis Custom Node Contracts

Guide

Revision 1

On this page

This document defines the canonical Isis contract for custom ComfyUI nodes in workflow definitions validated through @isis/workflows.

Scope#

The contract has three layers:

  1. Workflow-level manifest (custom_nodes_required).
  2. Per-node shape (nodes.<id> schema).
  3. Runtime compatibility expectations (provider/node availability).

Workflow Manifest Contract#

custom_nodes_required is optional, but when present it must be an array of strings.

json
{
  "custom_nodes_required": [
    "ComfyUI-AnimateDiff-Evolved",
    "ComfyUI-Impact-Pack@>=1.5.0 <2.0.0",
    "IPAdapterPlus"
  ]
}

Required behavior#

  • Each entry must identify a required custom node pack or node capability.
  • Entries must be stable IDs (do not use free-form prose).
  • Version pinning is recommended for reproducibility (<id>@<semver-range>).
  • If custom_nodes_required is declared, workflows must not reference missing capabilities during execution.

Node Contract (nodes.<id>)#

Each node in the canonical object-map must match:

json
{
  "class_type": "SomeNodeClass",
  "inputs": {
    "input_a": "value",
    "input_b": ["10", 0]
  },
  "outputs": ["IMAGE"],
  "_comment": "optional",
  "_condition": "optional"
}

Required fields#

  • class_type (string, required): ComfyUI/custom node class identifier.
  • inputs (object, required): keyed input payload; each value must be one of:
    • scalar (string, number, boolean, null)
    • node reference tuple ([nodeId: string, outputIndex: number])
  • outputs (string[], required): declared output channels.

Optional fields#

  • _comment (string)
  • _condition (string)

Strictness#

  • Additional node keys are rejected by schema validation.
  • Array-based legacy graph format (nodes[] + links[]) is non-canonical and must be normalized through the legacy adapter before validation.

Canonical Required Top-Level Fields#

For schema 1.0.0, compatibility checks require:

  • schema_version
  • workflow_info
  • inputs
  • nodes
  • prompt_construction
  • output_spec

Validation and Enforcement Points#

  • Authoring/CI:
    • pnpm nx run @isis/workflows:workflow:validate
    • pnpm nx run @isis/workflows:lint (includes schema validation dependency)
  • Registry ingestion:
    • POST /api/v1/workflows/validate
    • POST /api/v1/workflows
  • Compatibility helper:
    • validateWorkflowCompatibility(...)
    • legacy workflows without schema_version are migrated to schema 1.0.0 via the shared schema migration registry.

Authoring Checklist#

  • Include every external/custom dependency in custom_nodes_required.
  • Use canonical node object-map format (nodes.<id>), not array graphs.
  • Ensure every node has class_type, inputs, and outputs.
  • Keep node keys strict; move extra metadata to top-level passthrough fields if needed.
  • Pin custom node pack versions for production workflows.