fix: Correct schema version from v2 to v1 and add schema generation docs

- Fix version number in ComfyWorkflow1BaseType interface (was 2, should be 1)
- Fix version literal in zComfyWorkflow1 schema (was 2, should be 1)
- Update all comments referencing v2 to correctly state v1
- Fix validateComfyWorkflow to only check for version 1, not 2
- Add comprehensive schema generation documentation in docs/SCHEMA_GENERATION.md
- Document SOP for schema updates and version bumping

The PR was incorrectly trying to create a v2 schema when only documentation
changes were made. Schema version should only increment for breaking changes.

docs/SCHEMA_GENERATION.md

@@ -0,0 +1,160 @@
+# ComfyUI Workflow Schema Generation
+
+This document describes the process for generating and maintaining JSON Schema definitions for ComfyUI workflows.
+
+## Overview
+
+ComfyUI uses **Zod schemas** in TypeScript to define workflow structure, which are converted to **JSON Schema** format for external consumption, documentation, and validation.
+
+### Schema Versions
+
+- **Version 0.4** (Legacy): Original workflow format with array-based links
+- **Version 1.0** (Current): Modern format with object-based links, subgraphs, and reroutes
+
+## Schema Generation Process
+
+### Prerequisites
+
+1. Ensure all dependencies are installed: `npm install`
+2. Verify TypeScript compilation: `npm run typecheck`
+
+### Command
+
+```bash
+npm run json-schema
+```
+
+This runs the generation script: `scripts/generate-json-schema.ts`
+
+### Output
+
+Generated schemas are written to `./schemas/` directory:
+
+- `workflow-0_4.json` (~80KB) - Legacy workflow format
+- `workflow-1_0.json` (~82KB) - Current workflow format
+- `node-def-v1.json` - Node definition schema v1
+- `node-def-v2.json` - Node definition schema v2
+
+**Note**: The `./schemas/` directory is gitignored and not committed to the repository.
+
+## When to Regenerate Schemas
+
+### Required Regeneration
+
+Run schema generation when:
+
+1. **Schema Changes**: Any modifications to files in `/src/schemas/`
+2. **Breaking Changes**: Changes that affect data structure or validation
+3. **New Features**: Adding new workflow capabilities (subgraphs, reroutes, etc.)
+4. **Documentation Updates**: When schema descriptions change
+
+### Schema Version Bumping
+
+Only increment schema version for **breaking changes**:
+
+- Data structure changes (field renames, type changes)
+- Required field additions
+- Format changes that break backward compatibility
+
+**Non-breaking changes** (documentation, optional fields) should NOT bump the version.
+
+## Schema Sources
+
+### Primary Schemas (Zod-based)
+
+#### Workflow Schemas
+- **File**: `src/schemas/comfyWorkflowSchema.ts`
+- **Exports**: `zComfyWorkflow` (v0.4), `zComfyWorkflow1` (v1.0)
+- **Purpose**: Defines workflow JSON structure for both legacy and modern formats
+
+#### Node Definition Schemas
+- **Files**: 
+  - `src/schemas/nodeDefSchema.ts` (v1)
+  - `src/schemas/nodeDef/nodeDefSchemaV2.ts` (v2)
+- **Purpose**: Defines node definition structure for different versions
+
+### Generation Configuration
+
+The generation script uses:
+- **Library**: `zod-to-json-schema`
+- **Strategy**: `$refStrategy: 'none'` (inlines all references)
+- **Output**: Formatted JSON with proper naming
+
+## Standard Operating Procedure (SOP)
+
+### For Schema Updates
+
+1. **Make Changes**: Modify Zod schemas in `/src/schemas/`
+2. **Test Locally**: Ensure changes work with existing workflows
+3. **Run Generation**: `npm run json-schema`
+4. **Validate Output**: Check generated schemas for correctness
+5. **Test Integration**: Verify schemas work with external tools
+6. **Document Changes**: Update this document if process changes
+
+### For Version Bumps
+
+1. **Assess Breaking Changes**: Determine if changes are truly breaking
+2. **Update Version**: Increment version number in schema definition
+3. **Update Validation**: Modify `validateComfyWorkflow()` function
+4. **Update Serialization**: Update LGraph serialization if needed
+5. **Test Backward Compatibility**: Ensure old workflows still load
+6. **Document Migration**: Provide migration guide if needed
+
+### For External Publishing
+
+**Current Status**: No automated publishing to docs.comfy.org exists yet.
+
+**Recommended Process**:
+1. Generate schemas locally
+2. Copy to appropriate documentation repository
+3. Update documentation with new schema versions
+4. Coordinate with docs team for publication
+
+## Troubleshooting
+
+### Common Issues
+
+#### Lodash Import Errors
+**Error**: `SyntaxError: The requested module 'lodash' does not provide an export named 'clamp'`
+
+**Solution**: Use the simplified generation script that avoids litegraph imports:
+```bash
+npx tsx scripts/generate-json-schema-simple.ts
+```
+
+#### Recursive Reference Warnings
+**Warning**: `Recursive reference detected... Defaulting to any`
+
+**Explanation**: This is expected for subgraph definitions and doesn't affect functionality.
+
+### Schema Validation Issues
+
+1. **Check Source Schema**: Verify Zod schema is valid
+2. **Test TypeScript**: Run `npm run typecheck`
+3. **Check Dependencies**: Ensure all imports resolve correctly
+4. **Validate Output**: Test generated JSON Schema with online validators
+
+## Integration Points
+
+### External Documentation
+- **docs.comfy.org**: Official ComfyUI documentation site
+- **Workflow Spec**: https://docs.comfy.org/specs/workflow_json
+
+### Development Tools
+- **IDE Support**: Generated schemas provide autocomplete and validation
+- **API Validation**: External tools can validate workflow JSON
+- **Documentation Generation**: Schemas document workflow structure
+
+## Future Improvements
+
+1. **Automated Publishing**: Set up CI/CD to publish schemas to docs.comfy.org
+2. **Version Management**: Implement semantic versioning for schema changes
+3. **Migration Tools**: Create utilities to migrate between schema versions
+4. **Testing**: Add automated tests for schema generation and validation
+5. **Documentation**: Generate human-readable documentation from schemas
+
+## References
+
+- **Zod Documentation**: https://zod.dev/
+- **JSON Schema Specification**: https://json-schema.org/
+- **ComfyUI Workflow Specification**: https://docs.comfy.org/specs/workflow_json

