From df5f3d53546891a7cb2a6373f97957745f0db0ec Mon Sep 17 00:00:00 2001 From: mukunda katta Date: Fri, 15 May 2026 01:19:53 -0700 Subject: [PATCH] docs: clarify supported zod schema features --- helpers.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/helpers.md b/helpers.md index b33eec3476..be63db88ae 100644 --- a/helpers.md +++ b/helpers.md @@ -45,6 +45,27 @@ if (message?.parsed) { } ``` +### Supported Zod features + +The Zod helpers convert your schema to the strict JSON Schema subset supported by +Structured Outputs. Basic schema shapes such as `z.object()`, `z.string()`, +`z.number()`, `z.boolean()`, `z.array()`, `z.enum()`, `z.literal()`, +`z.union()`, and nullable fields are supported when they can be represented as +strict JSON Schema. + +Some Zod features do not map cleanly to strict JSON Schema or are not accepted +by Structured Outputs: + +- All object properties must be required. To express a field that can be absent + from the model's answer, make it nullable instead of using plain + `.optional()`. +- Zod runtime validation refinements and transforms are not sent to the API. + The SDK still uses your Zod schema to parse the returned JSON after the model + responds. +- TypeScript comments and arbitrary Zod metadata are not sent to the API. Use + `.describe()` on Zod fields, or the helper's `description` option, when you + want descriptions included in the generated JSON Schema. + ## Auto-parsing function tool calls The `.parse()` method will also automatically parse `function` tool calls if: