zod-openapi 5.0.0-beta.9 → 5.0.1

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,93 @@ 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',
+});
+```
+
+You can set additional metadata to the rendered schema in a few different ways. Zod's `.meta()` method allows you to directly set OpenAPI directly to the schema. However, if you wanted to override any field that Zod generates, this may not work as expected. In this case, you can use the `override` option to customize the rendered OpenAPI schema.
+
+eg.
+
+```typescript
+z.string().datetime().meta({
+  description: 'A date field',
+  format: 'MY-FORMAT',
+  'x-custom-field': 'custom value',
+});
+```
+
+Would render the following OpenAPI schema. Note that format is not overridden with our custom format value.
+
+```json
+{
+  "type": "string",
+  "format": "date-time",
+  "description": "A date field",
+  "x-custom-field": "custom value"
+}
+```
+
+In order to override fields which are generated by Zod or this library, you can use the `override` option in the `.meta()` method. This allows you to customize the rendered OpenAPI schema after we have both processed it.
+
+##### override object
+
+This does a naive merge of the override object with the rendered OpenAPI schema. This is useful for simple overrides where you want to add or modify properties without complex logic.
+
+```typescript
+z.string.datetime().meta({
+  description: 'A date field',
+  override: {
+    format: 'MY-FORMAT',
+  },
+});
+```
+
+##### override function
+
+The `override` function allows you to deeply customize the rendered OpenAPI schema. Eg. if you wanted to render a Zod union as a `oneOf` instead of `anyOf` for a single schema, you can do so by using the `override` function. View the documentation for `override` in the [CreateDocumentOptions](#createdocumentoptions) section for more information.
+
+```typescript
+z.union([z.string(), z.number()]).meta({
+  description: 'A union of string and number',
+  override: ({ jsonSchema }) => {
+    jsonSchema.anyOf = jsonSchema.oneOf;
+    delete jsonSchema.oneOf;
+  },
+});
+```
 
 ### `createDocument`
 
 Generates an OpenAPI documentation object.
 
 ```typescript
