Implementation:Openai Openai node Zod ParseDef

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

Overview

The parseDef function is the central dispatch hub of the vendored zod-to-json-schema converter, routing each Zod type definition to its specialized parser and managing schema references, caching, and metadata.

Description

The parseDef function is the core of the Zod-to-JSON-Schema conversion pipeline. Given any ZodTypeDef, it determines the appropriate type-specific parser to invoke and returns the resulting JsonSchema7Type. It handles over 30 Zod types through the internal selectParser switch statement, including strings, numbers, objects, arrays, unions, intersections, tuples, records, literals, enums, nullable, optional, maps, sets, lazy types, promises, effects, branded types, readonly types, catch, pipeline, and more.

Before dispatching to a parser, the function checks a seen cache to detect and handle circular or repeated references. When a previously seen definition is encountered, it generates a $ref reference according to the configured strategy (root, extract-to-root, relative, none, or seen). The extract-to-root strategy is particularly important for OpenAI's strict mode, which does not support top-level $refs -- instead, schemas are extracted to a #/definitions/ section. An optional override callback in the refs allows callers to intercept and customize the conversion of any definition.

After the type-specific parser produces a JSON Schema fragment, the addMeta helper enriches it with Zod description metadata (including an optional markdownDescription field). The module also exports the JsonSchema7Type union type, which encompasses all possible JSON Schema 7 type representations, and the JsonSchema7TypeUnion for the raw union without metadata.

Usage

This function is called by zodToJsonSchema as the primary conversion engine and recursively by individual type parsers (e.g., the object parser calls parseDef for each property, the union parser calls it for each option). It is not typically invoked directly by SDK consumers.

Code Reference

Source Location

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

Signature

export function parseDef(
  def: ZodTypeDef,
  refs: Refs,
  forceResolution?: boolean,
): JsonSchema7Type | undefined;

export type JsonSchema7TypeUnion =
  | JsonSchema7StringType
  | JsonSchema7ArrayType
  | JsonSchema7NumberType
  | JsonSchema7BigintType
  | JsonSchema7BooleanType
  | JsonSchema7DateType
  | JsonSchema7EnumType
  | JsonSchema7LiteralType
  | JsonSchema7NativeEnumType
  | JsonSchema7NullType
  | JsonSchema7ObjectType
  | JsonSchema7RecordType
  | JsonSchema7TupleType
  | JsonSchema7UnionType
  | JsonSchema7UndefinedType
  | JsonSchema7RefType
  | JsonSchema7NeverType
  | JsonSchema7MapType
  | JsonSchema7AnyType
  | JsonSchema7NullableType
  | JsonSchema7AllOfType
  | JsonSchema7UnknownType
  | JsonSchema7SetType;

export type JsonSchema7Type = JsonSchema7TypeUnion & {
  title?: string;
  default?: any;
  description?: string;
  markdownDescription?: string;
};

Import

import OpenAI from 'openai';

I/O Contract

Inputs

Name	Type	Required	Description
def	ZodTypeDef	Yes	Any Zod type definition object (e.g., from schema._def).
refs	Refs	Yes	Conversion context containing seen cache, currentPath, $refStrategy, override, target, definitions, and other configuration.
forceResolution	boolean	No	When true, bypasses the seen cache and forces a fresh schema generation. Defaults to false.

Outputs

Name	Type	Description
result	undefined	The JSON Schema 7 representation of the Zod type, or undefined for unsupported types (e.g., ZodFunction, ZodVoid, ZodSymbol).

Usage Examples

// parseDef is used internally by zodToJsonSchema.
// Here is how it fits into the conversion pipeline:

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

const UserSchema = z.object({
  name: z.string().describe('The user name'),
  age: z.number().int().positive(),
  tags: z.array(z.string()),
  role: z.enum(['admin', 'user', 'guest']),
});

// zodResponseFormat calls zodToJsonSchema, which calls parseDef for:
// 1. The top-level ZodObject -> parseObjectDef
//    2. name: ZodString -> parseStringDef
//    3. age: ZodNumber -> parseNumberDef
//    4. tags: ZodArray -> parseArrayDef
//       5. ZodString (element type) -> parseStringDef
//    6. role: ZodEnum -> parseEnumDef
const format = zodResponseFormat(UserSchema, 'user_info');

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime