zod-openapi 5.0.0 → 5.0.1

package/README.md

@@ -51,6 +51,58 @@ z.string().meta({
 });
 ```
 
+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.
@@ -183,25 +235,89 @@ const document = createDocument({
 ```typescript
 createDocument(doc, {
   override: ({ jsonSchema, zodSchema, io }) => {
-    // Customize the schema generation
-    if (io === 'output') {
+    const def = zodSchema._zod.def;
+    if (def.type === 'date' && io === 'output') {
       jsonSchema.type = 'string';
+      jsonSchema.format = 'date-time';
     }
   },
+  allowEmptySchema: {
+    custom: true,
+  },
 });
 ```
 
 #### 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` | `Object`            | `undefined` | 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 |
+| 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
+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.
@@ -895,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,4 +1,4 @@
-import { ComponentRegistry, Override, ZodOpenApiBaseMetadata, ZodOpenApiMetadata, createComponents, createRegistry } from "./components-Dus8apcN.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";
 

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import { ComponentRegistry, Override, ZodOpenApiBaseMetadata, ZodOpenApiMetadata, createComponents, createRegistry } from "./components-T2U31sZh.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";
 

package/dist/api.js

@@ -1,4 +1,4 @@
-const require_components = require('./components-BRLB21IO.js');
+const require_components = require('./components-DpACv95L.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-DuIz-WUQ.mjs";
+import { createComponents, createRegistry, isAnyZodType, unwrapZodObject } from "./components-CUMu4QeI.mjs";
 
 export { createComponents, createRegistry, isAnyZodType, unwrapZodObject };

package/dist/{components-Dus8apcN.d.mts → components-CCPXuBcU.d.mts}

@@ -366,6 +366,10 @@ interface ZodOpenApiBaseMetadata {
 }
 interface ZodOpenApiMetadata extends ZodOpenApiBaseMetadata, core.JSONSchemaMeta {
   examples?: unknown[];
+  /**
+   * @deprecated - Use `examples` instead.
+   * Use of `example` is discouraged, and later versions of OpenAPI specification may remove it.
+   */
   example?: unknown;
 }
 declare module 'zod/v4' {

package/dist/{components-DuIz-WUQ.mjs → components-CUMu4QeI.mjs}

@@ -27,7 +27,7 @@ const createMediaTypeObject = (mediaType, ctx, path) => {
 			source: { type: "mediaType" }
 		});
 		mediaTypeObject.schema = schemaObject;
-	}
+	} else mediaTypeObject.schema = schema;
 	if (examples) mediaTypeObject.examples = createExamples(examples, ctx.registry, [...path, "examples"]);
 	return mediaTypeObject;
 };

package/dist/{components-T2U31sZh.d.ts → components-D8Br4Oqx.d.ts}

@@ -366,6 +366,10 @@ interface ZodOpenApiBaseMetadata {
 }
 interface ZodOpenApiMetadata extends ZodOpenApiBaseMetadata, core.JSONSchemaMeta {
   examples?: unknown[];
+  /**
+   * @deprecated - Use `examples` instead.
+   * Use of `example` is discouraged, and later versions of OpenAPI specification may remove it.
+   */
   example?: unknown;
 }
 declare module 'zod/v4' {

package/dist/{components-BRLB21IO.js → components-DpACv95L.js}

@@ -50,7 +50,7 @@ const createMediaTypeObject = (mediaType, ctx, path) => {
 			source: { type: "mediaType" }
 		});
 		mediaTypeObject.schema = schemaObject;
