zod-to-openai-schema

Convert Zod schemas to OpenAI function calling compatible JSON Schema. This library helps you define your OpenAI function parameters using Zod's powerful schema definition system.

Developed by Techery.

Features

• Convert Zod schemas to OpenAI-compatible JSON Schema
• Preserves property descriptions and structure
• Full TypeScript support
• Zero dependencies (except Zod)

Type Compatibility

| Zod Type | OpenAI Schema Type | Notes | |----------|-------------------|-------| | z.string() | string | Basic string type | | z.number() | number | Floating point numbers | | z.number().int() | integer | Integer numbers | | z.boolean() | boolean | Boolean values | | z.enum([...]) | string | With enum: [...] | | z.object({...}) | object | With properties and required | | z.array(...) | array | With items schema | | z.union([...]) | N/A | Converted to anyOf: [...] | | z.discriminatedUnion(...) | N/A | Converted to anyOf: [...] | | z.literal(string) | string | With enum: [value] | | z.null() | string | With enum: [null] | | someSchema.nullable() | Same as base | With type: ['type', 'null'] | | z.lazy(...) | Supported | Using $ref and $defs |

Installation

npm install zod-to-openai-schema
# or
yarn add zod-to-openai-schema
# or
pnpm add zod-to-openai-schema

Usage

Basic Example

import { z } from 'zod';
import { zodToOpenAISchema } from 'zod-to-openai-schema';

const schema = z.object({
  name: z.string().describe('The name of the person'),
  age: z.number(),
  email: z.string().email(),
});

const jsonSchema = zodToOpenAISchema(schema);

// Resulting OpenAI schema:
{
  type: "object",
  properties: {
    name: { 
      type: "string",
      description: "The name of the person"
    },
    age: { type: "number" },
    email: { type: "string" }
  },
  required: ["name", "age", "email"],
  additionalProperties: false
}

Using with OpenAI Function Calling

import { z } from 'zod';
import { zodToOpenAISchema } from 'zod-to-openai-schema';
import OpenAI from 'openai';

const createTodoSchema = z.object({
  title: z.string().describe('The title of the todo item'),
  priority: z.enum(['low', 'medium', 'high']).describe('Priority level'),
  dueDate: z.string().describe('Due date in ISO format'),
});

const openai = new OpenAI();

const completion = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Create a high priority todo for reviewing code tomorrow' }],
  functions: [
    {
      name: 'createTodo',
      description: 'Create a new todo item',
      parameters: zodToOpenAISchema(createTodoSchema),
    },
  ],
});

Advanced Examples

Recursive Types with References

import { z } from 'zod';
import { zodToOpenAISchema, definition } from 'zod-to-openai-schema';

// Define a recursive comment schema
const commentSchema: z.ZodType<any> = z.lazy(() => 
  z.object({
    text: z.string(),
    replies: z.array(commentSchema)
  })
);

const schema = z.object({
  post: z.object({
    title: z.string(),
    content: z.string(),
  }),
  comments: z.array(commentSchema)
});

const jsonSchema = zodToOpenAISchema(schema);

// Resulting schema will use $ref and $defs for recursive types

Reusable Types with Named Definitions

const todoItemSchema = z.object({
  name: z.string(),
  completed: z.boolean(),
});

const schema = z.object({
  pending: z.array(todoItemSchema),
  completed: z.array(todoItemSchema),
});

const jsonSchema = zodToOpenAISchema(schema, {
  definitions: [definition('TodoItem', todoItemSchema)],
});

// Resulting schema will use $ref: "#/$defs/TodoItem"

Supported Features

• Basic Types:

  • string
  • number (with int() support)
  • boolean

• Complex Types:

  • Objects (z.object())
  • Arrays (z.array())
  • Enums (z.enum())
  • Unions (z.union())
  • Discriminated Unions (z.discriminatedUnion())
  • Literals (z.literal())
  • Recursive types (using z.lazy())

• Modifiers:

  • Nullable fields (nullable())
  • References ($ref and $defs)

• Metadata:

  • Description preservation
  • Custom type definitions

Limitations

• Optional fields are not supported (OpenAI requires explicit handling of optional fields)
• Some Zod types are not supported:
  • z.any()
  • z.never()
  • z.intersection()
  • z.tuple()
  • z.record()
• Validation constraints (min, max, regex, etc.) are not included in the output schema

API Reference

zodToOpenAISchema(schema: z.ZodTypeAny, config?: Config): OpenAIStructuredOutputSchema

Converts a Zod schema into an OpenAI-compatible JSON Schema.

Config Options

interface Config {
  definitions?: Definition[];
}

interface Definition {
  name: string;
  schema: z.ZodObject<any>;
}

definition(name: string, schema: z.ZodObject<any>): Definition

Helper function to create named type definitions for reuse.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Authors

• Serge Zenchenko - CTO at Techery

License

MIT