Add JSON Schema for Prompt API Format
- Dominant language
- Python
- Stars
- 133k
- Forks
- 15.7k
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 155
Description
### 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 #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](https://discordapp.com/channels/1218270712402415686/1225921300443435058/1394068591376338955), 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_
Contributor guide
Assessment
This issue has not been assessed yet.