-	}
+	} else mediaTypeObject.schema = schema;
 	if (examples) mediaTypeObject.examples = createExamples(examples, ctx.registry, [...path, "examples"]);
 	return mediaTypeObject;
 };

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, ZodOpenApiBaseMetadata, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiExampleObject, ZodOpenApiExamplesObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiLinkObject, ZodOpenApiLinksObject, ZodOpenApiMediaTypeObject, ZodOpenApiMetadata, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiSecuritySchemeObject, ZodOpenApiVersion, createDocument } from "./components-Dus8apcN.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, ZodOpenApiBaseMetadata, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiExampleObject, ZodOpenApiExamplesObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiLinkObject, ZodOpenApiLinksObject, ZodOpenApiMediaTypeObject, ZodOpenApiMetadata, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiSecuritySchemeObject, ZodOpenApiVersion, createDocument } from "./components-CCPXuBcU.mjs";
 import { core } from "zod/v4";
 
 //#region rolldown:runtime

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, ZodOpenApiBaseMetadata, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiExampleObject, ZodOpenApiExamplesObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiLinkObject, ZodOpenApiLinksObject, ZodOpenApiMediaTypeObject, ZodOpenApiMetadata, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiSecuritySchemeObject, ZodOpenApiVersion, createDocument } from "./components-T2U31sZh.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, ZodOpenApiBaseMetadata, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiExampleObject, ZodOpenApiExamplesObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiLinkObject, ZodOpenApiLinksObject, ZodOpenApiMediaTypeObject, ZodOpenApiMetadata, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiSecuritySchemeObject, ZodOpenApiVersion, createDocument } from "./components-D8Br4Oqx.js";
 import { core } from "zod/v4";
 
 //#region rolldown:runtime

package/dist/index.js

@@ -1,4 +1,4 @@
-const require_components = require('./components-BRLB21IO.js');
+const require_components = require('./components-DpACv95L.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-DuIz-WUQ.mjs";
+import { createComponents, createPaths, createRegistry, createSchema } from "./components-CUMu4QeI.mjs";
 
 //#region src/create/document.ts
 const createDocument = (zodOpenApiObject, opts = {}) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-openapi",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Convert Zod Schemas to OpenAPI v3.x documentation",
   "keywords": [
     "typescript",
@@ -19,6 +19,7 @@
     "type": "git",
     "url": "git+ssh://git@github.com/samchungy/zod-openapi.git"
   },
+  "funding": "https://github.com/samchungy/zod-openapi?sponsor=1",
   "license": "MIT",
   "sideEffects": false,
   "exports": {
@@ -39,20 +40,10 @@
     "dist",
     "api"
   ],
-  "scripts": {
-    "build": "pnpm copy:types && tsdown",
-    "copy:types": "skuba node scripts/copyTypes.ts",
-    "create:docs": " skuba node examples/simple/createSchema.ts && redocly build-docs examples/simple/openapi.yml --output=examples/simple/redoc-static.html",
-    "format": "skuba format",
-    "lint": "skuba lint",
-    "prepare": "pnpm build",
-    "test": "skuba test",
-    "test:ci": "skuba test --coverage",
-    "test:watch": "skuba test --watch"
-  },
   "devDependencies": {
-    "@arethetypeswrong/cli": "0.18.1",
-    "@redocly/cli": "1.34.3",
+    "@arethetypeswrong/cli": "0.18.2",
+    "@changesets/cli": "2.29.5",
+    "@redocly/cli": "1.34.4",
     "@types/node": "22.15.21",
     "ajv": "8.17.1",
     "eslint-plugin-import-zod": "1.0.3",
@@ -66,7 +57,6 @@
   "peerDependencies": {
     "zod": "^3.25.74"
   },
-  "packageManager": "pnpm@10.11.0",
   "engines": {
     "node": ">=20"
   },
@@ -79,5 +69,16 @@
     "template": "oss-npm-package",
     "type": "package",
     "version": "11.0.0"
+  },
+  "scripts": {
+    "build": "pnpm copy:types && tsdown",
+    "copy:types": "skuba node scripts/copyTypes.ts",
+    "create:docs": " skuba node examples/simple/createSchema.ts && redocly build-docs examples/simple/openapi.yml --output=examples/simple/redoc-static.html",
+    "format": "skuba format",
+    "lint": "skuba lint",
+    "release": "pnpm build && changeset publish",
+    "test": "skuba test",
+    "test:ci": "skuba test --coverage",
+    "test:watch": "skuba test --watch"
   }
-}
+}