This document defines the canonical Isis contract for custom ComfyUI nodes in
workflow definitions validated through @isis/workflows.
Scope#
The contract has three layers:
- Workflow-level manifest (
custom_nodes_required). - Per-node shape (
nodes.<id>schema). - 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_requiredis 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])
- scalar (
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_versionworkflow_infoinputsnodesprompt_constructionoutput_spec
Validation and Enforcement Points#
- Authoring/CI:
pnpm nx run @isis/workflows:workflow:validatepnpm nx run @isis/workflows:lint(includes schema validation dependency)
- Registry ingestion:
POST /api/v1/workflows/validatePOST /api/v1/workflows
- Compatibility helper:
validateWorkflowCompatibility(...)- legacy workflows without
schema_versionare migrated to schema1.0.0via 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, andoutputs. - Keep node keys strict; move extra metadata to top-level passthrough fields if needed.
- Pin custom node pack versions for production workflows.