From 5a316da613a173c783986c5eeb42a423223d33a0 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Mon, 4 May 2026 11:19:23 -0700
Subject: [PATCH] fix(spec): mark DeviceStats.index and
 NodeInfo.essentials_category as nullable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two fields in openapi.yaml are declared as required/non-nullable but
the Python implementation legitimately returns `null` for them, so any
client that response-validates against the spec will fail.

`DeviceStats.index` (used by GET /api/system_stats):
- server.py emits `"index": device.index` unconditionally
- For the CPU device (--cpu mode), `torch.device("cpu").index` is `None`
- → JSON response includes `"index": null` for CPU devices

`NodeInfo.essentials_category` (used by GET /api/object_info):
- The V3 schema-based path (comfy_api/latest/_io.py:1654) unconditionally
  passes `essentials_category=self.essentials_category` into NodeInfoV1
  and serializes via dataclasses.asdict(), so the key is always present
- Schema's `essentials_category` defaults to `None` for nodes that
  don't set it in `define_schema` (e.g. the APG node)
- → JSON response includes `"essentials_category": null` for those nodes
- (The V1 path in server.py uses `hasattr` and so omits the key
  entirely when not set, but the V3 path is the one that produces nulls)

Both fields keep their existing `required` status — they're always
present in the response, the value is just nullable. Descriptions
expanded to spell out when `null` is expected.
---
 openapi.yaml | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index 77d0e2318..fddfa8fdd 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -2347,7 +2347,12 @@ components:
           description: Device type (cuda, mps, cpu, etc.)
         index:
           type: number
-          description: Device index
+          nullable: true
+          description: |
+            Device index within its type (e.g. CUDA ordinal for `cuda:0`,
+            `cuda:1`). `null` for devices with no index, including the CPU
+            device returned in `--cpu` mode (PyTorch's `torch.device('cpu').index`
+            is `None`).
         vram_total:
           type: number
           description: Total VRAM in bytes
@@ -2503,7 +2508,11 @@ components:
           description: Alternative search terms for finding this node
         essentials_category:
           type: string
-          description: Category override used by the essentials pack
+          nullable: true
+          description: |
+            Category override used by the essentials pack. `null` for nodes
+            that don't set `ESSENTIALS_CATEGORY` (V1) or whose `Schema`
+            doesn't populate `essentials_category` (V3 / `comfy_api.latest.io`).
 
     # -------------------------------------------------------------------
     # Models