zod-openapi 5.0.0-beta.15 → 5.0.0-beta.17

package/README.md

@@ -3,7 +3,7 @@
   <h1 align="center">zod-openapi</h1>
 </p>
 <p align="center">
-A TypeScript library which uses <a href="https://github.com/colinhacks/zod">Zod</a> schemas to generate OpenAPI v3.x documentation.
+A TypeScript library which uses <a href="https://github.com/colinhacks/zod">Zod</a> schemas to generate OpenAPI v3.1x documentation.
 </p>
 <div align="center">
 <a href="https://www.npmjs.com/package/zod-openapi"><img src="https://img.shields.io/npm/v/zod-openapi"/></a>
@@ -31,33 +31,41 @@ pnpm install zod zod-openapi
 
 ### `.meta()`
 
-Use the `.meta()` method to add metadata to a Zod schema. It accepts an object with the following options:
+Use the `.meta()` method to add OpenAPI metadata to a Zod schema. It accepts an object with the following options:
 
 | Option     | Description                                                                                                      |
 | ---------- | ---------------------------------------------------------------------------------------------------------------- |
 | `id`       | Registers a schema as a reusable OpenAPI component.                                                              |
 | `header`   | Adds metadata for [response headers](#response-headers).                                                         |
 | `param`    | Adds metadata for [request parameters](#parameters).                                                             |
-| `override` | Allows you to override the rendered OpenAPI schema. This takes either an object or a function                    |
+| `override` | Allows you to override the rendered OpenAPI schema. This takes either an object or a function.                   |
 | `outputId` | Allows you to set a different ID for the output schema. This is useful when the input and output schemas differ. |
-| `unusedIO` | Allows you to set the `io` for an unused schema added to the components section. Defaults to `output`            |
+| `unusedIO` | Allows you to set the `io` for an unused schema added to the components section. Defaults to `output`.           |
+
+You can also set standard OpenAPI properties directly in the `.meta()` method, such as:
+
+```typescript
+z.string().meta({
+  description: 'A text field',
+  example: 'Example value',
+});
+```
 
 ### `createDocument`
 
 Generates an OpenAPI documentation object.
 
 ```typescript
-import 'zod-openapi/extend';
-import { z } from 'zod/v4';
+import { z } from 'zod';
 import { createDocument } from 'zod-openapi';
 
-const jobId = z.string().openapi({
+const jobId = z.string().meta({
   description: 'A unique identifier for a job',
   example: '12345',
   id: 'jobId',
 });
 
-const title = z.string().openapi({
+const title = z.string().meta({
   description: 'Job title',
   example: 'My job',
 });
@@ -170,37 +178,45 @@ const document = createDocument({
   ```
 </details>
 
-#### CreateDocumentOptions
-
-`createDocument` takes an optional `CreateDocumentOptions` argument which can be used to modify how the document is created.
+`createDocument` takes an optional options argument which can be used to modify how the document is created
 
 ```typescript
-const document = createDocument(details, {
-  override: ({ jsonSchema, zodSchema }) => {
-    if (jsonSchema.anyOf) {
-      ctx.jsonSchema.oneOf = ctx.jsonSchema.anyOf;
-      delete ctx.jsonSchema.anyOf;
+createDocument(doc, {
+  override: ({ jsonSchema, zodSchema, io }) => {
+    // Customize the schema generation
+    if (io === 'output') {
+      jsonSchema.type = 'string';
     }
   },
 });
 ```
 
+#### CreateDocumentOptions
+
+| Option             | Type                | Default                   | Description                                                                                                       |
+| ------------------ | ------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `override`         | `Function`          | `undefined`               | Override rendered schema with a function``                                                                        |
+| `outputIdSuffix`   | `string`            | `'Output'`                | Suffix for output schema IDs when the schema is used in both a request and response                               |
+| `allowEmptySchema` | `boolean \| Object` | `false`                   | Control whether empty schemas are allowed.                                                                        |
+| `cycles`           | `'ref' \| 'throw'`  | `'ref'`                   | How to handle cycles in schemas.<br>- `'ref'` — Break cycles using $defs<br>- `'throw'` — Error on cycles         |
+| `reused`           | `'ref' \| 'inline'` | `'inline'`                | How to handle reused schemas.<br>- `'ref'` — Reused schemas as references<br>- `'inline'` — Inline reused schemas |
+| `schemaRefPath`    | `string`            | `'#/components/schemas/'` | Path prefix for schema references. Used when generating $ref values.                                              |
+
 ### `createSchema`
 
 Creates an OpenAPI Schema Object along with any registered components. OpenAPI 3.1.0 Schema Objects are fully compatible with JSON Schema.
 
 ```typescript
-import 'zod-openapi/extend';
-import { z } from 'zod/v4';
+import { z } from 'zod';
 import { createSchema } from 'zod-openapi';
 
-const jobId = z.string().openapi({
+const jobId = z.string().meta({
   description: 'A unique identifier for a job',
   example: '12345',
   id: 'jobId',
 });
 
-const title = z.string().openapi({
+const title = z.string().meta({
   description: 'Job title',
   example: 'My job',
 });
@@ -245,16 +261,17 @@ const { schema, components } = createSchema(job);
 
 #### CreateSchemaOptions
 
-`createSchema` takes an optional `CreateSchemaOptions` parameter which can also take the same options as [CreateDocumentOptions](#createdocumentoptions) along with the following options:
+`createSchema` takes an optional `CreateSchemaOptions` parameter which includes all options from [CreateDocumentOptions](#createdocumentoptions) plus the following:
 
-```typescript
+````typescript
 const { schema, components } = createSchema(job, {
-  schemaType: 'input'; // This controls whether this should be rendered as a request (`input`) or response (`output`). Defaults to `output`
-  openapi: '3.0.0'; // OpenAPI version to use, defaults to `'3.1.0'`
-  components: { jobId: z.string() } // Additional components to use and create while rendering the schema
-  componentRefPath: '#/definitions/' // Defaults to #/components/schemas/
-})
-```
+  // Input/Output context - controls how schemas are generated
+  io: 'input', // 'input' for request bodies/params, 'output' for responses
+
+  // Component handling
+  schemaComponents: { jobId: z.string() }, // Pre-defined components to use
+  schemaComponentRefPath: '#/definitions/', // Custom path prefix for component references
+});
 
 ### Request Parameters
 
@@ -275,7 +292,7 @@ createDocument({
     },
   },
 });
-```
+````
 
 If you would like to declare parameters in a more traditional way you may also declare them using the [parameters](https://swagger.io/docs/specification/describing-parameters/) key. The definitions will then all be combined.
 
@@ -285,7 +302,7 @@ createDocument({
     '/jobs/{a}': {
       put: {
         parameters: [
-          z.string().openapi({
+          z.string().meta({
             param: {
               name: 'job-header',
               in: 'header',
@@ -396,7 +413,7 @@ If we take the example in `createDocument` and instead create `title` as follows
 ##### Auto Registering Schema
 
 ```typescript
-const title = z.string().openapi({
+const title = z.string().meta({
   description: 'Job title',
   example: 'My job',
   id: 'jobTitle', // <- new field
@@ -434,14 +451,14 @@ Another way to register schema instead of adding a `ref` is to add it to the com
 eg.
 
 ```typescript
-const title = z.string().openapi({
+const title = z.string().meta({
   description: 'Job title',
   example: 'My job',
 });
 createDocument({
   components: {
     schemas: {
-      jobTitle: title, // this will register this Zod Schema as jobTitle unless `ref` in `.openapi()` is specified on the type
+      jobTitle: title, // this will register this Zod Schema as jobTitle unless `id` in `.meta()` is specified on the type
     },
   },
 });
@@ -453,7 +470,7 @@ Query, Path, Header & Cookie parameters can be similarly registered:
 
 ```typescript
 // Easy auto registration
-const jobId = z.string().openapi({
+const jobId = z.string().meta({
   description: 'Job ID',
   example: '1234',
   param: { id: 'jobRef' },
@@ -474,7 +491,7 @@ createDocument({
 });
 
 // or more verbose auto registration
-const jobId = z.string().openapi({
+const jobId = z.string().meta({
   description: 'Job ID',
   example: '1234',
   param: { in: 'header', name: 'jobId', id: 'jobRef' },
@@ -490,8 +507,8 @@ createDocument({
   },
 });
 
-// or manual registeration
-const otherJobId = z.string().openapi({
+// or manual registration
+const otherJobId = z.string().meta({
   description: 'Job ID',
   example: '1234',
   param: { in: 'header', name: 'jobId' },
@@ -511,7 +528,7 @@ createDocument({
 Response headers can be similarly registered:
 
 ```typescript
-const header = z.string().openapi({
+const header = z.string().meta({
   description: 'Job ID',
   example: '1234',
   header: { id: 'some-header' },
@@ -519,7 +536,7 @@ const header = z.string().openapi({
 
 // or
 
-const jobIdHeader = z.string().openapi({
+const jobIdHeader = z.string().meta({
   description: 'Job ID',
   example: '1234',
 });
@@ -615,6 +632,40 @@ createDocument({
 });
 ```
 
+#### Path Items
+
+Path Items can also be registered
+
+````typescript
+const pathItem: ZodOpenApiPathItemObject = {
+  id: 'some-path-item',
+  get: {
+    responses: {
+      200: {
+        description: '200 OK',
+        content: {
+          'application/json': {
+            schema: z.object({ a: z.string() }),
+          },
+        },
+      },
+    },
+  },
+};
+
+// or
+
+createDocument({
+  components: {
+    pathItems: {
+      'some-path-item': pathItem,
+    },
+  },
+});
+```
+
+
+
 ### Zod Types
 
 Zod types are composed of two different parts: the input and the output. This library decides which type to create based on if it is used in a request or response context.
@@ -635,9 +686,9 @@ In general, you want to avoid using a registered input schema in an output conte
 const schema = z.object({
   name: z.string(),
 });
-```
+````
 
-Input:
+Input schemas (request bodies, parameters):
 
 ```json
 {
@@ -651,7 +702,7 @@ Input:
 }
 ```
 
-Output:
+Output schemas (responses):
 
 ```json
 {
@@ -666,25 +717,30 @@ Output:
 }
 ```
 
-Unless you are strictly using `z.looseObject()`s or `z.strictObject()`s throughout your codebase you will likely run into issues where the input and output schemas differ. This library will do a best effort to check equality using a simple JSON.stringify() === JSON.stringify() check. If your registered schema contains dynamically created components, this will always fail.
-
-If the schemas are not equal, it will automatically handle this by outputting the `output` schema with an `Output` suffix.
+When the same schema is referenced in both input and output contexts, the library generates two separate component schemas. This happens automatically when a schema with an ID is used in both contexts.
 
-You can override this by setting the `outputId` field with the `.meta()` method.
+You can customize the output schema name by providing an `outputId`:
 
 ```ts
 const schema = z
   .object({
     name: z.string(),
   })
-  .meta({ id: 'MyObject', outputId: 'MyObjectResponse' });
+  .meta({
+    id: 'MyObject',
+    outputId: 'MyObjectResponse', // Customize the output schema name
+  });
 ```
 
+You can also set a global suffix for output schemas or use `z.looseObject()` and `z.strictObject()` to have explicit control over the schema behavior.
+
+> **⚠️ Note:** If your registered schema contains dynamically created lazy components, they won't be reused between input and output schemas.
+
 ## Supported OpenAPI Versions
 
 Currently the following versions of OpenAPI are supported
 
-- `3.1.0`
+- `3.1.0` (minimum version)
 - `3.1.1`
 
 Setting the `openapi` field will change how the some of the components are rendered.
@@ -726,6 +782,10 @@ See the library in use in the [examples](./examples/) folder.
 
 - [eslint-plugin-zod-openapi](https://github.com/samchungy/eslint-plugin-zod-openapi) - Eslint rules for zod-openapi. This includes features which can autogenerate Typescript comments for your Zod types based on your `description`, `example` and `deprecated` fields.
 
+## Version Information
+
+For information about changes and migration from v4 to v5, see the [v5 migration guide](./docs/v5.md).
+
 ## Comparisons
 
 ### [@asteasolutions/zod-to-openapi](./docs/comparisons.md)

package/dist/api.d.mts

@@ -1,4 +1,4 @@
-import { ComponentRegistry, Override, createComponents, createRegistry } from "./components-Ck7iRc2n.mjs";
+import { ComponentRegistry, Override, createComponents, createRegistry } from "./components-uNe8arnt.mjs";
 import { $ZodObject, $ZodType, $ZodTypes } from "zod/v4/core";
 import { core } from "zod/v4";
 

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import { ComponentRegistry, Override, createComponents, createRegistry } from "./components-DLKlRo1M.js";
+import { ComponentRegistry, Override, createComponents, createRegistry } from "./components-Ds_qyBU9.js";
 import { $ZodObject, $ZodType, $ZodTypes } from "zod/v4/core";
 import { core } from "zod/v4";
 

package/dist/api.js

@@ -1,4 +1,4 @@
-const require_components = require('./components-DNTDGqgA.js');
+const require_components = require('./components-D4JjPRqN.js');
 
 exports.createComponents = require_components.createComponents;
 exports.createRegistry = require_components.createRegistry;

package/dist/api.mjs

@@ -1,3 +1,3 @@
-import { createComponents, createRegistry, isAnyZodType, unwrapZodObject } from "./components-CtyiAwVj.mjs";
+import { createComponents, createRegistry, isAnyZodType, unwrapZodObject } from "./components-CncTLZvX.mjs";
 
 export { createComponents, createRegistry, isAnyZodType, unwrapZodObject };

package/dist/{components-CtyiAwVj.mjs → components-CncTLZvX.mjs}

@@ -260,7 +260,7 @@ const renameComponents = (components, outputIds, ctx, refPath) => {
 		const registeredComponent = ctx.registry.components.schemas.ids.get(key);
 		if (!registeredComponent) continue;
 		if (isDependencyPure(componentDependencies, stringifiedComponents, ctx.registry, key)) continue;
-		const newName = outputIds.get(key) ?? `${key}Output`;
+		const newName = outputIds.get(key) ?? `${key}${ctx.opts.outputIdSuffix ?? "Output"}`;
 		componentsToRename.set(key, newName);
 		components[newName] = components[key];
 		delete components[key];
@@ -286,19 +286,12 @@ const isDependencyPure = (componentDependencies, stringifiedComponents, registry
 
 //#endregion
 //#region src/create/schema/schema.ts
-const deleteZodOpenApiMeta = (jsonSchema) => {
-	delete jsonSchema.param;
-	delete jsonSchema.header;
-	delete jsonSchema.unusedIO;
-	delete jsonSchema.override;
-	delete jsonSchema.outputId;
-};
 const createSchema = (schema, ctx = {
 	registry: createRegistry(),
 	io: "output",
 	opts: {}
 }) => {
-	ctx.registry ??= createRegistry();
+	ctx.registry ??= createRegistry({ schemas: ctx.opts?.schemaComponents });
 	ctx.opts ??= {};
 	ctx.io ??= "output";
 	const registrySchemas = Object.fromEntries(ctx.registry.components.schemas[ctx.io]);
@@ -314,6 +307,13 @@ const createSchema = (schema, ctx = {
 		components: jsonSchemas.components
 	};
 };
+const deleteZodOpenApiMeta = (jsonSchema) => {
+	delete jsonSchema.param;
+	delete jsonSchema.header;
+	delete jsonSchema.unusedIO;
+	delete jsonSchema.override;
+	delete jsonSchema.outputId;
+};
 const createSchemas = (schemas, ctx) => {
 	const refPath = ctx.opts.schemaRefPath ?? "#/components/schemas/";
 	const entries = {};
@@ -467,6 +467,7 @@ const createRegistry = (components) => {
 			const meta = globalRegistry.get(parameter);
 			const name = opts?.location?.name ?? meta?.param?.name;
 			const inLocation = opts?.location?.in ?? meta?.param?.in;
+			if (opts?.location?.name && meta?.param?.name || opts?.location?.in && meta?.param?.in) throw new Error(`Parameter at ${path.join(" > ")} has both \`.meta({ param: { name, in } })\` and \`.meta({ param: { location: { in, name } } })\` information`);
 			if (!name || !inLocation) throw new Error(`Parameter at ${path.join(" > ")} is missing \`.meta({ param: { name, in } })\` information`);
 			const schemaObject = registry$1.addSchema(parameter, [
 				...path,
@@ -500,6 +501,7 @@ const createRegistry = (components) => {
 				registry$1.components.parameters.ids.set(id, parameterObject);
 				return ref;
 			}
+			if (opts?.location?.name || opts?.location?.in) return parameterObject;
 			registry$1.components.parameters.seen.set(parameter, parameterObject);
 			return parameterObject;
 		},

package/dist/{components-DNTDGqgA.js → components-D4JjPRqN.js}

@@ -283,7 +283,7 @@ const renameComponents = (components, outputIds, ctx, refPath) => {
 		const registeredComponent = ctx.registry.components.schemas.ids.get(key);
 		if (!registeredComponent) continue;
 		if (isDependencyPure(componentDependencies, stringifiedComponents, ctx.registry, key)) continue;
-		const newName = outputIds.get(key) ?? `${key}Output`;
+		const newName = outputIds.get(key) ?? `${key}${ctx.opts.outputIdSuffix ?? "Output"}`;
 		componentsToRename.set(key, newName);
 		components[newName] = components[key];
 		delete components[key];
@@ -309,19 +309,12 @@ const isDependencyPure = (componentDependencies, stringifiedComponents, registry
 
 //#endregion
 //#region src/create/schema/schema.ts
-const deleteZodOpenApiMeta = (jsonSchema) => {
-	delete jsonSchema.param;
-	delete jsonSchema.header;
-	delete jsonSchema.unusedIO;
-	delete jsonSchema.override;
-	delete jsonSchema.outputId;
-};
 const createSchema = (schema, ctx = {
 	registry: createRegistry(),
 	io: "output",
 	opts: {}
 }) => {
-	ctx.registry ??= createRegistry();
+	ctx.registry ??= createRegistry({ schemas: ctx.opts?.schemaComponents });
 	ctx.opts ??= {};
 	ctx.io ??= "output";
 	const registrySchemas = Object.fromEntries(ctx.registry.components.schemas[ctx.io]);
@@ -337,6 +330,13 @@ const createSchema = (schema, ctx = {
 		components: jsonSchemas.components
 	};
 };
+const deleteZodOpenApiMeta = (jsonSchema) => {
+	delete jsonSchema.param;
+	delete jsonSchema.header;
+	delete jsonSchema.unusedIO;
+	delete jsonSchema.override;
+	delete jsonSchema.outputId;
+};
 const createSchemas = (schemas, ctx) => {
 	const refPath = ctx.opts.schemaRefPath ?? "#/components/schemas/";
 	const entries = {};
@@ -490,6 +490,7 @@ const createRegistry = (components) => {
 			const meta = zod_v4_core.globalRegistry.get(parameter);
 			const name = opts?.location?.name ?? meta?.param?.name;
 			const inLocation = opts?.location?.in ?? meta?.param?.in;
+			if (opts?.location?.name && meta?.param?.name || opts?.location?.in && meta?.param?.in) throw new Error(`Parameter at ${path.join(" > ")} has both \`.meta({ param: { name, in } })\` and \`.meta({ param: { location: { in, name } } })\` information`);
 			if (!name || !inLocation) throw new Error(`Parameter at ${path.join(" > ")} is missing \`.meta({ param: { name, in } })\` information`);
 			const schemaObject = registry$1.addSchema(parameter, [
 				...path,
@@ -523,6 +524,7 @@ const createRegistry = (components) => {
 				registry$1.components.parameters.ids.set(id, parameterObject);
 				return ref;
 			}
+			if (opts?.location?.name || opts?.location?.in) return parameterObject;
 			registry$1.components.parameters.seen.set(parameter, parameterObject);
 			return parameterObject;
 		},

package/dist/{components-Ck7iRc2n.d.mts → components-Ds_qyBU9.d.ts}

@@ -360,7 +360,7 @@ declare module 'zod/v4' {
      */
     unusedIO?: 'input' | 'output';
     /**
-     * An alternate id to use for this schema in the event the schema is used in both input and output contexts.
+     * An alternate id to use for this schema in the event a registered schema is used in both a request and response schema.
      * If not specified, the id will be simply derived as the id of the schema plus an `Output` suffix. Please note that `id` must be set.
      */
     outputId?: string;
@@ -448,10 +448,10 @@ type OverrideType = $ZodTypes['_zod']['def']['type'];
 interface CreateDocumentOptions {
   /**
    * Use this to allowlist empty schemas to be created for given types
-   * - `true` — Allow empty schemas for input and output
-   * - `{ input: true, output: true }` — Allow empty schemas for input and output
-   * - `{ input: true }` — Allow empty schemas for input only
-   * - `{ output: true }` — Allow empty schemas for output only
+   * - `{ [ZodType]: true}` — Allow empty schemas for input and output
+   * - `{ [ZodType]: { input: true, output: true } }` — Allow empty schemas for input and output
+   * - `{ [ZodType]: { input: true } }` — Allow empty schemas for input only
+   * - `{ [ZodType]: { output: true } }` — Allow empty schemas for output only
    */
   allowEmptySchema?: Partial<Record<OverrideType, true | Partial<{
     input: true;
@@ -463,6 +463,14 @@ interface CreateDocumentOptions {
    * - `(ctx) => { ctx.jsonSchema.type = 'string'; }` — Override the schema type to be a string using a function
    */
   override?: Override;
+  /**
+   * Suffix to append to the output ID of the schema.
+   * This is useful to avoid conflicts with other schemas that may have the same name.
+   * For example, if you have a schema named `Person`, you can set this to `Response` to get `PersonResponse`.
+   * If not set, the default suffix is `Output`.
+   * @default 'Output'
+   */
+  outputIdSuffix?: string;
   /**
    * How to handle reused schemas.
    * - `"ref"` — Reused schemas will be rendered as references

package/dist/{components-DLKlRo1M.d.ts → components-uNe8arnt.d.mts}

@@ -360,7 +360,7 @@ declare module 'zod/v4' {
      */
     unusedIO?: 'input' | 'output';
     /**
-     * An alternate id to use for this schema in the event the schema is used in both input and output contexts.
+     * An alternate id to use for this schema in the event a registered schema is used in both a request and response schema.
      * If not specified, the id will be simply derived as the id of the schema plus an `Output` suffix. Please note that `id` must be set.
      */
     outputId?: string;
@@ -448,10 +448,10 @@ type OverrideType = $ZodTypes['_zod']['def']['type'];
 interface CreateDocumentOptions {
   /**
    * Use this to allowlist empty schemas to be created for given types
-   * - `true` — Allow empty schemas for input and output
-   * - `{ input: true, output: true }` — Allow empty schemas for input and output
-   * - `{ input: true }` — Allow empty schemas for input only
-   * - `{ output: true }` — Allow empty schemas for output only
+   * - `{ [ZodType]: true}` — Allow empty schemas for input and output
+   * - `{ [ZodType]: { input: true, output: true } }` — Allow empty schemas for input and output
+   * - `{ [ZodType]: { input: true } }` — Allow empty schemas for input only
+   * - `{ [ZodType]: { output: true } }` — Allow empty schemas for output only
    */
   allowEmptySchema?: Partial<Record<OverrideType, true | Partial<{
     input: true;
@@ -463,6 +463,14 @@ interface CreateDocumentOptions {
    * - `(ctx) => { ctx.jsonSchema.type = 'string'; }` — Override the schema type to be a string using a function
    */
   override?: Override;
+  /**
+   * Suffix to append to the output ID of the schema.
+   * This is useful to avoid conflicts with other schemas that may have the same name.
+   * For example, if you have a schema named `Person`, you can set this to `Response` to get `PersonResponse`.
+   * If not set, the default suffix is `Output`.
+   * @default 'Output'
+   */
+  outputIdSuffix?: string;
   /**
    * How to handle reused schemas.
    * - `"ref"` — Reused schemas will be rendered as references

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { BaseParameterObject, CallbackObject, CallbacksObject, ComponentRegistry, ComponentsObject, ContactObject, ContentObject, CreateDocumentOptions, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, IExtensionName, IExtensionType, ISpecificationExtension, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, Override, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, TagObject, XmlObject, ZodObjectInput, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiMediaTypeObject, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiVersion, createDocument } from "./components-Ck7iRc2n.mjs";
+import { BaseParameterObject, CallbackObject, CallbacksObject, ComponentRegistry, ComponentsObject, ContactObject, ContentObject, CreateDocumentOptions, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, IExtensionName, IExtensionType, ISpecificationExtension, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, Override, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, TagObject, XmlObject, ZodObjectInput, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiMediaTypeObject, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiVersion, createDocument } from "./components-uNe8arnt.mjs";
 import { core } from "zod/v4";
 
 //#region rolldown:runtime
@@ -11,7 +11,9 @@ interface SchemaResult {
 declare const createSchema: (schema: core.$ZodType, ctx?: {
   registry?: ComponentRegistry;
   io?: "input" | "output";
-  opts?: CreateDocumentOptions;
+  opts?: CreateDocumentOptions & {
+    schemaComponents?: ZodOpenApiComponentsObject["schemas"];
+  };
 }) => {
   schema: SchemaObject | ReferenceObject;
   components: Record<string, SchemaObject>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BaseParameterObject, CallbackObject, CallbacksObject, ComponentRegistry, ComponentsObject, ContactObject, ContentObject, CreateDocumentOptions, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, IExtensionName, IExtensionType, ISpecificationExtension, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, Override, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, TagObject, XmlObject, ZodObjectInput, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiMediaTypeObject, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiVersion, createDocument } from "./components-DLKlRo1M.js";
+import { BaseParameterObject, CallbackObject, CallbacksObject, ComponentRegistry, ComponentsObject, ContactObject, ContentObject, CreateDocumentOptions, DiscriminatorObject, EncodingObject, EncodingPropertyObject, ExampleObject, ExamplesObject, ExternalDocumentationObject, HeaderObject, HeadersObject, IExtensionName, IExtensionType, ISpecificationExtension, InfoObject, LicenseObject, LinkObject, LinkParametersObject, LinksObject, MediaTypeObject, OAuthFlowObject, OAuthFlowsObject, OpenAPIObject, OperationObject, Override, ParameterLocation, ParameterObject, ParameterStyle, PathItemObject, PathObject, PathsObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SchemaObject, SchemaObjectType, SchemasObject, ScopesObject, SecurityRequirementObject, SecuritySchemeObject, SecuritySchemeType, ServerObject, ServerVariableObject, TagObject, XmlObject, ZodObjectInput, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiMediaTypeObject, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiVersion, createDocument } from "./components-Ds_qyBU9.js";
 import { core } from "zod/v4";
 
 //#region rolldown:runtime
@@ -11,7 +11,9 @@ interface SchemaResult {
 declare const createSchema: (schema: core.$ZodType, ctx?: {
   registry?: ComponentRegistry;
   io?: "input" | "output";
-  opts?: CreateDocumentOptions;
+  opts?: CreateDocumentOptions & {
+    schemaComponents?: ZodOpenApiComponentsObject["schemas"];
+  };
 }) => {
   schema: SchemaObject | ReferenceObject;
   components: Record<string, SchemaObject>;

package/dist/index.js

@@ -1,4 +1,4 @@
-const require_components = require('./components-DNTDGqgA.js');
+const require_components = require('./components-D4JjPRqN.js');
 
 //#region src/create/document.ts
 const createDocument = (zodOpenApiObject, opts = {}) => {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { createComponents, createPaths, createRegistry, createSchema } from "./components-CtyiAwVj.mjs";
+import { createComponents, createPaths, createRegistry, createSchema } from "./components-CncTLZvX.mjs";
 
 //#region src/create/document.ts
 const createDocument = (zodOpenApiObject, opts = {}) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-openapi",
-  "version": "5.0.0-beta.15",
+  "version": "5.0.0-beta.17",
   "description": "Convert Zod Schemas to OpenAPI v3.x documentation",
   "keywords": [
     "typescript",
@@ -54,7 +54,7 @@
     "@arethetypeswrong/cli": "0.18.1",
     "@redocly/cli": "1.34.3",
     "@types/node": "22.15.21",
-    "eslint-plugin-zod-openapi": "1.0.0",
+    "eslint-plugin-zod-openapi": "2.0.0-beta.1",
     "openapi3-ts": "4.5.0",
     "skuba": "11.0.1",
     "tsdown": "0.12.9",