zod-openapi 5.0.0-beta.18 → 5.0.0-beta.2

package/README.md

@@ -3,12 +3,12 @@
   <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>
 <a href="https://www.npmjs.com/package/zod-openapi"><img src="https://img.shields.io/npm/dm/zod-openapi"/></a>
-<a href="https://nodejs.org/en/"><img src="https://img.shields.io/node/v/zod-openapi"/></a>
+<a href="https://nodejs.org/en/"><img src="https://img.shields.io/badge/node-%3E%3D%2018-brightgreen"/></a>
 <a href="https://github.com/samchungy/zod-openapi/actions/workflows/test.yml"><img src="https://github.com/samchungy/zod-openapi/actions/workflows/test.yml/badge.svg"/></a>
 <a href="https://github.com/samchungy/zod-openapi/actions/workflows/release.yml"><img src="https://github.com/samchungy/zod-openapi/actions/workflows/release.yml/badge.svg"/></a>
 <a href="https://github.com/seek-oss/skuba"><img src="https://img.shields.io/badge/🤿%20skuba-powered-009DC4"/></a>
@@ -31,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 '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',
 });
@@ -178,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 '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',
 });
@@ -261,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
@@ -303,7 +285,7 @@ createDocument({
     '/jobs/{a}': {
       put: {
         parameters: [
-          z.string().meta({
+          z.string().openapi({
             param: {
               name: 'job-header',
               in: 'header',
@@ -414,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
@@ -452,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
     },
   },
 });
@@ -471,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' },
@@ -492,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' },
@@ -508,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' },
@@ -529,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' },
@@ -537,7 +519,7 @@ const header = z.string().meta({
 
 // or
 
-const jobIdHeader = z.string().meta({
+const jobIdHeader = z.string().openapi({
   description: 'Job ID',
   example: '1234',
 });
@@ -633,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.
@@ -764,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
 {
@@ -784,7 +651,7 @@ Input schemas (request bodies, parameters):
 }
 ```
 
-Output schemas (responses):
+Output:
 
 ```json
 {
@@ -799,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.
@@ -864,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/api/index.d.ts

@@ -1 +1 @@
-export * from '../dist/api';
+export * from "../dist/api";

package/dist/api.cjs

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const components = require("./components.chunk.cjs");
+exports.createComponents = components.createComponents;
+exports.createMediaTypeObject = components.createMediaTypeObject;
+exports.createParameter = components.createParameter;
+exports.createRegistry = components.createRegistry;
+exports.unwrapZodObject = components.unwrapZodObject;

package/dist/api.d.mts

@@ -1,11 +1,5 @@
-import { ComponentRegistry, Override, createComponents, createRegistry } from "./components-DkESnIB9.mjs";
-import { $ZodObject, $ZodType, $ZodTypes } from "zod/v4/core";
-import { core } from "zod/v4";
-
-//#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 { createComponents, createRegistry } from './create/components.js';
+export { createMediaTypeObject } from './create/content.js';
+export { createParameter } from './create/parameters.js';
+export { unwrapZodObject } from './create/object.js';
+export { Override, isAnyZodType } from './zod.js';

package/dist/api.d.ts

@@ -1,11 +1,5 @@
-import { ComponentRegistry, Override, createComponents, createRegistry } from "./components-BLmIpmmY.js";
-import { $ZodObject, $ZodType, $ZodTypes } from "zod/v4/core";
-import { core } from "zod/v4";
-
-//#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 { createComponents, createRegistry } from './create/components.js';
+export { createMediaTypeObject } from './create/content.js';
+export { createParameter } from './create/parameters.js';
+export { unwrapZodObject } from './create/object.js';
+export { Override, isAnyZodType } from './zod.js';

package/dist/api.mjs

@@ -1,3 +1,8 @@
-import { createComponents, createRegistry, isAnyZodType, unwrapZodObject } from "./components-Cblv9pY1.mjs";
-
-export { createComponents, createRegistry, isAnyZodType, unwrapZodObject };
+import { createComponents, createMediaTypeObject, createParameter, createRegistry, unwrapZodObject } from "./components.chunk.mjs";
+export {
+  createComponents,
+  createMediaTypeObject,
+  createParameter,
+  createRegistry,
+  unwrapZodObject
+};