zod-openapi 5.0.0-beta.20 → 5.0.0-beta.4

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.1x documentation.
+A TypeScript library which uses <a href="https://github.com/colinhacks/zod">Zod</a> schemas to generate OpenAPI v3.x 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>
@@ -15,9 +15,6 @@ A TypeScript library which uses <a href="https://github.com/colinhacks/zod">Zod<
 </div>
 <br>
 
-> [!TIP]
-> Zod v4 support is available via `zod-openapi@beta`. Please read the [documentation](https://github.com/samchungy/zod-openapi/blob/v4-stash/docs/v5.md) for more information. A codegen will be available on release to help you migrate if you wish to wait.
-
 ## Installation
 
 Install via `npm`, `yarn`, or `pnpm`:
@@ -34,41 +31,33 @@ pnpm install zod zod-openapi
 
 ### `.meta()`
 
-Use the `.meta()` method to add OpenAPI metadata to a Zod schema. It accepts an object with the following options:
+Use the `.meta()` method to add 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`.           |
-
-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',
-});
-```
+| `unusedIO` | Allows you to set the `io` for an unused schema added to the components section. Defaults to `output`            |
 
 ### `createDocument`
 
 Generates an OpenAPI documentation object.
 
 ```typescript
-import * as z from 'zod/v4';
+import 'zod-openapi/extend';
+import { z } from 'zod';
 import { createDocument } from 'zod-openapi';
 
-const jobId = z.string().meta({
+const jobId = z.string().openapi({
   description: 'A unique identifier for a job',
   example: '12345',
   id: 'jobId',
 });
 
-const title = z.string().meta({
+const title = z.string().openapi({
   description: 'Job title',
   example: 'My job',
 });
@@ -181,45 +170,37 @@ const document = createDocument({
   ```
 </details>
 
-`createDocument` takes an optional options argument which can be used to modify how the document is created
+#### CreateDocumentOptions
+
+`createDocument` takes an optional `CreateDocumentOptions` argument which can be used to modify how the document is created.
 
 ```typescript
-createDocument(doc, {
-  override: ({ jsonSchema, zodSchema, io }) => {
-    // Customize the schema generation
-    if (io === 'output') {
-      jsonSchema.type = 'string';
+const document = createDocument(details, {
+  override: ({ jsonSchema, zodSchema }) => {
+    if (jsonSchema.anyOf) {
+      ctx.jsonSchema.oneOf = ctx.jsonSchema.anyOf;
+      delete ctx.jsonSchema.anyOf;
     }
   },
 });
 ```
 
-#### 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 * as z from 'zod/v4';
+import 'zod-openapi/extend';
+import { z } from 'zod';
 import { createSchema } from 'zod-openapi';
 
-const jobId = z.string().meta({
+const jobId = z.string().openapi({
   description: 'A unique identifier for a job',
   example: '12345',
   id: 'jobId',
 });
 
-const title = z.string().meta({
+const title = z.string().openapi({
   description: 'Job title',
   example: 'My job',
 });
@@ -264,17 +245,15 @@ const { schema, components } = createSchema(job);
 
 #### CreateSchemaOptions
 
-`createSchema` takes an optional `CreateSchemaOptions` parameter which includes all options from [CreateDocumentOptions](#createdocumentoptions) plus the following:
+`createSchema` takes an optional `CreateSchemaOptions` parameter which can also take the same options as [CreateDocumentOptions](#createdocumentoptions) along with the following options:
 
 ```typescript
 const { schema, components } = createSchema(job, {
-  // 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
-});
+  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/
+})
 ```
 
 ### Request Parameters
@@ -306,7 +285,7 @@ createDocument({
     '/jobs/{a}': {
       put: {
         parameters: [
-          z.string().meta({
+          z.string().openapi({
             param: {
               name: 'job-header',
               in: 'header',
@@ -417,7 +396,7 @@ If we take the example in `createDocument` and instead create `title` as follows
 ##### Auto Registering Schema
 
 ```typescript
-const title = z.string().meta({
+const title = z.string().openapi({
   description: 'Job title',
   example: 'My job',
   id: 'jobTitle', // <- new field
@@ -455,14 +434,14 @@ Another way to register schema instead of adding a `ref` is to add it to the com
 eg.
 
 ```typescript
-const title = z.string().meta({
+const title = z.string().openapi({
   description: 'Job title',
   example: 'My job',
 });
 createDocument({
   components: {
     schemas: {
-      jobTitle: title, // this will register this Zod Schema as jobTitle unless `id` in `.meta()` is specified on the type
+      jobTitle: title, // this will register this Zod Schema as jobTitle unless `ref` in `.openapi()` is specified on the type
     },
   },
 });
@@ -474,7 +453,7 @@ Query, Path, Header & Cookie parameters can be similarly registered:
 
 ```typescript
 // Easy auto registration
-const jobId = z.string().meta({
+const jobId = z.string().openapi({
   description: 'Job ID',
   example: '1234',
   param: { id: 'jobRef' },
@@ -495,7 +474,7 @@ createDocument({
 });
 
 // or more verbose auto registration
-const jobId = z.string().meta({
+const jobId = z.string().openapi({
   description: 'Job ID',
   example: '1234',
   param: { in: 'header', name: 'jobId', id: 'jobRef' },
@@ -511,8 +490,8 @@ createDocument({
   },
 });
 
-// or manual registration
-const otherJobId = z.string().meta({
+// or manual registeration
+const otherJobId = z.string().openapi({
   description: 'Job ID',
   example: '1234',
   param: { in: 'header', name: 'jobId' },
@@ -532,7 +511,7 @@ createDocument({
 Response headers can be similarly registered:
 
 ```typescript
-const header = z.string().meta({
+const header = z.string().openapi({
   description: 'Job ID',
   example: '1234',
   header: { id: 'some-header' },
@@ -540,7 +519,7 @@ const header = z.string().meta({
 
 // or
 
-const jobIdHeader = z.string().meta({
+const jobIdHeader = z.string().openapi({
   description: 'Job ID',
   example: '1234',
 });
@@ -636,121 +615,6 @@ 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,
-    },
-  },
-});
-```
-
-#### Security Schemes
-
-Security Schemes can be registered for authentication methods:
-
-```typescript
-createDocument({
-  components: {
-    securitySchemes: {
-      bearerAuth: {
-        type: 'http',
-        scheme: 'bearer',
-        bearerFormat: 'JWT',
-        description: 'JWT Authentication',
-      },
-    },
-  },
-});
-```
-
-#### Links
-
-Links can be registered to describe relationships between operations:
-
-```typescript
-const link: ZodOpenApiLinkObject = {
-  id: 'getUserById',
-  operationId: 'getUser',
-  parameters: {
-    userId: '$request.path.id',
-  },
-  description: 'Link to get user by id',
-};
-
-// or
-
-createDocument({
-  components: {
-    links: {
-      getUserById: {
-        operationId: 'getUser',
-        parameters: {
-          userId: '$request.path.id',
-        },
-        description: 'Link to get user by id',
-      },
-    },
-  },
-});
-```
-
-#### Examples
-
-Examples can be registered to provide sample values for schemas:
-
-```typescript
-const example: ZodOpenApiExampleObject = {
-  id: 'userExample',
-  summary: 'A sample user',
-  value: {
-    id: '123',
-    name: 'Jane Doe',
-    email: 'jane@example.com',
-  },
-};
-
-// or
-
-createDocument({
-  components: {
-    examples: {
-      userExample: {
-        summary: 'A sample user',
-        value: {
-          id: '123',
-          name: 'Jane Doe',
-          email: 'jane@example.com',
-        },
-      },
-    },
-  },
-});
-```
-
 ### 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.
@@ -767,13 +631,13 @@ Output:
 
 In general, you want to avoid using a registered input schema in an output context and vice versa. This is because the rendered input and output schemas of a simple Zod schema will differ, even with a simple Zod schema like `z.object()`.
 
-```typescript
+```ts
 const schema = z.object({
   name: z.string(),
 });
 ```
 
-Input schemas (request bodies, parameters):
+Input:
 
 ```json
 {
@@ -787,7 +651,7 @@ Input schemas (request bodies, parameters):
 }
 ```
 
-Output schemas (responses):
+Output:
 
 ```json
 {
@@ -802,30 +666,25 @@ Output schemas (responses):
 }
 ```
 
-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.
+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.
 
-You can customize the output schema name by providing an `outputId`:
+If the schemas are not equal, it will automatically handle this by outputting the `output` schema with an `Output` suffix.
+
+You can override this by setting the `outputId` field with the `.meta()` method.
 
 ```ts
 const schema = z
   .object({
     name: z.string(),
   })
-  .meta({
-    id: 'MyObject',
-    outputId: 'MyObjectResponse', // Customize the output schema name
-  });
+  .meta({ id: 'MyObject', outputId: 'MyObjectResponse' });
 ```
 
-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` (minimum version)
+- `3.1.0`
 - `3.1.1`
 
 Setting the `openapi` field will change how the some of the components are rendered.
@@ -867,10 +726,6 @@ 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,11 +1,22 @@
-import { ComponentRegistry, Override, createComponents, createRegistry } from "./components-DkESnIB9.mjs";
+import { ComponentRegistry, MediaTypeObject, Override, ParameterLocation, ParameterObject, ReferenceObject, ZodOpenApiMediaTypeObject, createComponents, createRegistry, isAnyZodType } from "./components-DAYTA1Um.mjs";
 import { $ZodObject, $ZodType, $ZodTypes } from "zod/v4/core";
-import { core } from "zod/v4";
 
+//#region src/create/content.d.ts
+declare const createMediaTypeObject: (mediaTypeObject: ZodOpenApiMediaTypeObject, ctx: {
+  registry: ComponentRegistry;
+  io: "input" | "output";
+}, path: string[]) => MediaTypeObject;
+//#endregion
+//#region src/create/parameters.d.ts
+declare const createParameter: (parameter: $ZodType, location: {
+  in: ParameterLocation;
+  name: string;
+} | undefined, ctx: {
+  registry: ComponentRegistry;
+  io: "input" | "output";
+}, path: string[]) => ParameterObject | ReferenceObject;
+//#endregion
 //#region src/create/object.d.ts
 declare const unwrapZodObject: (zodType: $ZodTypes, io: "input" | "output", path: string[]) => $ZodObject;
 //#endregion
-//#region src/zod.d.ts
-declare const isAnyZodType: (schema: unknown) => schema is core.$ZodTypes;
-//#endregion
-export { ComponentRegistry, Override, createComponents, createRegistry, isAnyZodType, unwrapZodObject };
+export { Override, createComponents, createMediaTypeObject, createParameter, createRegistry, isAnyZodType, unwrapZodObject };

package/dist/api.d.ts

@@ -1,11 +1,22 @@
-import { ComponentRegistry, Override, createComponents, createRegistry } from "./components-BLmIpmmY.js";
+import { ComponentRegistry, MediaTypeObject, Override, ParameterLocation, ParameterObject, ReferenceObject, ZodOpenApiMediaTypeObject, createComponents, createRegistry, isAnyZodType } from "./components-5_CJdR73.js";
 import { $ZodObject, $ZodType, $ZodTypes } from "zod/v4/core";
-import { core } from "zod/v4";
 
+//#region src/create/content.d.ts
+declare const createMediaTypeObject: (mediaTypeObject: ZodOpenApiMediaTypeObject, ctx: {
+  registry: ComponentRegistry;
+  io: "input" | "output";
+}, path: string[]) => MediaTypeObject;
+//#endregion
+//#region src/create/parameters.d.ts
+declare const createParameter: (parameter: $ZodType, location: {
+  in: ParameterLocation;
+  name: string;
+} | undefined, ctx: {
+  registry: ComponentRegistry;
+  io: "input" | "output";
+}, path: string[]) => ParameterObject | ReferenceObject;
+//#endregion
 //#region src/create/object.d.ts
 declare const unwrapZodObject: (zodType: $ZodTypes, io: "input" | "output", path: string[]) => $ZodObject;
 //#endregion
-//#region src/zod.d.ts
-declare const isAnyZodType: (schema: unknown) => schema is core.$ZodTypes;
-//#endregion
-export { ComponentRegistry, Override, createComponents, createRegistry, isAnyZodType, unwrapZodObject };
+export { Override, createComponents, createMediaTypeObject, createParameter, createRegistry, isAnyZodType, unwrapZodObject };

package/dist/api.js

@@ -1,6 +1,8 @@
-const require_components = require('./components-XnOyQ3JZ.js');
+require('./zod-i2t01GF0.js');
+const require_components = require('./components-CXjVnBr-.js');
 
 exports.createComponents = require_components.createComponents;
+exports.createMediaTypeObject = require_components.createMediaTypeObject;
+exports.createParameter = require_components.createParameter;
 exports.createRegistry = require_components.createRegistry;
-exports.isAnyZodType = require_components.isAnyZodType;
 exports.unwrapZodObject = require_components.unwrapZodObject;

package/dist/api.mjs

@@ -1,3 +1,4 @@
-import { createComponents, createRegistry, isAnyZodType, unwrapZodObject } from "./components-BVy-T4wz.mjs";
+import "./zod-BvA30wad.mjs";
+import { createComponents, createMediaTypeObject, createParameter, createRegistry, unwrapZodObject } from "./components-CvutxtFV.mjs";
 
-export { createComponents, createRegistry, isAnyZodType, unwrapZodObject };
+export { createComponents, createMediaTypeObject, createParameter, createRegistry, unwrapZodObject };