src/schemas/comfyWorkflowSchema.ts

@@ -4,49 +4,101 @@ import { fromZodError } from 'zod-validation-error'
 // GroupNode is hacking node id to be a string, so we need to allow that.
 // innerNode.id = `${this.node.id}:${i}`
 // Remove it after GroupNode is redesigned.
-export const zNodeId = z.union([z.number().int(), z.string()])
-export const zNodeInputName = z.string()
+/**
+ * Node identifier that can be either a number or string.
+ * Numeric IDs are standard, string IDs are used for GroupNodes.
+ */
+export const zNodeId = z
+  .union([z.number().int(), z.string()])
+  .describe('Unique identifier for a node in the workflow')
+
+/** Name of a node input slot */
+export const zNodeInputName = z
+  .string()
+  .describe('The name of a node input parameter')
+
 export type NodeId = z.infer<typeof zNodeId>
-export const zSlotIndex = z.union([
-  z.number().int(),
-  z
-    .string()
-    .transform((val) => parseInt(val))
-    .refine((val) => !isNaN(val), {
-      message: 'Invalid number'
-    })
-])
+
+/**
+ * Index of a slot on a node (input or output).
+ * Can be number or string that parses to a number.
+ */
+export const zSlotIndex = z
+  .union([
+    z.number().int(),
+    z
+      .string()
+      .transform((val) => parseInt(val))
+      .refine((val) => !isNaN(val), {
+        message: 'Invalid number'
+      })
+  ])
+  .describe('Index of an input or output slot on a node')
 
 // TODO: Investigate usage of array and number as data type usage in custom nodes.
 // Known usage:
 // - https://github.com/rgthree/rgthree-comfy Context Big node is using array as type.
-export const zDataType = z.union([z.string(), z.array(z.string()), z.number()])
+/**
+ * Data type for node inputs/outputs. Can be string, array of strings, or number.
+ * Most common types are strings like 'IMAGE', 'LATENT', 'MODEL', etc.
+ */
+export const zDataType = z
+  .union([z.string(), z.array(z.string()), z.number()])
+  .describe('Data type specification for node connections')
 
-const zVector2 = z.union([
-  z
-    .object({ 0: z.number(), 1: z.number() })
-    .passthrough()
-    .transform((v) => [v[0], v[1]] as [number, number]),
-  z.tuple([z.number(), z.number()])
-])
+/**
+ * 2D position or size vector [x, y].
+ * Can be array tuple or object with numeric indices.
+ */
+const zVector2 = z
+  .union([
+    z
+      .object({ 0: z.number(), 1: z.number() })
+      .passthrough()
+      .transform((v) => [v[0], v[1]] as [number, number]),
+    z.tuple([z.number(), z.number()])
+  ])
+  .describe('2D coordinate or size vector')
 
