Implementation:Openai Openai node ZodToJsonSchema Entry

Knowledge Sources	Openai_Openai_node
Domains	SDK, Schema_Conversion, Validation
Last Updated	2026-02-15 12:00 GMT

Overview

The zodToJsonSchema function is the top-level entry point for converting a Zod schema into a JSON Schema document, supporting multiple JSON Schema draft targets and configurable definition strategies.

Description

The zodToJsonSchema function accepts a ZodSchema and an optional configuration (either a string name or a Partial<Options<Target>> object) and returns a complete JSON Schema document. It initializes the conversion context via getRefs, delegates to parseDef for the core type conversion, and then assembles the final output including $schema metadata and any accumulated definitions.

The function supports two JSON Schema targets: jsonSchema7 (draft-07, the default) and jsonSchema2019-09 (draft 2019-09), each producing the appropriate $schema URL. When a name is provided, the function controls how the root schema and its definitions are organized. With the duplicate-ref name strategy, the main schema is placed both at the top level and duplicated under definitions (but only if it was actually referenced, avoiding unnecessary duplication). With the default strategy, a top-level $ref points to the named definition.

A critical design feature is the iterative definition resolution loop: calling parseDef may itself add new entries to refs.definitions (e.g., when the extract-to-root ref strategy extracts nested schemas). The function iterates up to 500 times, processing newly discovered definitions each round until all are resolved. This is essential for supporting deeply nested or self-referential schemas used with OpenAI's structured output feature, which requires all $refs to be resolved to #/definitions/.

Usage

This function is called internally by zodResponseFormat and zodFunction to convert Zod schemas into JSON Schema for OpenAI's structured output and function calling features. It can also be called directly when a raw JSON Schema conversion is needed.

Code Reference

Source Location

• Repository: openai-node
• File: src/_vendor/zod-to-json-schema/zodToJsonSchema.ts

Signature

const zodToJsonSchema: <Target extends Targets = 'jsonSchema7'>(
  schema: ZodSchema<any>,
  options?: Partial<Options<Target>> | string,
) => (Target extends 'jsonSchema7' ? JsonSchema7Type : object) & {
  $schema?: string;
  definitions?: {
    [key: string]: JsonSchema7Type | object;
  };
};

Import

import OpenAI from 'openai';

I/O Contract

Inputs

Name	Type	Required	Description
schema	ZodSchema<any>	Yes	The Zod schema to convert to JSON Schema.
options	string	No	Configuration options or a string name for the schema. Options include name, nameStrategy, target, $refStrategy, basePath, definitionPath, emailStrategy, base64Strategy, and more.

Outputs

Name	Type	Description
$schema	string	The JSON Schema version URI (e.g., 'http://json-schema.org/draft-07/schema#').
type	string	The top-level schema type (e.g., 'object').
properties	Record<string, JsonSchema7Type>	Property schemas (for object types).
definitions	Record<string, JsonSchema7Type>	Extracted definition schemas for $ref resolution.
$ref	string	Reference pointer when using named schema mode (non-duplicate-ref strategy).

Usage Examples

// zodToJsonSchema is used internally by zodResponseFormat and zodFunction.
// It can also be used directly for schema conversion:

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

const ResponseSchema = z.object({
  answer: z.string().describe('The answer to the question'),
  confidence: z.number().min(0).max(1),
  sources: z.array(z.object({
    title: z.string(),
    url: z.string().url(),
  })),
});

// zodResponseFormat internally calls zodToJsonSchema to produce:
// {
//   type: 'object',
//   properties: {
//     answer: { type: 'string', description: 'The answer to the question' },
//     confidence: { type: 'number', minimum: 0, maximum: 1 },
//     sources: {
//       type: 'array',
//       items: {
//         type: 'object',
//         properties: {
//           title: { type: 'string' },
//           url: { type: 'string', format: 'uri' }
//         }
//       }
//     }
//   },
//   $schema: 'http://json-schema.org/draft-07/schema#'
// }
const format = zodResponseFormat(ResponseSchema, 'research_answer');

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime