Implementation:Openai Openai node ZodResponseFormat

Knowledge Sources	openai-node OpenAI Structured Outputs
Domains	Schema_Validation, NLP
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for creating auto-parseable response format objects from Zod schemas provided by the openai-node SDK.

Description

The zodResponseFormat function creates an AutoParseableResponseFormat for the Chat Completions API, and zodTextFormat creates an AutoParseableTextFormat for the Responses API. Both convert a Zod schema to JSON Schema, wrap it in the appropriate format object, and attach a $parseRaw method for automatic response parsing.

The function supports both Zod v3 and Zod v4 schemas transparently, detecting the version via the _zod property.

Usage

Use zodResponseFormat when calling client.chat.completions.parse() or client.chat.completions.stream() with structured output. Use zodTextFormat when calling client.responses.parse() with the Responses API.

Code Reference

Source Location

• Repository: openai-node
• File: src/helpers/zod.ts
• Lines: L82-116 (zodResponseFormat: L82-99, zodTextFormat: L101-116)

Signature

export function zodResponseFormat<ZodInput extends z3.ZodType | z4.ZodType>(
  zodObject: ZodInput,
  name: string,
  props?: Omit<ResponseFormatJSONSchema.JSONSchema, 'schema' | 'strict' | 'name'>,
): AutoParseableResponseFormat<InferZodType<ZodInput>>;

export function zodTextFormat<ZodInput extends z3.ZodType | z4.ZodType>(
  zodObject: ZodInput,
  name: string,
  props?: Omit<ResponseFormatTextJSONSchemaConfig, 'schema' | 'type' | 'strict' | 'name'>,
): AutoParseableTextFormat<InferZodType<ZodInput>>;

Import

import { zodResponseFormat, zodTextFormat } from 'openai/helpers/zod';

I/O Contract

Inputs

Name	Type	Required	Description
zodObject	ZodType (v3 or v4)	Yes	Zod schema defining the expected output shape
name	string	Yes	Schema name (sent to the API as the schema identifier)
props	object	No	Additional JSON Schema properties (description, etc.)

Outputs

Name	Type	Description
(zodResponseFormat)	AutoParseableResponseFormat<T>	Format object for Chat Completions response_format parameter with $parseRaw method
(zodTextFormat)	AutoParseableTextFormat<T>	Format object for Responses API text.format parameter with $parseRaw method

Usage Examples

Chat Completions with zodResponseFormat

import { z } from 'zod';
import OpenAI from 'openai';
import { zodResponseFormat } from 'openai/helpers/zod';

const client = new OpenAI();

const MathAnswer = z.object({
  steps: z.array(z.object({
    explanation: z.string(),
    answer: z.string(),
  })),
  final_answer: z.string(),
});

const completion = await client.chat.completions.parse({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a math tutor.' },
    { role: 'user', content: 'Solve 8x + 31 = 2' },
  ],
  response_format: zodResponseFormat(MathAnswer, 'math_answer'),
});

// completion.choices[0].message.parsed is typed as MathAnswer
console.log(completion.choices[0].message.parsed?.final_answer);

Responses API with zodTextFormat

import { z } from 'zod';
import OpenAI from 'openai';
import { zodTextFormat } from 'openai/helpers/zod';

const client = new OpenAI();

const Person = z.object({ name: z.string(), age: z.number() });

const response = await client.responses.parse({
  model: 'gpt-4o',
  input: 'Extract: John is 30 years old.',
  text: { format: zodTextFormat(Person, 'person') },
});

console.log(response.output_parsed); // { name: 'John', age: 30 }

Related Pages

Implements Principle

• Principle:Openai_Openai_node_Response_Format_Configuration