Comfy-Org / Comfy-Org/ComfyUI

Add JSON Schema for Prompt API Format

Open
#8,899 8 comments 0 reactions 0 assignees View on GitHub
A bug-cop:response-received Feature
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.