zod-openapi

You can register reusable components in two ways:

1. Auto-registration: Add an id to the .meta() call of a Zod schema or parameter. The library will automatically create a $ref in the document and add the schema to the components section.
2. Manual registration: Explicitly define the component in the components property of the createDocument configuration object.

Supported component types include:

• schemas
• parameters
• headers
• responses
• callbacks
• pathItems
• securitySchemes
• links
• examples

// 1. Auto-registration via .meta({ id: '...' })
const jobId = z.string().meta({
  id: 'jobRef',
  param: { in: 'header', name: 'jobId' },
});

createDocument({
  paths: {
    '/jobs/{jobId}': {
      put: {
        requestParams: { header: z.object({ jobId }) },
      },
    },
  },
});

// 2. Manual registration
createDocument({
  components: {
    parameters: {
      jobRef: z.string().meta({ param: { in: 'header', name: 'jobId' } }),
    },
  },
});

Zod types are composed of an input and an output. This library distinguishes between these contexts to generate appropriate OpenAPI schemas:

• Input Context: Used for Request Parameters (query, path, header, cookie) and Request Bodies.
• Output Context: Used for Response Bodies and Response Headers.

Why this matters: A single Zod schema might render differently depending on the context. For example, a z.object() in an input context might not include additionalProperties: false, whereas in an output context, it might.

If a schema is used in both contexts, the library automatically generates two separate component schemas to avoid conflicts. You can customize the output schema name using .meta({ outputId: '...' }) or set a global suffix via createDocument's outputIdSuffix option.

// Customizing the output schema name to distinguish from input
const schema = z
  .object({
    name: z.string(),
  })
  .meta({
    id: 'MyObject',
    outputId: 'MyObjectResponse',
  });

zod-openapi v5 uses Zod's native toJSONSchema() method. This results in different behaviors for input and output schemas to better align with how Zod objects work:

• Input schemas: Allow additional properties by default (no additionalProperties specified).
• Output schemas: Strip extra properties (additionalProperties: false).

If an object schema with an id is used in both request (input) and response (output) contexts, the library automatically generates two separate component schemas (e.g., Person and PersonOutput).

Customization

• Custom output name: Use .meta({ id: 'Person', outputId: 'CustomOutputName' }).
• Global suffix: Set outputIdSuffix in CreateDocumentOptions to change the default "Output" suffix.
• Manual control: Use z.looseObject() (allows additional properties) or z.strictObject() (forbids them) to explicitly control behavior instead of the default z.object().

Note: If a schema contains dynamically created lazy components, they will not be reused between input and output schemas.

const schema = z
  .object({
    name: z.string(),
    age: z.number(),
  })
  .meta({
    id: 'Person',
  });

In v5, schema generation has moved from an immediate creation model to a registry-based lazy resolution model. Instead of functions returning fully populated schemas immediately, you now use a registry to manage schemas.

1. Create a Registry: Initialize a registry using createRegistry().
2. Add Schemas to Registry: Use registry.addSchema() to register your Zod schemas. This returns an empty reference object initially.
3. Generate Components: Call createComponents(registry, docOpts) to populate the registry, resolve all references, and generate the final schemas and components.

This approach enables better deduplication and automated lazy schema resolution.

// 1. Create a registry
const registry = createRegistry();

// 2. Add your schema to the registry (returns a reference)
const schema = registry.addSchema({
  schema,
  path,
  source: {
    type: 'mediaType',
  }
});

console.log(schema); // {} (empty reference)

// 3. Generate all schemas and components at once
const components = createComponents(registry, docOpts);

console.log(schema); // { type: 'string' } (now populated)

You can define request parameters in two ways:

1. Using requestParams: Group parameters by their location (path, query, cookie, or header) using a Zod object.
2. Using parameters: Use the traditional OpenAPI parameters array, where you can use .meta({ param: { ... } }) on Zod schemas to specify the location and name.

Note: When using .meta({ param: { ... } }), the id in .meta() can be used to register the parameter as a reusable component.

// Method 1: requestParams
createDocument({
  paths: {
    '/jobs/{a}': {
      put: {
        requestParams: {
          path: z.object({ a: z.string() }),
          query: z.object({ b: z.string() }),
          cookie: z.object({ cookie: z.string() }),
          header: z.object({ 'custom-header': z.string() }),
        },
      },
    },
  },
});

// Method 2: parameters array with .meta()
createDocument({
  paths: {
    '/jobs/{a}': {
      put: {
        parameters: [
          z.string().meta({
            param: {
              name: 'job-header',
              in: 'header',
            },
          }),
        ],
      },
    },
  },
});

Request Body

Set the schema field within the content object of the desired media type (e.g., 'application/json').

Responses

Set the schema field within the content object of the response status code. You can also define response headers using the headers key with a Zod schema.

// Request Body
createDocument({
  paths: {
    '/jobs': {
      get: {
        requestBody: {
          content: {
            'application/json': { schema: z.object({ a: z.string() }) },
          },
        },
      },
    },
  },
});

// Responses with Headers
createDocument({
  paths: {
    '/jobs': {
      get: {
        responses: {
          200: {
            description: '200 OK',
            content: {
              'application/json': { schema: z.object({ a: z.string() }) },
            },
            headers: z.object({
              'header-key': z.string(),
            }),
          },
        },
      },
    },
  },
});