{"id":10433,"library":"zod-openapi","title":"Zod Schemas to OpenAPI Documentation Generator","description":"zod-openapi is a TypeScript library that transforms Zod schemas into OpenAPI v3.x documentation. It leverages Zod's native `.meta()` method to embed OpenAPI-specific metadata directly into your schemas, allowing you to generate comprehensive API specifications effortlessly. The current stable version is `5.4.6`, and the package is actively maintained with frequent patch releases addressing compatibility and bug fixes, alongside regular minor updates for new features and improvements.","status":"active","version":"5.4.6","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/samchungy/zod-openapi","tags":["javascript","typescript","json-schema","swagger","openapi","openapi3","zod","zod-openapi"],"install":[{"cmd":"npm install zod-openapi","lang":"bash","label":"npm"},{"cmd":"yarn add zod-openapi","lang":"bash","label":"yarn"},{"cmd":"pnpm add zod-openapi","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Importing any named export from 'zod-openapi' or a bare `import 'zod-openapi';` is necessary for TypeScript to recognize the OpenAPI-specific properties in Zod's `.meta()` method at compile-time.","wrong":"const { createDocument } = require('zod-openapi');","symbol":"createDocument","correct":"import { createDocument } from 'zod-openapi';"}],"quickstart":{"code":"import { z } from 'zod';\nimport { createDocument } from 'zod-openapi'; // This import enables .meta() type extensions\n\nconst userIdParam = z.string().uuid().meta({\n  param: {\n    name: 'userId',\n    in: 'path',\n    required: true,\n    description: 'Unique ID of the user',\n  },\n  example: 'a1b2c3d4-e5f6-7890-1234-567890abcdef',\n});\n\nconst userSchema = z.object({\n  id: z.string().uuid().meta({\n    description: 'Unique identifier for the user',\n    readOnly: true,\n  }),\n  name: z.string().min(1).max(100).meta({\n    description: 'Full name of the user',\n    example: 'John Doe',\n  }),\n  email: z.string().email().meta({\n    description: 'User\\'s email address',\n    example: 'john.doe@example.com',\n  }),\n}).meta({\n  id: 'User', // Registers this schema as a reusable OpenAPI component\n  description: 'Schema for a user object',\n});\n\nconst newUserSchema = userSchema.omit({ id: true }).meta({\n  id: 'NewUser',\n  description: 'Schema for creating a new user',\n});\n\nconst document = createDocument({\n  openapi: '3.0.0',\n  info: {\n    title: 'User Management API',\n    version: '1.0.0',\n    description: 'API for creating and retrieving users.',\n  },\n  paths: {\n    '/users': {\n      post: {\n        summary: 'Create a new user',\n        requestBody: {\n          content: {\n            'application/json': {\n              schema: newUserSchema,\n            },\n          },\n        },\n        responses: {\n          '201': {\n            description: 'User created successfully',\n            content: {\n              'application/json': {\n                schema: userSchema,\n              },\n            },\n          },\n        },\n      },\n    },\n    '/users/{userId}': {\n      get: {\n        summary: 'Get user by ID',\n        parameters: [userIdParam],\n        responses: {\n          '200': {\n            description: 'User details',\n            content: {\n              'application/json': {\n                schema: userSchema,\n              },\n            },\n          },\n          '404': {\n            description: 'User not found',\n          },\n        },\n      },\n    },\n  },\n  components: {\n    // Schemas with an 'id' in their meta property are automatically converted\n    // and can be referenced. Listing them here makes them explicit.\n    schemas: {\n      User: userSchema,\n      NewUser: newUserSchema\n    }\n  }\n});\n\nconsole.log(JSON.stringify(document, null, 2));","lang":"typescript","description":"This example demonstrates how to define Zod schemas with OpenAPI metadata for request parameters, request bodies, and responses using `.meta()`. It then generates a complete OpenAPI 3.x document that includes definitions for creating and retrieving users."},"warnings":[{"fix":"Use the `zodSchemas` property within the `CreateDocumentOptions.override` function instead of directly on `.meta().override`.","message":"The `zodSchemas` property was removed from the `.meta().override` option for Zod schemas.","severity":"breaking","affected_versions":">=5.3.0"},{"fix":"If the previous rendering behavior for `z.undefined()` is required, use the `override` option in `.meta()` to customize the OpenAPI schema output.","message":"The rendering of `z.undefined()` schemas changed to `{\"not\": {}}`.","severity":"breaking","affected_versions":">=5.2.0"},{"fix":"Ensure you are on the latest `zod-openapi` version (`5.4.6` or newer) to address known compatibility issues with recent Zod v4.x releases.","message":"Compatibility issues or crashes may occur when generating OpenAPI schemas for Zod versions `4.1.13+` or `4.3+`, particularly with discriminated unions or other complex Zod types.","severity":"gotcha","affected_versions":"5.4.0 - 5.4.5"},{"fix":"Add `import 'zod-openapi';` or `import { createDocument } from 'zod-openapi';` (or any other named import) to a relevant TypeScript file, typically where `createDocument` is called.","message":"To enable full TypeScript support for OpenAPI-specific properties (like `id`, `param`, `header`) within Zod's `.meta()` method, you must import `zod-openapi` somewhere in your project.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Update `zod-openapi` to version `5.4.3` or newer to resolve this specific TypeScript error.","cause":"Missing or incorrect TypeScript type declarations, potentially due to internal module resolution issues or version conflicts.","error":"TS2304: Cannot find name 'oas31_d_exports'."},{"fix":"Update `zod-openapi` to the latest patch version (e.g., `5.4.6` for Zod 4.3+ compatibility) to resolve known schema representation issues.","cause":"The structure or a specific Zod type within your schema is not correctly handled by `zod-openapi` for OpenAPI representation. This can occur with newer or complex Zod features.","error":"Error: Zod schema cannot be represented in OpenAPI"},{"fix":"Ensure `zod-openapi` is imported in your project (e.g., `import { createDocument } from 'zod-openapi';`) to enable type augmentation.","cause":"TypeScript is not aware of the OpenAPI-specific `.meta()` extensions provided by `zod-openapi`.","error":"Property 'param' does not exist on type 'ZodMeta<ZodTypeAny, any>'."},{"fix":"Update `zod-openapi` to version `5.4.4` or newer to fix issues related to discriminated union schema generation.","cause":"Generating OpenAPI schemas for discriminated union types with specific Zod versions (e.g., Zod 4.1.13+) could lead to runtime crashes in `zod-openapi`.","error":"TypeError: Cannot read properties of undefined (reading 'discriminator')"}],"ecosystem":"npm"}