Implementation:Openai Openai node Zod String Parser

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

Overview

The Zod String Parser converts Zod string schema definitions (including all validation checks) into their equivalent JSON Schema 7 representation.

Description

The parseStringDef function is a specialized parser within the vendored zod-to-json-schema conversion library. It takes a ZodStringDef and translates every Zod string validation check into the corresponding JSON Schema constraints. This includes min/max length mapping to minLength/maxLength, format validations (email, URL, UUID, datetime, date, time, duration, IPv4, IPv6) mapping to the format keyword, and pattern-based checks (regex, cuid, cuid2, ulid, nanoid, base64, emoji, startsWith, endsWith, includes) mapping to the pattern keyword.

The module handles complex scenarios where multiple formats or patterns are present on a single schema. When a second format is added, the existing format is moved into an anyOf array; similarly, multiple patterns are collected into an allOf array. The zodPatterns constant exports pre-compiled regular expressions that replicate Zod's built-in validation patterns, with modifications to accommodate the lack of regex flags in JSON Schema (e.g., replacing /i flag with explicit case ranges).

The processRegExp helper function performs sophisticated regex flag translation when applyRegexFlags is enabled in the refs configuration. It walks through regex source characters, expanding case-insensitive (i), multiline (m), and dotall (s) flags into equivalent flag-independent patterns. The email strategy is configurable (format:email, format:idn-email, or pattern:zod), and the base64 strategy supports format:binary, contentEncoding:base64, or pattern:zod modes.

Usage

This parser is invoked automatically by the central parseDef dispatch function whenever a ZodString type is encountered during schema conversion. It is part of the internal zod-to-json-schema pipeline used by zodResponseFormat and zodFunction to generate JSON Schema for OpenAI's structured output and function calling features.

Code Reference

Source Location

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

Signature

export function parseStringDef(def: ZodStringDef, refs: Refs): JsonSchema7StringType;

export const zodPatterns: {
  cuid: RegExp;
  cuid2: RegExp;
  ulid: RegExp;
  email: RegExp;
  emoji: () => RegExp;
  uuid: RegExp;
  ipv4: RegExp;
  ipv6: RegExp;
  base64: RegExp;
  nanoid: RegExp;
};

export type JsonSchema7StringType = {
  type: 'string';
  minLength?: number;
  maxLength?: number;
  format?: string;
  pattern?: string;
  allOf?: { pattern: string; errorMessage?: ErrorMessages }[];
  anyOf?: { format: string; errorMessage?: ErrorMessages }[];
  errorMessage?: ErrorMessages;
  contentEncoding?: string;
};

Import

import OpenAI from 'openai';

I/O Contract

Inputs

Name	Type	Required	Description
def	ZodStringDef	Yes	The Zod string definition object, containing an array of checks representing validations.
refs	Refs	Yes	Conversion context including emailStrategy, base64Strategy, patternStrategy, applyRegexFlags, errorMessages, and currentPath.

Outputs

Name	Type	Description
type	'string'	Always 'string'.
minLength	number	Minimum string length constraint.
maxLength	number	Maximum string length constraint.
format	string	JSON Schema format keyword (e.g., 'email', 'uri', 'uuid').
pattern	string	Regular expression pattern constraint.
allOf	Array<{ pattern: string }>	Multiple pattern constraints combined via allOf.
anyOf	Array<{ format: string }>	Multiple format constraints combined via anyOf.
contentEncoding	string	Content encoding (e.g., 'base64').

Usage Examples

// The string parser is invoked internally during zodToJsonSchema conversion.
// Example: a Zod string schema with multiple checks produces the following JSON Schema.

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

const schema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  website: z.string().url(),
  id: z.string().uuid(),
});

// When passed to zodResponseFormat, the string parser converts each field:
// email  -> { type: 'string', format: 'email' }
// name   -> { type: 'string', minLength: 1, maxLength: 100 }
// website -> { type: 'string', format: 'uri' }
// id     -> { type: 'string', format: 'uuid' }
const responseFormat = zodResponseFormat(schema, 'contact_info');

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime