Immutable solution version
Express/Next.js: enforce JSON shape with zodTextFormat
Complete solution
The Node SDK's parse path needs the zod helper wired into text.format, and the zod schema has to be strict-compatible. This skill covers the exact wiring and the optional-field rule that causes 400s.
Structured outputs in Node via zodTextFormat
Same guarantee as Python, different wiring. Verified against the structured outputs guide on 2026-09-26.
The call
import OpenAI from "openai";
import { zodTextFormat } from "openai/helpers/zod";
import { z } from "zod";
const openai = new OpenAI();
const CalendarEvent = z.object({
name: z.string(),
date: z.string(),
participants: z.array(z.string()),
});
const response = await openai.responses.parse({
model: "...",
input: "Alice and Bob are going to a science fair on Friday.",
text: { format: zodTextFormat(CalendarEvent, "event") },
});
const event = response.output_parsed;The optional-field trap
Strict schemas require every key to be present or explicitly nullable. In zod that means: do not use .optional() and expect it to pass. Use z.string().nullable() for fields the model may omit, or give the field a .default(). The 400 you get otherwise says the schema is invalid, not that the model misbehaved; the fix is in your zod object, not the prompt.
The naming trap
zodTextFormat takes a name as the second argument. Reuse the same name for the same shape across deploys; the name becomes part of the schema identity in logs and traces, and renaming it per request makes debugging harder.
Check before you ship
In an Express route,
res.json(response.output_parsed); in a Next.js route handler,Response.json(response.output_parsed). No manual JSON.parse anywhere.Handle parse refusal errors explicitly; the helper throws instead of returning partial JSON.
Evidence
OpenAI's structured outputs guide documents openai.responses.parse with text.format set via zodTextFormat(Schema, name) and the response.output_parsed accessor, with strict JSON Schema rules applied to the generated schema.
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_QPV1L6D5aj6JHKQrKyMYNg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Express/Next.js: enforce JSON shape with zodTextFormat <span>— Vectle</span></a>