zod-openapi 5.0.0-beta.9 → 5.0.0

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

@@ -1,5 +1,5 @@
+import * as core from "zod/v4/core";
 import { $ZodType, $ZodTypes } from "zod/v4/core";
-import { core } from "zod/v4";
 
 //#region src/openapi3-ts/dist/model/specification-extension.d.ts
 type IExtensionName = `x-${string}`;
@@ -329,42 +329,47 @@ type Override = (ctx: {
   jsonSchema: core.JSONSchema.BaseSchema;
   io: 'input' | 'output';
 }) => void;
-declare module 'zod/v4' {
-  interface GlobalMeta {
-    /**
-     * Used to set metadata for a parameter
-     */
-    param?: Partial<ParameterObject> & {
-      /**
-       * Used to output this Zod Schema in the components parameters section. Any usage of this Zod Schema will then be transformed into a $ref.
-       */
-      id?: string;
-    };
-    /**
-     * Used to set metadata for a response header
-     */
-    header?: Partial<HeaderObject> & {
-      /**
-       * Used to output this Zod Schema in the components headers section. Any usage of this Zod Schema will then be transformed into a $ref.
-       */
-      id?: string;
-    };
-    /**
-     * Use to override the rendered schema
-     */
-    override?: SchemaObject | Override;
+interface ZodOpenApiBaseMetadata {
+  /**
+   * Used to set metadata for a parameter
+   */
+  param?: Partial<ParameterObject> & {
     /**
-     * For use only if this Zod Schema is manually registered in the `components` section
-     * and is not used anywhere else in the document.
-     * Defaults to `output` if not specified.
+     * Used to output this Zod Schema in the components parameters section. Any usage of this Zod Schema will then be transformed into a $ref.
      */
-    unusedIO?: 'input' | 'output';
+    id?: string;
+  };
+  /**
+   * Used to set metadata for a response header
+   */
+  header?: Partial<HeaderObject> & {
     /**
-     * An alternate id to use for this schema in the event the schema is used in both input and output contexts.
-     * If not specified, the id will be simply derived as the id of the schema plus an `Output` suffix. Please note that `id` must be set.
+     * Used to output this Zod Schema in the components headers section. Any usage of this Zod Schema will then be transformed into a $ref.
      */
-    outputId?: string;
-  }
+    id?: string;
+  };
+  /**
+   * Use to override the rendered schema
+   */
+  override?: SchemaObject | Override;
+  /**
+   * For use only if this Zod Schema is manually registered in the `components` section
+   * and is not used anywhere else in the document.
+   * Defaults to `output` if not specified.
+   */
+  unusedIO?: 'input' | 'output';
+  /**
+   * An alternate id to use for this schema in the event a registered schema is used in both a request and response schema.
+   * If not specified, the id will be simply derived as the id of the schema plus an `Output` suffix. Please note that `id` must be set.
+   */
+  outputId?: string;
+}
+interface ZodOpenApiMetadata extends ZodOpenApiBaseMetadata, core.JSONSchemaMeta {
+  examples?: unknown[];
+  example?: unknown;
+}
+declare module 'zod/v4' {
+  interface GlobalMeta extends ZodOpenApiMetadata {}
 }
 //#endregion
 //#region src/create/document.d.ts
@@ -381,9 +386,10 @@ interface ZodOpenApiRequestBodyObject extends Omit<RequestBodyObject, 'content'>
   id?: string;
 }
 type ZodOpenApiHeadersObject = ZodObjectInput | HeadersObject;
