{"id":26641567,"url":"https://github.com/techery/zod-to-openai-schema","last_synced_at":"2026-02-06T05:32:45.685Z","repository":{"id":272656681,"uuid":"917353867","full_name":"techery/zod-to-openai-schema","owner":"techery","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-17T13:01:04.000Z","size":61,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-11T13:51:38.948Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/techery.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-15T20:28:52.000Z","updated_at":"2025-01-17T12:58:38.000Z","dependencies_parsed_at":"2025-01-15T22:26:49.498Z","dependency_job_id":"d0f07c99-d797-4196-ad5e-47dec69a1489","html_url":"https://github.com/techery/zod-to-openai-schema","commit_stats":null,"previous_names":["techery/zod-to-openai-schema"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/techery/zod-to-openai-schema","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techery%2Fzod-to-openai-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techery%2Fzod-to-openai-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techery%2Fzod-to-openai-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techery%2Fzod-to-openai-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/techery","download_url":"https://codeload.github.com/techery/zod-to-openai-schema/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techery%2Fzod-to-openai-schema/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29152426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T02:39:25.012Z","status":"ssl_error","status_checked_at":"2026-02-06T02:37:22.784Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-24T18:32:22.716Z","updated_at":"2026-02-06T05:32:45.669Z","avatar_url":"https://github.com/techery.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zod-to-openai-schema\n\n[![npm version](https://badge.fury.io/js/@techery%2Fzod-to-openai-schema.svg)](https://www.npmjs.com/package/@techery/zod-to-openai-schema)\n![CI Status](https://github.com/techery/zod-to-openai-schema/actions/workflows/pr-checks.yml/badge.svg?branch=main)\n\nConvert [Zod](https://github.com/colinhacks/zod) schemas to [OpenAI function calling](https://platform.openai.com/docs/guides/function-calling) compatible JSON Schema. This library helps you define your OpenAI function parameters using Zod's powerful schema definition system.\n\nDeveloped by [Techery](https://techery.io).\n\n## Features\n- Convert Zod schemas to OpenAI-compatible JSON Schema\n- Preserves property descriptions and structure\n- Full TypeScript support\n- Zero dependencies (except Zod)\n\n## Type Compatibility\n\n| Zod Type | OpenAI Schema Type | Notes |\n|----------|-------------------|-------|\n| `z.string()` | `string` | Basic string type |\n| `z.number()` | `number` | Floating point numbers |\n| `z.number().int()` | `integer` | Integer numbers |\n| `z.boolean()` | `boolean` | Boolean values |\n| `z.enum([...])` | `string` | With `enum: [...]` |\n| `z.object({...})` | `object` | With `properties` and `required` |\n| `z.array(...)` | `array` | With `items` schema |\n| `z.union([...])` | N/A | Converted to `anyOf: [...]` |\n| `z.discriminatedUnion(...)` | N/A | Converted to `anyOf: [...]` |\n| `z.literal(string)` | `string` | With `enum: [value]` |\n| `z.null()` | `string` | With `enum: [null]` |\n| `someSchema.nullable()` | Same as base | With `type: ['type', 'null']` |\n| `z.lazy(...)` | Supported | Using `$ref` and `$defs` |\n\n## Installation\n\n```bash\nnpm install zod-to-openai-schema\n# or\nyarn add zod-to-openai-schema\n# or\npnpm add zod-to-openai-schema\n```\n\n## Usage\n\n### Basic Example\n\n```typescript\nimport { z } from 'zod';\nimport { zodToOpenAISchema } from 'zod-to-openai-schema';\n\nconst schema = z.object({\n  name: z.string().describe('The name of the person'),\n  age: z.number(),\n  email: z.string().email(),\n});\n\nconst jsonSchema = zodToOpenAISchema(schema);\n\n// Resulting OpenAI schema:\n{\n  type: \"object\",\n  properties: {\n    name: { \n      type: \"string\",\n      description: \"The name of the person\"\n    },\n    age: { type: \"number\" },\n    email: { type: \"string\" }\n  },\n  required: [\"name\", \"age\", \"email\"],\n  additionalProperties: false\n}\n```\n\n### Using with OpenAI Function Calling\n\n```typescript\nimport { z } from 'zod';\nimport { zodToOpenAISchema } from 'zod-to-openai-schema';\nimport OpenAI from 'openai';\n\nconst createTodoSchema = z.object({\n  title: z.string().describe('The title of the todo item'),\n  priority: z.enum(['low', 'medium', 'high']).describe('Priority level'),\n  dueDate: z.string().describe('Due date in ISO format'),\n});\n\nconst openai = new OpenAI();\n\nconst completion = await openai.chat.completions.create({\n  model: 'gpt-4',\n  messages: [{ role: 'user', content: 'Create a high priority todo for reviewing code tomorrow' }],\n  functions: [\n    {\n      name: 'createTodo',\n      description: 'Create a new todo item',\n      parameters: zodToOpenAISchema(createTodoSchema),\n    },\n  ],\n});\n```\n\n### Advanced Examples\n\n#### Recursive Types with References\n\n```typescript\nimport { z } from 'zod';\nimport { zodToOpenAISchema, definition } from 'zod-to-openai-schema';\n\n// Define a recursive comment schema\nconst commentSchema: z.ZodType\u003cany\u003e = z.lazy(() =\u003e \n  z.object({\n    text: z.string(),\n    replies: z.array(commentSchema)\n  })\n);\n\nconst schema = z.object({\n  post: z.object({\n    title: z.string(),\n    content: z.string(),\n  }),\n  comments: z.array(commentSchema)\n});\n\nconst jsonSchema = zodToOpenAISchema(schema);\n\n// Resulting schema will use $ref and $defs for recursive types\n```\n\n#### Reusable Types with Named Definitions\n\n```typescript\nconst todoItemSchema = z.object({\n  name: z.string(),\n  completed: z.boolean(),\n});\n\nconst schema = z.object({\n  pending: z.array(todoItemSchema),\n  completed: z.array(todoItemSchema),\n});\n\nconst jsonSchema = zodToOpenAISchema(schema, {\n  definitions: [definition('TodoItem', todoItemSchema)],\n});\n\n// Resulting schema will use $ref: \"#/$defs/TodoItem\"\n```\n\n## Supported Features\n\n- Basic Types:\n  - `string`\n  - `number` (with `int()` support)\n  - `boolean`\n  \n- Complex Types:\n  - Objects (`z.object()`)\n  - Arrays (`z.array()`)\n  - Enums (`z.enum()`)\n  - Unions (`z.union()`)\n  - Discriminated Unions (`z.discriminatedUnion()`)\n  - Literals (`z.literal()`)\n  - Recursive types (using `z.lazy()`)\n\n- Modifiers:\n  - Nullable fields (`nullable()`)\n  - References (`$ref` and `$defs`)\n\n- Metadata:\n  - Description preservation\n  - Custom type definitions\n\n## Limitations\n\n- Optional fields are not supported (OpenAI requires explicit handling of optional fields)\n- Some Zod types are not supported:\n  - `z.any()`\n  - `z.never()`\n  - `z.intersection()`\n  - `z.tuple()`\n  - `z.record()`\n- Validation constraints (min, max, regex, etc.) are not included in the output schema\n\n## API Reference\n\n### `zodToOpenAISchema(schema: z.ZodTypeAny, config?: Config): OpenAIStructuredOutputSchema`\n\nConverts a Zod schema into an OpenAI-compatible JSON Schema.\n\n#### Config Options\n```typescript\ninterface Config {\n  definitions?: Definition[];\n}\n\ninterface Definition {\n  name: string;\n  schema: z.ZodObject\u003cany\u003e;\n}\n```\n\n### `definition(name: string, schema: z.ZodObject\u003cany\u003e): Definition`\n\nHelper function to create named type definitions for reuse.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Authors\n\n- [Serge Zenchenko](https://github.com/sergezenchenko) - CTO at [Techery](https://techery.io)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechery%2Fzod-to-openai-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechery%2Fzod-to-openai-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechery%2Fzod-to-openai-schema/lists"}