mirror of
https://github.com/comfyanonymous/ComfyUI.git
synced 2026-05-06 10:17:59 +08:00
spec: add workflow_id / workflow_version_id to PromptRequest with x-runtime tag (#13709)
Adds two optional, nullable UUID fields to PromptRequest for runtimes
that wrap workflow execution in a workflow-version entity (the
hosted-cloud runtime does this; local ComfyUI does not). Both fields
are tagged `x-runtime: [cloud]` to mark them as runtime-specific —
local ComfyUI returns `null` (or omits them entirely) and that's
correct behavior, not drift.
## Why these fields belong in the OSS spec
Hosted-cloud's frontend and backend share `openapi.yaml` as their
single source of truth via auto-generated client types. Without the
fields declared in the spec, the cloud runtime has to either:
1. Hand-edit a vendored copy of openapi.yaml (drift between vendor
and upstream — unsustainable).
2. Maintain a separate cloud-only spec file (forks the contract,
defeats the point of a shared OSS spec).
Both options have been tried and both produce maintenance pain. The
shape that scales is: cloud-only fields live in OSS spec under their
intended path, declared nullable, with an explicit `x-runtime` tag so
local-only readers can ignore them programmatically and human readers
can see what each runtime populates.
## About the `x-runtime` extension
This is the first use of `x-runtime` in this spec. Convention:
- `x-runtime: [cloud]` — only the hosted-cloud runtime populates the
field; local returns null or omits.
- `x-runtime: [local]` — only local populates; cloud returns null.
- Tag absent — both runtimes populate the field (the default).
This is a vendor extension (`x-` prefix) and is ignored by spec
validators that don't recognize it, including `kin-openapi`. Local
clients reading the spec see two extra optional nullable fields, which
is forward-compatible with all existing readers.
## What this does not change
- No Python code changes. `PromptRequest` already accepts arbitrary
optional fields (`extra_data: additionalProperties: true` on the
same schema is a stronger guarantee). The Python server already
silently accepts and ignores both fields today.
- No required-fields change. Both fields stay outside `required`,
so older clients that don't know about them keep validating.
- No nullability widening on existing fields.
## Verification
- YAML parses (`yaml.safe_load`).
- `kin-openapi` `loader.LoadFromFile` accepts the modified spec.
- `openapi3filter.ValidateRequest` on a PromptRequest with both
fields set to `null`, set to a valid UUID, or omitted — all pass.
This commit is contained in:
20
openapi.yaml
20
openapi.yaml
@ -1999,6 +1999,26 @@ components:
|
||||
items:
|
||||
type: string
|
||||
description: List of node IDs to execute (partial graph execution)
|
||||
workflow_id:
|
||||
type: string
|
||||
format: uuid
|
||||
nullable: true
|
||||
x-runtime: [cloud]
|
||||
description: |
|
||||
UUID identifying a hosted-cloud workflow entity to associate with this
|
||||
job. Local ComfyUI doesn't track workflow entities and returns `null`
|
||||
(or omits the field). The `x-runtime: [cloud]` extension marks this
|
||||
as populated only by the hosted-cloud runtime; absence of the tag
|
||||
means a field is populated by all runtimes.
|
||||
workflow_version_id:
|
||||
type: string
|
||||
format: uuid
|
||||
nullable: true
|
||||
x-runtime: [cloud]
|
||||
description: |
|
||||
UUID identifying a hosted-cloud workflow version to associate with
|
||||
this job. Local ComfyUI returns `null` (or omits the field). See
|
||||
`workflow_id` above for `x-runtime` semantics.
|
||||
|
||||
PromptResponse:
|
||||
type: object
|
||||
|
||||
Reference in New Issue
Block a user