Feature Idea

Problem

Currently, developers working with the ComfyUI API face several challenges:

• No formal specification for the prompt format used with /prompt endpoint
• Confusion between workflow and prompt formats (see Workflow format in UI is not the same as API format - creates a lot of confusion and challenges #1335)
• No validation or IDE support for API integrations
• Difficult to build reliable automation tools

Proposed Solution

I've created a JSON Schema for the current prompt format by analyzing the validation logic in server.py (L1070-1140) and execution.py (L2300-2700). This schema:

• Documents the existing format (no breaking changes)
• Enables validation and IDE autocomplete
• Provides clear examples for common workflows
• Serves as a foundation for future enhancements

What This Includes

1. Core Schema (schemas/prompt.json)

   • Validates prompt structure with node IDs as string keys
   • Supports both direct values and node links [node_id, output_index]
   • Handles any class_type (extensible for custom nodes)
   • Includes optional _meta fields

2. Documentation (docs/api/prompt-schema.md)

   • Explanation of validation rules
   • Common node examples
   • Format comparison guide (workflow vs prompt)

Implementation

Ready to submit PR with schema and documentation once the approach is approved.

Future Possibilities

Based on initial Discord feedback, there's interest in eventually generating dynamic schemas based on installed nodes. This initial schema provides a foundation that could be extended to:

• Generate node-specific validation with required inputs
• Enable LLM structured output for workflow generation
• Create type-safe API clients

However, this initial PR focuses only on documenting the current format to provide immediate value while keeping the scope manageable.

Questions for Review

1. Is schemas/ the appropriate location for this file?
2. Should we version the schema for future compatibility?
3. Any specific validation rules that should be included in v1?

Existing Solutions

No response

Other

No response