fix(zod): warn on optional field usage

src/_vendor/zod-to-json-schema/parsers/object.ts

@@ -39,12 +39,20 @@ export function parseObjectDef(def: ZodObjectDef, refs: Refs) {
         [propName, propDef],
       ) => {
         if (propDef === undefined || propDef._def === undefined) return acc;
+        const propertyPath = [...refs.currentPath, 'properties', propName];
         const parsedDef = parseDef(propDef._def, {
           ...refs,
-          currentPath: [...refs.currentPath, 'properties', propName],
-          propertyPath: [...refs.currentPath, 'properties', propName],
+          currentPath: propertyPath,
+          propertyPath,
         });
         if (parsedDef === undefined) return acc;
+        if (refs.openaiStrictMode && propDef.isOptional() && !propDef.isNullable()) {
+          console.warn(
+            `Zod field at \`${propertyPath.join(
+              '/',
+            )}\` uses \`.optional()\` without \`.nullable()\` which is not supported by the API. See: https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#all-fields-must-be-required\nThis will become an error in a future version of the SDK.`,
+          );
+        }
         return {
           properties: {
             ...acc.properties,

tests/helpers/zod.test.ts

@@ -278,4 +278,56 @@ describe('zodResponseFormat', () => {
       }
     `);
   });
+
+  it('warns on optional fields', () => {
+    const consoleSpy = jest.spyOn(console, 'warn');
+    consoleSpy.mockClear();
+
+    zodResponseFormat(
+      z.object({
+        required: z.string(),
+        optional: z.string().optional(),
+        optional_and_nullable: z.string().optional().nullable(),
+      }),
+      'schema',
+    );
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Zod field at `#/definitions/schema/properties/optional` uses `.optional()` without `.nullable()` which is not supported by the API. See: https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#all-fields-must-be-required\nThis will become an error in a future version of the SDK.',
+    );
+    expect(consoleSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('warns on nested optional fields', () => {
+    const consoleSpy = jest.spyOn(console, 'warn');
+    consoleSpy.mockClear();
+
+    zodResponseFormat(
+      z.object({
+        foo: z.object({ bar: z.array(z.object({ can_be_missing: z.boolean().optional() })) }),
+      }),
+      'schema',
+    );
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Zod field at `#/definitions/schema/properties/foo/properties/bar/items/properties/can_be_missing` uses `.optional()`',
+      ),
+    );
+    expect(consoleSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not warn on union nullable fields', () => {
+    const consoleSpy = jest.spyOn(console, 'warn');
+    consoleSpy.mockClear();
+
+    zodResponseFormat(
+      z.object({
+        union: z.union([z.string(), z.null()]).optional(),
+      }),
+      'schema',
+    );
+
+    expect(consoleSpy).toHaveBeenCalledTimes(0);
+  });
 });