-interface ZodOpenApiResponseObject extends Omit<ResponseObject, 'content' | 'headers'> {
+interface ZodOpenApiResponseObject extends Omit<ResponseObject, 'content' | 'headers' | 'links'> {
   content?: ZodOpenApiContentObject;
   headers?: ZodOpenApiHeadersObject;
+  links?: ZodOpenApiLinksObject;
   /** Use this field to auto register this response object as a component */
   id?: string;
 }
@@ -427,8 +433,23 @@ interface ZodOpenApiPathsObject extends ISpecificationExtension {
 type ZodOpenApiParameterObject = $ZodType | ParameterObject | ReferenceObject;
 type ZodOpenApiHeaderObject = $ZodType | HeaderObject | ReferenceObject;
 type ZodOpenApiSchemaObject = $ZodType | SchemaObject | ReferenceObject;
-type ZodOpenApiRequestBody = $ZodType | RequestBodyObject | ReferenceObject;
-interface ZodOpenApiComponentsObject extends Omit<ComponentsObject, 'schemas' | 'responses' | 'requestBodies' | 'headers' | 'parameters' | 'pathItems' | 'callbacks'> {
+interface ZodOpenApiSecuritySchemeObject extends SecuritySchemeObject {
+  /**
+   * Used to register this security scheme as a component.
+   */
+  id?: string;
+}
+interface ZodOpenApiLinkObject extends LinkObject {
+  /** Use this field to auto register this link object as a component */
+  id?: string;
+}
+type ZodOpenApiLinksObject = Record<string, ZodOpenApiLinkObject | ReferenceObject>;
+interface ZodOpenApiExampleObject extends ExampleObject {
+  /** Use this field to auto register this example object as a component */
+  id?: string;
+}
+type ZodOpenApiExamplesObject = Record<string, ZodOpenApiExampleObject | ReferenceObject>;
+interface ZodOpenApiComponentsObject extends Omit<ComponentsObject, 'schemas' | 'responses' | 'requestBodies' | 'headers' | 'parameters' | 'pathItems' | 'callbacks' | 'securitySchemes' | 'examples'> {
   parameters?: Record<string, ZodOpenApiParameterObject>;
   schemas?: Record<string, ZodOpenApiSchemaObject>;
   requestBodies?: Record<string, ZodOpenApiRequestBodyObject>;
@@ -436,6 +457,9 @@ interface ZodOpenApiComponentsObject extends Omit<ComponentsObject, 'schemas' |
   responses?: Record<string, ZodOpenApiResponseObject>;
   callbacks?: Record<string, ZodOpenApiCallbackObject>;
   pathItems?: Record<string, ZodOpenApiPathItemObject>;
+  securitySchemes?: Record<string, ZodOpenApiSecuritySchemeObject>;
+  links?: Record<string, ZodOpenApiLinkObject>;
+  examples?: Record<string, ZodOpenApiExampleObject>;
 }
 type ZodOpenApiVersion = OpenApiVersion;
 interface ZodOpenApiObject extends Omit<OpenAPIObject, 'openapi' | 'paths' | 'webhooks' | 'components'> {
@@ -449,10 +473,10 @@ type OverrideType = $ZodTypes['_zod']['def']['type'];
 interface CreateDocumentOptions {
   /**
    * Use this to allowlist empty schemas to be created for given types
-   * - `true` — Allow empty schemas for input and output
-   * - `{ input: true, output: true }` — Allow empty schemas for input and output
-   * - `{ input: true }` — Allow empty schemas for input only
-   * - `{ output: true }` — Allow empty schemas for output only
+   * - `{ [ZodType]: true}` — Allow empty schemas for input and output
+   * - `{ [ZodType]: { input: true, output: true } }` — Allow empty schemas for input and output
+   * - `{ [ZodType]: { input: true } }` — Allow empty schemas for input only
+   * - `{ [ZodType]: { output: true } }` — Allow empty schemas for output only
    */
   allowEmptySchema?: Partial<Record<OverrideType, true | Partial<{
     input: true;
@@ -464,6 +488,14 @@ interface CreateDocumentOptions {
    * - `(ctx) => { ctx.jsonSchema.type = 'string'; }` — Override the schema type to be a string using a function
    */
   override?: Override;
+  /**
+   * Suffix to append to the output ID of the schema.
+   * This is useful to avoid conflicts with other schemas that may have the same name.
+   * For example, if you have a schema named `Person`, you can set this to `Response` to get `PersonResponse`.
+   * If not set, the default suffix is `Output`.
+   * @default 'Output'
+   */
+  outputIdSuffix?: string;
   /**
    * How to handle reused schemas.
    * - `"ref"` — Reused schemas will be rendered as references
@@ -478,60 +510,120 @@ interface CreateDocumentOptions {
 declare const createDocument: (zodOpenApiObject: ZodOpenApiObject, opts?: CreateDocumentOptions) => OpenAPIObject;
 //#endregion
 //#region src/create/components.d.ts
-interface ComponentRegistry {
-  /**
-   * Contains a map of component name to their OpenAPI schema object or reference.
-   */
-  schemas: {
-    dynamicSchemaCount: number;
-    input: Map<string, {
-      zodType: $ZodType;
-      schemaObject: SchemaObject | ReferenceObject;
-    }>;
-    output: Map<string, {
-      zodType: $ZodType;
-      schemaObject: SchemaObject | ReferenceObject;
-    }>;
-    ids: Map<string, SchemaObject | ReferenceObject>;
-    manual: Map<string, {
-      input: {
-        used?: true;
-        schemaObject: SchemaObject;
-      };
-      output: {
-        used?: true;
-        schemaObject: SchemaObject;
-      };
-      zodType: $ZodType;
-    }>;
-    setSchema: (key: string, schema: $ZodType, io: 'input' | 'output') => SchemaObject | ReferenceObject;
-  };
-  headers: {
-    ids: Map<string, HeaderObject | ReferenceObject>;
-    seen: WeakMap<$ZodType, HeaderObject | ReferenceObject>;
-  };
-  requestBodies: {
-    ids: Map<string, RequestBodyObject | ReferenceObject>;
-    seen: WeakMap<ZodOpenApiRequestBodyObject, RequestBodyObject | ReferenceObject>;
-  };
-  responses: {
-    ids: Map<string, ResponseObject | ReferenceObject>;
-    seen: WeakMap<ZodOpenApiResponseObject, ResponseObject | ReferenceObject>;
-  };
-  parameters: {
-    ids: Map<string, ParameterObject | ReferenceObject>;
-    seen: WeakMap<$ZodType, ParameterObject | ReferenceObject>;
+type SchemaSource = {
+  type: 'mediaType' | 'header';
+} | {
+  type: 'parameter';
+  location: {
+    in: string;
+    name: string;
   };
-  callbacks: {
-    ids: Map<string, ZodOpenApiCallbackObject | ReferenceObject>;
-    seen: WeakMap<ZodOpenApiCallbackObject, ZodOpenApiCallbackObject | ReferenceObject>;
-  };
-  pathItems: {
-    ids: Map<string, PathItemObject | ReferenceObject>;
-    seen: WeakMap<ZodOpenApiPathItemObject, PathItemObject | ReferenceObject>;
+};
+interface ComponentRegistry {
+  components: {
+    schemas: {
+      dynamicSchemaCount: number;
+      input: Map<string, {
+        zodType: $ZodType;
+        schemaObject: SchemaObject | ReferenceObject;
+        source: SchemaSource & {
+          path: string[];
+        };
+      }>;
+      output: Map<string, {
+        zodType: $ZodType;
+        schemaObject: SchemaObject | ReferenceObject;
+        source: SchemaSource & {
+          path: string[];
+        };
+      }>;
+      ids: Map<string, SchemaObject | ReferenceObject>;
+      manual: Map<string, {
+        input: {
+          used?: true;
+          schemaObject: SchemaObject;
+        };
+        output: {
+          used?: true;
+          schemaObject: SchemaObject;
+        };
+        zodType: $ZodType;
+      }>;
+    };
+    headers: {
+      ids: Map<string, HeaderObject | ReferenceObject>;
+      seen: WeakMap<$ZodType, HeaderObject | ReferenceObject>;
+    };
+    requestBodies: {
+      ids: Map<string, RequestBodyObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiRequestBodyObject, RequestBodyObject | ReferenceObject>;
+    };
+    responses: {
+      ids: Map<string, ResponseObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiResponseObject, ResponseObject | ReferenceObject>;
+    };
+    parameters: {
+      ids: Map<string, ParameterObject | ReferenceObject>;
+      seen: WeakMap<$ZodType, ParameterObject | ReferenceObject>;
+    };
+    callbacks: {
+      ids: Map<string, ZodOpenApiCallbackObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiCallbackObject, ZodOpenApiCallbackObject | ReferenceObject>;
+    };
+    pathItems: {
+      ids: Map<string, PathItemObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiPathItemObject, PathItemObject | ReferenceObject>;
+    };
+    securitySchemes: {
+      ids: Map<string, SecuritySchemeObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiSecuritySchemeObject, SecuritySchemeObject | ReferenceObject>;
+    };
+    links: {
+      ids: Map<string, LinkObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiLinkObject, LinkObject | ReferenceObject>;
+    };
+    examples: {
+      ids: Map<string, ExampleObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiExampleObject, ExampleObject | ReferenceObject>;
+    };
   };
+  addSchema: (schema: $ZodType, path: string[], opts: {
+    io: 'input' | 'output';
+    source: SchemaSource;
+  }) => SchemaObject | ReferenceObject;
+  addHeader: (header: $ZodType, path: string[], opts?: {
+    manualId?: string;
+  }) => HeaderObject | ReferenceObject;
+  addParameter: (parameter: $ZodType, path: string[], opts?: {
+    location?: {
+      in: ParameterLocation;
+      name: string;
+    };
+    manualId?: string;
+  }) => ParameterObject | ReferenceObject;
+  addRequestBody: (requestBody: ZodOpenApiRequestBodyObject, path: string[], opts?: {
+    manualId?: string;
+  }) => RequestBodyObject | ReferenceObject;
+  addPathItem: (pathItem: ZodOpenApiPathItemObject, path: string[], opts?: {
+    manualId?: string;
+  }) => PathItemObject | ReferenceObject;
+  addResponse: (response: ZodOpenApiResponseObject, path: string[], opts?: {
+    manualId?: string;
+  }) => ResponseObject | ReferenceObject;
+  addCallback: (callback: ZodOpenApiCallbackObject, path: string[], opts?: {
+    manualId?: string;
+  }) => CallbackObject | ReferenceObject;
+  addSecurityScheme: (securityScheme: ZodOpenApiSecuritySchemeObject, path: string[], opts?: {
+    manualId?: string;
+  }) => SecuritySchemeObject | ReferenceObject;
+  addLink: (link: ZodOpenApiLinkObject, path: string[], opts?: {
+    manualId?: string;
+  }) => LinkObject | ReferenceObject;
+  addExample: (example: ZodOpenApiExampleObject, path: string[], opts?: {
+    manualId?: string;
+  }) => ExampleObject | ReferenceObject;
 }
 declare const createRegistry: (components?: ZodOpenApiComponentsObject) => ComponentRegistry;
 declare const createComponents: (registry: ComponentRegistry, opts: CreateDocumentOptions) => ComponentsObject;
 //#endregion
-export { 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, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiMediaTypeObject, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBody, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiVersion, createComponents, createDocument, createRegistry };
+export { 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, createComponents, createDocument, createRegistry };

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

@@ -1,5 +1,5 @@
+import * as core from "zod/v4/core";
 import { $ZodType, $ZodTypes } from "zod/v4/core";
-import { core } from "zod/v4";
 
 //#region src/openapi3-ts/dist/model/specification-extension.d.ts
 type IExtensionName = `x-${string}`;
@@ -329,42 +329,47 @@ type Override = (ctx: {
   jsonSchema: core.JSONSchema.BaseSchema;
   io: 'input' | 'output';
 }) => void;
-declare module 'zod/v4' {
-  interface GlobalMeta {
-    /**
-     * Used to set metadata for a parameter
-     */
-    param?: Partial<ParameterObject> & {
-      /**
-       * Used to output this Zod Schema in the components parameters section. Any usage of this Zod Schema will then be transformed into a $ref.
-       */
-      id?: string;
-    };
-    /**
-     * Used to set metadata for a response header
-     */
-    header?: Partial<HeaderObject> & {
-      /**
-       * Used to output this Zod Schema in the components headers section. Any usage of this Zod Schema will then be transformed into a $ref.
-       */
-      id?: string;
-    };
-    /**
-     * Use to override the rendered schema
-     */
-    override?: SchemaObject | Override;
+interface ZodOpenApiBaseMetadata {
+  /**
+   * Used to set metadata for a parameter
+   */
+  param?: Partial<ParameterObject> & {
     /**
-     * For use only if this Zod Schema is manually registered in the `components` section
-     * and is not used anywhere else in the document.
-     * Defaults to `output` if not specified.
+     * Used to output this Zod Schema in the components parameters section. Any usage of this Zod Schema will then be transformed into a $ref.
      */
-    unusedIO?: 'input' | 'output';
+    id?: string;
+  };
+  /**
+   * Used to set metadata for a response header
+   */
+  header?: Partial<HeaderObject> & {
     /**
-     * An alternate id to use for this schema in the event the schema is used in both input and output contexts.
-     * If not specified, the id will be simply derived as the id of the schema plus an `Output` suffix. Please note that `id` must be set.
+     * Used to output this Zod Schema in the components headers section. Any usage of this Zod Schema will then be transformed into a $ref.
      */
-    outputId?: string;
-  }
+    id?: string;
+  };
+  /**
+   * Use to override the rendered schema
+   */
+  override?: SchemaObject | Override;
+  /**
+   * For use only if this Zod Schema is manually registered in the `components` section
+   * and is not used anywhere else in the document.
+   * Defaults to `output` if not specified.
+   */
+  unusedIO?: 'input' | 'output';
+  /**
+   * An alternate id to use for this schema in the event a registered schema is used in both a request and response schema.
+   * If not specified, the id will be simply derived as the id of the schema plus an `Output` suffix. Please note that `id` must be set.
+   */
+  outputId?: string;
+}
+interface ZodOpenApiMetadata extends ZodOpenApiBaseMetadata, core.JSONSchemaMeta {
+  examples?: unknown[];
+  example?: unknown;
+}
+declare module 'zod/v4' {
+  interface GlobalMeta extends ZodOpenApiMetadata {}
 }
 //#endregion
 //#region src/create/document.d.ts
@@ -381,9 +386,10 @@ interface ZodOpenApiRequestBodyObject extends Omit<RequestBodyObject, 'content'>
   id?: string;
 }
 type ZodOpenApiHeadersObject = ZodObjectInput | HeadersObject;
-interface ZodOpenApiResponseObject extends Omit<ResponseObject, 'content' | 'headers'> {
+interface ZodOpenApiResponseObject extends Omit<ResponseObject, 'content' | 'headers' | 'links'> {
   content?: ZodOpenApiContentObject;
   headers?: ZodOpenApiHeadersObject;
+  links?: ZodOpenApiLinksObject;
   /** Use this field to auto register this response object as a component */
   id?: string;
 }
@@ -427,8 +433,23 @@ interface ZodOpenApiPathsObject extends ISpecificationExtension {
 type ZodOpenApiParameterObject = $ZodType | ParameterObject | ReferenceObject;
 type ZodOpenApiHeaderObject = $ZodType | HeaderObject | ReferenceObject;
 type ZodOpenApiSchemaObject = $ZodType | SchemaObject | ReferenceObject;
-type ZodOpenApiRequestBody = $ZodType | RequestBodyObject | ReferenceObject;
-interface ZodOpenApiComponentsObject extends Omit<ComponentsObject, 'schemas' | 'responses' | 'requestBodies' | 'headers' | 'parameters' | 'pathItems' | 'callbacks'> {
+interface ZodOpenApiSecuritySchemeObject extends SecuritySchemeObject {
+  /**
+   * Used to register this security scheme as a component.
+   */
+  id?: string;
+}
+interface ZodOpenApiLinkObject extends LinkObject {
+  /** Use this field to auto register this link object as a component */
+  id?: string;
+}
+type ZodOpenApiLinksObject = Record<string, ZodOpenApiLinkObject | ReferenceObject>;
+interface ZodOpenApiExampleObject extends ExampleObject {
+  /** Use this field to auto register this example object as a component */
+  id?: string;
+}
+type ZodOpenApiExamplesObject = Record<string, ZodOpenApiExampleObject | ReferenceObject>;
+interface ZodOpenApiComponentsObject extends Omit<ComponentsObject, 'schemas' | 'responses' | 'requestBodies' | 'headers' | 'parameters' | 'pathItems' | 'callbacks' | 'securitySchemes' | 'examples'> {
   parameters?: Record<string, ZodOpenApiParameterObject>;
   schemas?: Record<string, ZodOpenApiSchemaObject>;
   requestBodies?: Record<string, ZodOpenApiRequestBodyObject>;
@@ -436,6 +457,9 @@ interface ZodOpenApiComponentsObject extends Omit<ComponentsObject, 'schemas' |
   responses?: Record<string, ZodOpenApiResponseObject>;
   callbacks?: Record<string, ZodOpenApiCallbackObject>;
   pathItems?: Record<string, ZodOpenApiPathItemObject>;
+  securitySchemes?: Record<string, ZodOpenApiSecuritySchemeObject>;
+  links?: Record<string, ZodOpenApiLinkObject>;
+  examples?: Record<string, ZodOpenApiExampleObject>;
 }
 type ZodOpenApiVersion = OpenApiVersion;
 interface ZodOpenApiObject extends Omit<OpenAPIObject, 'openapi' | 'paths' | 'webhooks' | 'components'> {
@@ -449,10 +473,10 @@ type OverrideType = $ZodTypes['_zod']['def']['type'];
 interface CreateDocumentOptions {
   /**
    * Use this to allowlist empty schemas to be created for given types
-   * - `true` — Allow empty schemas for input and output
-   * - `{ input: true, output: true }` — Allow empty schemas for input and output
-   * - `{ input: true }` — Allow empty schemas for input only
-   * - `{ output: true }` — Allow empty schemas for output only
+   * - `{ [ZodType]: true}` — Allow empty schemas for input and output
+   * - `{ [ZodType]: { input: true, output: true } }` — Allow empty schemas for input and output
+   * - `{ [ZodType]: { input: true } }` — Allow empty schemas for input only
+   * - `{ [ZodType]: { output: true } }` — Allow empty schemas for output only
    */
   allowEmptySchema?: Partial<Record<OverrideType, true | Partial<{
     input: true;
@@ -464,6 +488,14 @@ interface CreateDocumentOptions {
    * - `(ctx) => { ctx.jsonSchema.type = 'string'; }` — Override the schema type to be a string using a function
    */
   override?: Override;
+  /**
+   * Suffix to append to the output ID of the schema.
+   * This is useful to avoid conflicts with other schemas that may have the same name.
+   * For example, if you have a schema named `Person`, you can set this to `Response` to get `PersonResponse`.
+   * If not set, the default suffix is `Output`.
+   * @default 'Output'
+   */
+  outputIdSuffix?: string;
   /**
    * How to handle reused schemas.
    * - `"ref"` — Reused schemas will be rendered as references
@@ -478,60 +510,120 @@ interface CreateDocumentOptions {
 declare const createDocument: (zodOpenApiObject: ZodOpenApiObject, opts?: CreateDocumentOptions) => OpenAPIObject;
 //#endregion
 //#region src/create/components.d.ts
-interface ComponentRegistry {
-  /**
-   * Contains a map of component name to their OpenAPI schema object or reference.
-   */
-  schemas: {
-    dynamicSchemaCount: number;
-    input: Map<string, {
-      zodType: $ZodType;
-      schemaObject: SchemaObject | ReferenceObject;
-    }>;
-    output: Map<string, {
-      zodType: $ZodType;
-      schemaObject: SchemaObject | ReferenceObject;
-    }>;
-    ids: Map<string, SchemaObject | ReferenceObject>;
-    manual: Map<string, {
-      input: {
-        used?: true;
-        schemaObject: SchemaObject;
-      };
-      output: {
-        used?: true;
-        schemaObject: SchemaObject;
-      };
-      zodType: $ZodType;
-    }>;
-    setSchema: (key: string, schema: $ZodType, io: 'input' | 'output') => SchemaObject | ReferenceObject;
-  };
-  headers: {
-    ids: Map<string, HeaderObject | ReferenceObject>;
-    seen: WeakMap<$ZodType, HeaderObject | ReferenceObject>;
-  };
-  requestBodies: {
-    ids: Map<string, RequestBodyObject | ReferenceObject>;
-    seen: WeakMap<ZodOpenApiRequestBodyObject, RequestBodyObject | ReferenceObject>;
-  };
-  responses: {
-    ids: Map<string, ResponseObject | ReferenceObject>;
-    seen: WeakMap<ZodOpenApiResponseObject, ResponseObject | ReferenceObject>;
-  };
-  parameters: {
-    ids: Map<string, ParameterObject | ReferenceObject>;
-    seen: WeakMap<$ZodType, ParameterObject | ReferenceObject>;
+type SchemaSource = {
+  type: 'mediaType' | 'header';
+} | {
+  type: 'parameter';
+  location: {
+    in: string;
+    name: string;
   };
-  callbacks: {
-    ids: Map<string, ZodOpenApiCallbackObject | ReferenceObject>;
-    seen: WeakMap<ZodOpenApiCallbackObject, ZodOpenApiCallbackObject | ReferenceObject>;
-  };
-  pathItems: {
-    ids: Map<string, PathItemObject | ReferenceObject>;
-    seen: WeakMap<ZodOpenApiPathItemObject, PathItemObject | ReferenceObject>;
+};
+interface ComponentRegistry {
+  components: {
+    schemas: {
+      dynamicSchemaCount: number;
+      input: Map<string, {
+        zodType: $ZodType;
+        schemaObject: SchemaObject | ReferenceObject;
+        source: SchemaSource & {
+          path: string[];
+        };
+      }>;
+      output: Map<string, {
+        zodType: $ZodType;
+        schemaObject: SchemaObject | ReferenceObject;
+        source: SchemaSource & {
+          path: string[];
+        };
+      }>;
+      ids: Map<string, SchemaObject | ReferenceObject>;
+      manual: Map<string, {
+        input: {
+          used?: true;
+          schemaObject: SchemaObject;
+        };
+        output: {
+          used?: true;
+          schemaObject: SchemaObject;
+        };
+        zodType: $ZodType;
+      }>;
+    };
+    headers: {
+      ids: Map<string, HeaderObject | ReferenceObject>;
+      seen: WeakMap<$ZodType, HeaderObject | ReferenceObject>;
+    };
+    requestBodies: {
+      ids: Map<string, RequestBodyObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiRequestBodyObject, RequestBodyObject | ReferenceObject>;
+    };
+    responses: {
+      ids: Map<string, ResponseObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiResponseObject, ResponseObject | ReferenceObject>;
+    };
+    parameters: {
+      ids: Map<string, ParameterObject | ReferenceObject>;
+      seen: WeakMap<$ZodType, ParameterObject | ReferenceObject>;
+    };
+    callbacks: {
+      ids: Map<string, ZodOpenApiCallbackObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiCallbackObject, ZodOpenApiCallbackObject | ReferenceObject>;
+    };
+    pathItems: {
+      ids: Map<string, PathItemObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiPathItemObject, PathItemObject | ReferenceObject>;
+    };
+    securitySchemes: {
+      ids: Map<string, SecuritySchemeObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiSecuritySchemeObject, SecuritySchemeObject | ReferenceObject>;
+    };
+    links: {
+      ids: Map<string, LinkObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiLinkObject, LinkObject | ReferenceObject>;
+    };
+    examples: {
+      ids: Map<string, ExampleObject | ReferenceObject>;
+      seen: WeakMap<ZodOpenApiExampleObject, ExampleObject | ReferenceObject>;
+    };
   };
+  addSchema: (schema: $ZodType, path: string[], opts: {
+    io: 'input' | 'output';
+    source: SchemaSource;
+  }) => SchemaObject | ReferenceObject;
+  addHeader: (header: $ZodType, path: string[], opts?: {
+    manualId?: string;
+  }) => HeaderObject | ReferenceObject;
+  addParameter: (parameter: $ZodType, path: string[], opts?: {
+    location?: {
+      in: ParameterLocation;
+      name: string;
+    };
+    manualId?: string;
+  }) => ParameterObject | ReferenceObject;
+  addRequestBody: (requestBody: ZodOpenApiRequestBodyObject, path: string[], opts?: {
+    manualId?: string;
+  }) => RequestBodyObject | ReferenceObject;
+  addPathItem: (pathItem: ZodOpenApiPathItemObject, path: string[], opts?: {
+    manualId?: string;
+  }) => PathItemObject | ReferenceObject;
+  addResponse: (response: ZodOpenApiResponseObject, path: string[], opts?: {
+    manualId?: string;
+  }) => ResponseObject | ReferenceObject;
+  addCallback: (callback: ZodOpenApiCallbackObject, path: string[], opts?: {
+    manualId?: string;
+  }) => CallbackObject | ReferenceObject;
+  addSecurityScheme: (securityScheme: ZodOpenApiSecuritySchemeObject, path: string[], opts?: {
+    manualId?: string;
+  }) => SecuritySchemeObject | ReferenceObject;
+  addLink: (link: ZodOpenApiLinkObject, path: string[], opts?: {
+    manualId?: string;
+  }) => LinkObject | ReferenceObject;
+  addExample: (example: ZodOpenApiExampleObject, path: string[], opts?: {
+    manualId?: string;
+  }) => ExampleObject | ReferenceObject;
 }
 declare const createRegistry: (components?: ZodOpenApiComponentsObject) => ComponentRegistry;
 declare const createComponents: (registry: ComponentRegistry, opts: CreateDocumentOptions) => ComponentsObject;
 //#endregion
-export { 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, ZodOpenApiCallbackObject, ZodOpenApiCallbacksObject, ZodOpenApiComponentsObject, ZodOpenApiContentObject, ZodOpenApiHeaderObject, ZodOpenApiHeadersObject, ZodOpenApiMediaTypeObject, ZodOpenApiObject, ZodOpenApiOperationObject, ZodOpenApiParameterObject, ZodOpenApiParameters, ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBody, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiResponsesObject, ZodOpenApiSchemaObject, ZodOpenApiVersion, createComponents, createDocument, createRegistry };
+export { 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, createComponents, createDocument, createRegistry };