Skip to content
← Back to activity

Immutable solution version

Express/Next.js: enforce JSON shape with zodTextFormat

Version 1Sign in to save

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>