-// Definition of an AI model file used in the workflow.
-const zModelFile = z.object({
-  name: z.string(),
-  url: z.string().url(),
-  hash: z.string().optional(),
-  hash_type: z.string().optional(),
-  directory: z.string()
-})
+/**
+ * AI model file definition used in the workflow.
+ * Contains metadata for downloading and verifying model files.
+ */
+const zModelFile = z
+  .object({
+    /** Model file name */
+    name: z.string().describe('Model file name'),
+    /** Download URL for the model */
+    url: z.string().url().describe('Download URL for the model'),
+    /** File hash for integrity verification */
+    hash: z
+      .string()
+      .optional()
+      .describe('File hash for integrity verification'),
+    /** Hash algorithm type (e.g., 'sha256') */
+    hash_type: z.string().optional().describe('Hash algorithm type'),
+    /** Directory where model should be stored */
+    directory: z.string().describe('Directory where model should be stored')
+  })
+  .describe('AI model file metadata')
 
+/**
+ * Graph state tracking for ID generation in schema version 1.
+ * Maintains counters for generating unique IDs for new elements.
+ */
 const zGraphState = z
   .object({
-    lastGroupId: z.number(),
-    lastNodeId: z.number(),
-    lastLinkId: z.number(),
-    lastRerouteId: z.number()
+    /** Last assigned group ID */
+    lastGroupId: z.number().describe('Last assigned group ID'),
+    /** Last assigned node ID */
+    lastNodeId: z.number().describe('Last assigned node ID'),
+    /** Last assigned link ID */
+    lastLinkId: z.number().describe('Last assigned link ID'),
+    /** Last assigned reroute ID */
+    lastRerouteId: z.number().describe('Last assigned reroute ID')
   })
   .passthrough()