-import 'zod-openapi/extend';
-import { z } from 'zod/v4';
+import * as z from 'zod/v4';
 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 +230,109 @@ const document = createDocument({
   ```
 </details>
 
+`createDocument` takes an optional options argument which can be used to modify how the document is created
+
+```typescript
+createDocument(doc, {
+  override: ({ jsonSchema, zodSchema, io }) => {
+    const def = zodSchema._zod.def;
+    if (def.type === 'date' && io === 'output') {
+      jsonSchema.type = 'string';
+      jsonSchema.format = 'date-time';
+    }
+  },
+  allowEmptySchema: {
+    custom: true,
+  },
+});
+```
+
 #### CreateDocumentOptions
 
-`createDocument` takes an optional `CreateDocumentOptions` argument which can be used to modify how the document is created.
+| Option             | Type                | Description                                                                                                                               |
+| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `override`         | `Function`          | Override rendered schema with a function``                                                                                                |
+| `outputIdSuffix`   | `string`            | Suffix for output schema IDs when the schema is used in both a request and response. Defaults to ``'Output'`                              |
+| `allowEmptySchema` | `Object`            | Control whether empty schemas are allowed for specific Zod schema types                                                                   |
+| `cycles`           | `'ref' \| 'throw'`  | How to handle cycles in schemas.<br>- `'ref'` — Break cycles using $defs<br>- `'throw'` — Error on cycles. Defaults to `'ref'`            |
+| `reused`           | `'ref' \| 'inline'` | How to handle reused schemas.<br>- `'ref'` — Reused schemas as references<br>- `'inline'` — Inline reused schemas. Defaults to `'inline'` |
+|                    |
+
+##### `override`
+
+The `override` function allows you to customize the rendered OpenAPI schema. It receives an object with the following properties:
+
+| Property     | Type                  | Description                                                                                                       |
+| ------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `jsonSchema` | `Object`              | The OpenAPI schema object being generated. You can modify this object to change the rendered schema.              |
+| `zodSchema`  | `ZodType`             | The original Zod schema being converted to OpenAPI. You can use this to access Zod-specific properties.           |
+| `io`         | `'input' \| 'output'` | The context in which the schema is being rendered. `'input'` for request bodies/params, `'output'` for responses. |
+
+This allows you to transform the schema based on your own rules or requirements. For example, if you
+
+1. Wanted to change how dates are rendered in the output context because a typical JSON serializer will transform them to a string
+2. Change all union outputs to be oneOf instead of anyOf
 
 ```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 }) => {
+    const def = zodSchema._zod.def;
+    if (def.type === 'date' && io === 'output') {
+      jsonSchema.type = 'string';
+      jsonSchema.format = 'date-time';
+      return;
+    }
+    if (def.type === 'union') {
+      jsonSchema.oneOf = jsonSchema.anyOf;
+      delete jsonSchema.anyOf;
+      return;
     }
   },
 });
 ```
 
+##### `outputIdSuffix`
+
+The `outputIdSuffix` option allows you to set a suffix for output schema IDs when the schema is used in both a request and response context. This is useful for distinguishing between input and output schemas.
+
+##### `allowEmptySchema`
+
+The `allowEmptySchema` option allows you to control whether or not this library will throw when it encounters an empty schema. By default this library will not throw if it encounters an `z.any()` or `z.unknown()` schema.
+
+This allows you to customize how this library handles [unrepresentable](https://zod.dev/json-schema?id=unrepresentable) Zod schemas.
+
+eg. If you wanted to allow `z.custom()` to be rendered as an empty schema, you can set the `allowEmptySchema` option as follows:
+
+```typescript
+createDocument(doc, {
+  allowEmptySchema: {
+    custom: true, // Allow empty schemas for `z.custom()` in all contexts
+    set: { output: true }, // Allow empty schemas for `z.set()` only in an output context
+  },
+});
+```
+
+##### `cycles` and `reused`
+
+These options are exposed directly from the Zod. Read the [documentation](https://zod.dev/json-schema?id=unrepresentable#cycles) for more information on how to use these options.
+
+#####
+
 ### `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 * as z from 'zod/v4';
 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,15 +377,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
 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
+  opts: {}, // Create Document Options,
+});
 ```
 
 ### Request Parameters
@@ -285,7 +419,7 @@ createDocument({
     '/jobs/{a}': {
       put: {
         parameters: [
-          z.string().openapi({
+          z.string().meta({
             param: {
               name: 'job-header',
               in: 'header',
@@ -396,7 +530,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 +568,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 +587,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 +608,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 +624,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 +645,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 +653,7 @@ const header = z.string().openapi({
 
 // or
 
-const jobIdHeader = z.string().openapi({
+const jobIdHeader = z.string().meta({
   description: 'Job ID',
   example: '1234',
 });
@@ -615,6 +749,121 @@ 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.
@@ -631,13 +880,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()`.
 
-```ts
+```typescript
 const schema = z.object({
   name: z.string(),
 });
 ```
 
-Input:
+Input schemas (request bodies, parameters):
 
 ```json
 {
@@ -651,7 +900,7 @@ Input:
 }
 ```
 
-Output:
+Output schemas (responses):
 
 ```json
 {
@@ -666,25 +915,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,9 +980,9 @@ 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.
 
-## Comparisons
+## Version Information
 
-### [@asteasolutions/zod-to-openapi](./docs/comparisons.md)
+For information about changes and migration from v4 to v5, see the [v5 migration guide](./docs/v5.md).
 
 ## Development
 
@@ -757,21 +1011,3 @@ pnpm format
 # Check for issues
 pnpm lint
 ```
-
-### Release
-
-To release a new version
-
-1. Create a [new GitHub Release](https://github.com/samchungy/zod-openapi/releases/new)
-2. Select `🏷️ Choose a tag`, enter a version number. eg. `v1.2.0` and click `+ Create new tag: vX.X.X on publish`.
-3. Click the `Generate release notes` button and adjust the description.
-4. Tick the `Set as the latest release` box and click `Publish release`. This will trigger the `Release` workflow.
-5. Check the `Pull Requests` tab for a PR labelled `Release vX.X.X`.
-6. Click `Merge Pull Request` on that Pull Request to update master with the new package version.
-
-To release a new beta version
-
-1. Create a [new GitHub Release](https://github.com/samchungy/zod-openapi/releases/new)
-2. Select `🏷️ Choose a tag`, enter a version number with a `-beta.X` suffix eg. `v1.2.0-beta.1` and click `+ Create new tag: vX.X.X-beta.X on publish`.
-3. Click the `Generate release notes` button and adjust the description.
-4. Tick the `Set as a pre-release` box and click `Publish release`. This will trigger the `Prerelease` workflow.

package/dist/api.d.mts

@@ -1,20 +1,11 @@
-import { ComponentRegistry, Override, ParameterLocation, ParameterObject, ReferenceObject, createComponents, createRegistry } from "./components-26wns3Hd.mjs";
+import { ComponentRegistry, Override, ZodOpenApiBaseMetadata, ZodOpenApiMetadata, createComponents, createRegistry } from "./components-CCPXuBcU.mjs";
 import { $ZodObject, $ZodType, $ZodTypes } from "zod/v4/core";
 import { core } from "zod/v4";
 
-//#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, createParameter, createRegistry, isAnyZodType, unwrapZodObject };
+export { ComponentRegistry, Override, ZodOpenApiBaseMetadata, ZodOpenApiMetadata, createComponents, createRegistry, isAnyZodType, unwrapZodObject };

package/dist/api.d.ts

@@ -1,20 +1,11 @@
-import { ComponentRegistry, Override, ParameterLocation, ParameterObject, ReferenceObject, createComponents, createRegistry } from "./components-CokUEQbL.js";
+import { ComponentRegistry, Override, ZodOpenApiBaseMetadata, ZodOpenApiMetadata, createComponents, createRegistry } from "./components-D8Br4Oqx.js";
 import { $ZodObject, $ZodType, $ZodTypes } from "zod/v4/core";
 import { core } from "zod/v4";
 
-//#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, createParameter, createRegistry, isAnyZodType, unwrapZodObject };
+export { ComponentRegistry, Override, ZodOpenApiBaseMetadata, ZodOpenApiMetadata, createComponents, createRegistry, isAnyZodType, unwrapZodObject };

package/dist/api.js

@@ -1,7 +1,6 @@
-const require_components = require('./components-CB3cj8u3.js');
+const require_components = require('./components-DpACv95L.js');
 
 exports.createComponents = require_components.createComponents;
-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,3 @@
-import { createComponents, createParameter, createRegistry, isAnyZodType, unwrapZodObject } from "./components-0QHfGwg0.mjs";
+import { createComponents, createRegistry, isAnyZodType, unwrapZodObject } from "./components-CUMu4QeI.mjs";
 
-export { createComponents, createParameter, createRegistry, isAnyZodType, unwrapZodObject };
+export { createComponents, createRegistry, isAnyZodType, unwrapZodObject };