Comfy-Org/ComfyUI_frontend
1
0
Fork 0
mirror of https://github.com/Comfy-Org/ComfyUI_frontend.git synced 2026-02-05 07:30:11 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
fix-schema-version-and-generation
ComfyUI_frontend/docs/SCHEMA_GENERATION.md
bymyself ae184609c8 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.
2025-08-12 15:18:59 -07:00

5.3 KiB
Raw Permalink Blame History

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

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:

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

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