+  .describe('Graph state tracking for ID generation')
 
 const zComfyLink = z.tuple([
   z.number(), // Link id
@@ -287,24 +339,52 @@ export const zBaseExportableGraph = z.object({
   subgraphs: z.array(zSubgraphInstance).optional()
 })
 
-/** Schema version 0.4 */
+/**
+ * ComfyUI Workflow JSON Schema version 0.4 (legacy).
+ * This is the original workflow format used by ComfyUI.
+ */
 export const zComfyWorkflow = zBaseExportableGraph
   .extend({
-    id: z.string().uuid().optional(),
-    revision: z.number().optional(),
-    last_node_id: zNodeId,
-    last_link_id: z.number(),
-    nodes: z.array(zComfyNode),
-    links: z.array(zComfyLink),
-    floatingLinks: z.array(zComfyLinkObject).optional(),
-    groups: z.array(zGroup).optional(),
-    config: zConfig.optional().nullable(),
-    extra: zExtra.optional().nullable(),
-    version: z.number(),
-    models: z.array(zModelFile).optional(),
-    definitions: zGraphDefinitions.optional()
+    /** Unique workflow identifier */
+    id: z.string().uuid().optional().describe('Unique workflow identifier'),
+    /** Workflow revision number */
+    revision: z.number().optional().describe('Workflow revision number'),
+    /** Highest node ID used in this workflow */
+    last_node_id: zNodeId.describe('Highest node ID used in this workflow'),
+    /** Highest link ID used in this workflow */
+    last_link_id: z.number().describe('Highest link ID used in this workflow'),
+    /** All nodes in the workflow */
+    nodes: z.array(zComfyNode).describe('All nodes in the workflow'),
+    /** Node connections (legacy tuple format) */
+    links: z
+      .array(zComfyLink)
+      .describe('Node connections in legacy tuple format'),
+    /** Floating links (unconnected endpoints) */
+    floatingLinks: z
+      .array(zComfyLinkObject)
+      .optional()
+      .describe('Floating links with unconnected endpoints'),
+    /** Visual groupings of nodes */
+    groups: z.array(zGroup).optional().describe('Visual groupings of nodes'),
+    /** Workflow configuration settings */
+    config: zConfig
+      .optional()
+      .nullable()
+      .describe('Workflow configuration settings'),
+    /** Extra metadata and extensions */
+    extra: zExtra
+      .optional()
+      .nullable()
+      .describe('Extra metadata and extensions'),
+    /** Schema version number */
+    version: z.number().describe('Schema version number (0.4)'),
+    /** Required model files */
+    models: z.array(zModelFile).optional().describe('Required AI model files'),
+    /** Subgraph definitions */
+    definitions: zGraphDefinitions.optional().describe('Subgraph definitions')
   })
   .passthrough()
+  .describe('ComfyUI Workflow JSON Schema v0.4')
 
 /** Required for recursive definition of subgraphs. */
 interface ComfyWorkflow1BaseType {
@@ -339,37 +419,76 @@ interface ComfyWorkflow1BaseOutput extends ComfyWorkflow1BaseType {
   }
 }
 
-/** Schema version 1 */
+/**
+ * ComfyUI Workflow JSON Schema version 1 (current).
+ * This is the modern workflow format with improved structure and features.
+ */
 export const zComfyWorkflow1 = zBaseExportableGraph
   .extend({
-    id: z.string().uuid().optional(),
-    revision: z.number().optional(),
-    version: z.literal(1),
-    config: zConfig.optional().nullable(),
-    state: zGraphState,
-    groups: z.array(zGroup).optional(),
-    nodes: z.array(zComfyNode),
-    links: z.array(zComfyLinkObject).optional(),
-    floatingLinks: z.array(zComfyLinkObject).optional(),
-    reroutes: z.array(zReroute).optional(),
-    extra: zExtra.optional().nullable(),
-    models: z.array(zModelFile).optional(),
+    /** Unique workflow identifier */
+    id: z.string().uuid().optional().describe('Unique workflow identifier'),
+    /** Workflow revision number for tracking changes */
+    revision: z
+      .number()
+      .optional()
+      .describe('Workflow revision number for tracking changes'),
+    /** Schema version (always 1 for this format) */
+    version: z.literal(1).describe('Schema version number (1)'),
+    /** Workflow configuration settings */
+    config: zConfig
+      .optional()
+      .nullable()
+      .describe('Workflow configuration settings'),
+    /** Graph state for ID tracking and generation */
+    state: zGraphState.describe('Graph state for ID tracking and generation'),
+    /** Visual groupings of nodes */
+    groups: z.array(zGroup).optional().describe('Visual groupings of nodes'),
+    /** All nodes in the workflow */
+    nodes: z.array(zComfyNode).describe('All nodes in the workflow'),
+    /** Node connections (modern object format) */
+    links: z
+      .array(zComfyLinkObject)
+      .optional()
+      .describe('Node connections in modern object format'),
+    /** Floating links (unconnected endpoints) */
+    floatingLinks: z
+      .array(zComfyLinkObject)
+      .optional()
+      .describe('Floating links with unconnected endpoints'),
+    /** Reroute nodes for organizing connections */
+    reroutes: z
+      .array(zReroute)
+      .optional()
+      .describe('Reroute nodes for organizing connections'),
+    /** Extra metadata and extensions */
+    extra: zExtra
+      .optional()
+      .nullable()
+      .describe('Extra metadata and extensions'),
+    /** Required AI model files */
+    models: z.array(zModelFile).optional().describe('Required AI model files'),
+    /** Subgraph definitions */
     definitions: z
       .object({
-        subgraphs: z.lazy(
-          (): z.ZodArray<
-            z.ZodType<
-              SubgraphDefinitionBase<ComfyWorkflow1BaseOutput>,
-              z.ZodTypeDef,
-              SubgraphDefinitionBase<ComfyWorkflow1BaseInput>
-            >,
-            'many'
-          > => z.array(zSubgraphDefinition)
-        )
+        /** Nested subgraph definitions */
+        subgraphs: z
+          .lazy(
+            (): z.ZodArray<
+              z.ZodType<
+                SubgraphDefinitionBase<ComfyWorkflow1BaseOutput>,
+                z.ZodTypeDef,
+                SubgraphDefinitionBase<ComfyWorkflow1BaseInput>
+              >,
+              'many'
+            > => z.array(zSubgraphDefinition)
+          )
+          .describe('Nested subgraph definitions')
       })
       .optional()
+      .describe('Subgraph definitions')
   })
   .passthrough()
+  .describe('ComfyUI Workflow JSON Schema v1')
 
 export const zExportedSubgraphIONode = z.object({
   id: zNodeId,
@@ -481,6 +600,14 @@ const zWorkflowVersion = z.object({
   version: z.number()
 })
 
+/**
+ * Validates a ComfyUI workflow JSON against the appropriate schema version.
+ * Supports both legacy (v0.4) and modern (v1) workflow formats.
+ *
+ * @param data - The workflow data to validate
+ * @param onError - Error callback function for validation failures
+ * @returns Parsed and validated workflow data or null if invalid
+ */
 export async function validateComfyWorkflow(
   data: unknown,
   onError: (error: string) => void = console.warn
@@ -489,17 +616,18 @@ export async function validateComfyWorkflow(
 
   let result: SafeParseReturnType<unknown, ComfyWorkflowJSON>
   if (!versionResult.success) {
-    // Invalid workflow
+    // Invalid workflow - missing or invalid version
     const error = fromZodError(versionResult.error)
     onError(`Workflow does not contain a valid version.  Zod error:\n${error}`)
     return null
   } else if (versionResult.data.version === 1) {
-    // Schema version 1
+    // Modern schema version 1 (current)
     result = await zComfyWorkflow1.safeParseAsync(data)
   } else {
-    // Unknown or old version: 0.4
+    // Legacy or unknown version: defaults to 0.4 format
     result = await zComfyWorkflow.safeParseAsync(data)
   }
+
   if (result.success) return result.data
 
   const error = fromZodError(result.error)