From 50294909311d595df0952cc1798696ed401ba5da Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Wed, 22 Apr 2026 14:02:51 -0700
Subject: [PATCH] fix(openapi): address jtreminio oneOf review on /api/userdata
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructure the UserData response schemas to address the review feedback
on the `oneOf` without a discriminator, and fix two accuracy bugs found
while doing it.

Changes
- GET /api/userdata response: extract the inline `oneOf` to a named
  schema (`ListUserdataResponse`) and add the missing third variant
  returned when `split=true` and `full_info=false` (array of
  `[relative_path, ...path_components]`). Previously only two of the
  three actual server response shapes were described.
- UserDataResponse (POST endpoints): correct the description — this
  schema is a single item, not a list — and point at the canonical
  `GetUserDataResponseFullFile` schema instead of the duplicate
  `UserDataResponseFull`. Also removes the malformed blank line in
  `UserDataResponseShort`.
- Delete the now-unused `UserDataResponseFull` and
  `UserDataResponseShort` schemas (replaced by reuse of
  `GetUserDataResponseFullFile` and an inline string variant).
- Add an `x-variant-selector` vendor extension to both `oneOf` sites
  documenting which query-parameter combination selects which branch,
  since a true OpenAPI `discriminator` is not applicable (the variants
  are type-disjoint and the selector lives in the request, not the
  response body).

This keeps the shapes the server actually emits (no wire-breaking
change) while making the selection rule explicit for SDK generators
and readers.
---
 openapi.yaml | 68 ++++++++++++++++++++++++++++------------------------
 1 file changed, 37 insertions(+), 31 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index 3fbcd96dd..77d0e2318 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -926,15 +926,7 @@ paths:
           content:
             application/json:
               schema:
-                oneOf:
-                  - type: array
-                    items:
-                      type: string
-                    description: Simple filename list
-                  - type: array
-                    items:
-                      $ref: "#/components/schemas/GetUserDataResponseFullFile"
-                    description: Full file info list (when full_info=true)
+                $ref: "#/components/schemas/ListUserdataResponse"
         "404":
           description: Directory not found
 
@@ -2618,31 +2610,45 @@ components:
     # Userdata
     # -------------------------------------------------------------------
     UserDataResponse:
-      description: Response body for `/api/userdata` — either a list of filenames or a list of full file objects, depending on the `full_info` query parameter.
+      description: |
+        Response body for the POST endpoints `/api/userdata/{file}` and
+        `/api/userdata/{file}/move/{dest}`. Returns a single item whose
+        shape depends on the `full_info` query parameter.
+      x-variant-selector:
+        full_info=true: file-info object (`GetUserDataResponseFullFile`)
+        default: relative path string
       oneOf:
-        - $ref: "#/components/schemas/UserDataResponseFull"
-        - $ref: "#/components/schemas/UserDataResponseShort"
+        - $ref: "#/components/schemas/GetUserDataResponseFullFile"
+        - type: string
+          description: Relative path of the written or moved file. Returned when `full_info` is absent or false.
 
-    UserDataResponseFull:
-      type: object
-      description: List of files in the authenticated user's data directory, as full file objects with metadata.
-      properties:
-        path:
-          type: string
-        size:
-          type: integer
-        modified:
-          type: integer
-          format: int64
-          description: Unix timestamp of last modification in milliseconds
-        created:
-          type: number
-          description: Unix timestamp of file creation
+    ListUserdataResponse:
+      description: |
+        Response body for `GET /api/userdata`. The array item shape is
+        determined by the `full_info` and `split` query parameters.
+      x-variant-selector:
+        full_info=true: array of file-info objects (`GetUserDataResponseFullFile`)
+        split=true: array of `[relative_path, ...path_components]` arrays
+        default: array of relative path strings
+      oneOf:
+        - type: array
+          items:
+            $ref: "#/components/schemas/GetUserDataResponseFullFile"
+          description: Returned when `full_info=true`.
+        - type: array
+          items:
+            type: array
+            items:
+              type: string
+            minItems: 2
+          description: |
+            Returned when `split=true` and `full_info=false`. Each inner
+            array is `[relative_path, ...path_components]`.
+        - type: array
+          items:
+            type: string
+          description: Default shape — array of file paths relative to the user data root.
 
-    UserDataResponseShort:
-      type: string
-
-      description: List of files in the authenticated user's data directory, as filename strings only.
     GetUserDataResponseFullFile:
       type: object
       description: A single entry in a full-info user data listing.