openapi-schema-type 1.0.0

package/typings/openapi_spec_3.2_schema.d.ts

@@ -0,0 +1,1112 @@
+import type { JSONSchemaMeta202012 } from "json-schema-meta-type";
+
+/**
+ * OpenAPI 3.2 Specification TypeScript Type Definitions
+ * Generated from openapi_spec_3.2_schema_2025-09-17.json
+ */
+
+// ===============
+// MARK: Base Types
+// ===============
+export type SpecificationExtensionKey = `x-${string}`;
+
+/**
+ * Extension fields for OpenAPI specification
+ * Allows adding custom properties with names starting with "x-"
+ * $comment: https://spec.openapis.org/oas/v3.2#specification-extensions
+ */
+export type SpecificationExtensions = Record<
+    SpecificationExtensionKey,
+    unknown
+>;
+
+/**
+ * A simple object to allow referencing other components in the specification
+ * $comment: https://spec.openapis.org/oas/v3.2#reference-object
+ */
+export interface ReferenceObject {
+    /**
+     * The reference string
+     */
+    $ref: string;
+    /**
+     * A short summary which by default should override that of the referenced component
+     */
+    summary?: string;
+    /**
+     * A description which by default should override that of the referenced component
+     */
+    description?: string;
+}
+
+/**
+ * The Schema Object allows the definition of input and output data types
+ */
+export type SchemaObject = Exclude<JSONSchemaMeta202012, boolean>;
+
+/**
+ * A simple map of string to string
+ */
+export type MapOfString = Record<string, string>;
+
+// ===============
+// MARK: Info Objects
+// ===============
+
+/**
+ * The object provides metadata about the API
+ * $comment: https://spec.openapis.org/oas/v3.2#info-object
+ */
+export type InfoObject = {
+    /**
+     * The title of the API
+     */
+    title: string;
+    /**
+     * A short summary of the API
+     */
+    summary?: string;
+    /**
+     * A verbose description of the API
+     * CommonMark syntax can be used for rich text representation
+     */
+    description?: string;
+    /**
+     * A URL to the Terms of Service for the API
+     * MUST be in URL format
+     */
+    termsOfService?: string;
+    /**
+     * The contact information for the exposed API
+     */
+    contact?: ContactObject;
+    /**
+     * The license information for the exposed API
+     */
+    license?: LicenseObject;
+    /**
+     * The version of the OpenAPI document
+     */
+    version: string;
+} & SpecificationExtensions;
+
+/**
+ * Contact information for the exposed API
+ * $comment: https://spec.openapis.org/oas/v3.2#contact-object
+ */
+export type ContactObject = {
+    /**
+     * The identifying name of the contact person/organization
+     */
+    name?: string;
+    /**
+     * The URL pointing to the contact information
+     * MUST be in URL format
+     */
+    url?: string;
+    /**
+     * The email address of the contact person/organization
+     * MUST be in email format
+     */
+    email?: string;
+} & SpecificationExtensions;
+
+/**
+ * License information for the exposed API
+ * $comment: https://spec.openapis.org/oas/v3.2#license-object
+ */
+export type LicenseObject = {
+    /**
+     * The license name used for the API
+     */
+    name: string;
+    /**
+     * An SPDX license expression for the API
+     */
+    identifier?: string;
+    /**
+     * A URL to the license used for the API
+     * MUST be in URL format
+     */
+    url?: string;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Server Objects
+// ===============
+
+/**
+ * An object representing a Server
+ * $comment: https://spec.openapis.org/oas/v3.2#server-object
+ */
+export type ServerObject = {
+    /**
+     * A URL to the target host
+     * May be a relative path
+     */
+    url: string;
+    /**
+     * An optional string describing the host designated by the URL
+     */
+    description?: string;
+    /**
+     * An optional name for the server
+     */
+    name?: string;
+    /**
+     * A map between a variable name and its value
+     */
+    variables?: Record<string, ServerVariableObject>;
+} & SpecificationExtensions;
+
+/**
+ * An object representing a Server Variable for server URL template substitution
+ * $comment: https://spec.openapis.org/oas/v3.2#server-variable-object
+ */
+export type ServerVariableObject = {
+    /**
+     * An enumeration of string values to be used if the substitution options are from a limited set
+     */
+    enum?: string[];
+    /**
+     * The default value to use for substitution
+     */
+    default: string;
+    /**
+     * An optional description for the server variable
+     */
+    description?: string;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Components Object
+// ===============
+
+/**
+ * Holds a set of reusable objects for different aspects of the OAS
+ * $comment: https://spec.openapis.org/oas/v3.2#components-object
+ */
+export type ComponentsObject = {
+    /**
+     * An object to hold reusable Schema Objects
+     */
+    schemas?: Record<string, SchemaObject>;
+    /**
+     * An object to hold reusable Response Objects
+     */
+    responses?: Record<string, ResponseOrReferenceObject>;
+    /**
+     * An object to hold reusable Parameter Objects
+     */
+    parameters?: Record<string, ParameterOrReferenceObject>;
+    /**
+     * An object to hold reusable Example Objects
+     */
+    examples?: Record<string, ExampleOrReferenceObject>;
+    /**
+     * An object to hold reusable Request Body Objects
+     */
+    requestBodies?: Record<string, RequestBodyOrReferenceObject>;
+    /**
+     * An object to hold reusable Header Objects
+     */
+    headers?: Record<string, HeaderOrReferenceObject>;
+    /**
+     * An object to hold reusable Security Scheme Objects
+     */
+    securitySchemes?: Record<string, SecuritySchemeOrReferenceObject>;
+    /**
+     * An object to hold reusable Link Objects
+     */
+    links?: Record<string, LinkOrReferenceObject>;
+    /**
+     * An object to hold reusable Callback Objects
+     */
+    callbacks?: Record<string, CallbacksOrReferenceObject>;
+    /**
+     * An object to hold reusable path item objects
+     */
+    pathItems?: Record<string, PathItemObject>;
+    /**
+     * An object to hold reusable media type objects
+     */
+    mediaTypes?: Record<string, MediaTypeOrReferenceObject>;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Paths and Operations
+// ===============
+
+export type PathKey = `/${string}`;
+/**
+ * Holds the relative paths to the individual endpoints and their operations
+ * $comment: https://spec.openapis.org/oas/v3.2#paths-object
+ */
+export type PathsObject = Record<PathKey, PathItemObject> &
+    SpecificationExtensions;
+
+/**
+ * Describes the operations available on a single path
+ * $comment: https://spec.openapis.org/oas/v3.2#path-item-object
+ */
+export type PathItemObject = {
+    /**
+     * A reference to a path item object
+     */
+    $ref?: string;
+    /**
+     * An optional, string summary
+     */
+    summary?: string;
+    /**
+     * An optional, string description
+     */
+    description?: string;
+    /**
+     * An alternative server array to service all operations in this path
+     */
+    servers?: ServerObject[];
+    /**
+     * A list of parameters that are applicable for all the operations described under this path
+     */
+    parameters?: ParameterObject[];
+    /**
+     * A map of operations that are not part of the standard HTTP methods
+     */
+    additionalOperations?: Record<string, OperationObject>;
+    /**
+     * A definition of a GET operation on this path
+     */
+    get?: OperationObject;
+    /**
+     * A definition of a PUT operation on this path
+     */
+    put?: OperationObject;
+    /**
+     * A definition of a POST operation on this path
+     */
+    post?: OperationObject;
+    /**
+     * A definition of a DELETE operation on this path
+     */
+    delete?: OperationObject;
+    /**
+     * A definition of an OPTIONS operation on this path
+     */
+    options?: OperationObject;
+    /**
+     * A definition of a HEAD operation on this path
+     */
+    head?: OperationObject;
+    /**
+     * A definition of a PATCH operation on this path
+     */
+    patch?: OperationObject;
+    /**
+     * A definition of a TRACE operation on this path
+     */
+    trace?: OperationObject;
+    /**
+     * A definition of a QUERY operation on this path
+     */
+    query?: OperationObject;
+} & SpecificationExtensions;
+
+/**
+ * Describes a single API operation on a path
+ * $comment: https://spec.openapis.org/oas/v3.2#operation-object
+ */
+export type OperationObject = {
+    /**
+     * A list of tags for API documentation control
+     */
+    tags?: string[];
+    /**
+     * A short summary of what the operation does
+     */
+    summary?: string;
+    /**
+     * A verbose explanation of the operation behavior
+     */
+    description?: string;
+    /**
+     * Additional external documentation for this operation
+     */
+    externalDocs?: ExternalDocumentationObject;
+    /**
+     * Unique string used to identify the operation
+     */
+    operationId?: string;
+    /**
+     * A list of parameters that are applicable for this operation
+     */
+    parameters?: ParameterObject[];
+    /**
+     * The request body applicable for this operation
+     */
+    requestBody?: RequestBodyOrReferenceObject;
+    /**
+     * The list of possible responses as they are returned from executing this operation
+     */
+    responses?: ResponsesObject;
+    /**
+     * A map of possible out-of-band callbacks related to the parent operation
+     */
+    callbacks?: Record<string, CallbacksOrReferenceObject>;
+    /**
+     * Declares this operation to be deprecated
+     */
+    deprecated?: boolean;
+    /**
+     * A declaration of which security schemes can be used for this operation
+     */
+    security?: SecurityRequirementObject[];
+    /**
+     * An alternative server array to service this operation
+     */
+    servers?: ServerObject[];
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Parameters
+// ===============
+
+/**
+ * The location of the parameter
+ */
+export type ParameterLocation =
+    | "query"
+    | "querystring"
+    | "header"
+    | "path"
+    | "cookie";
+
+type ParameterProperties = {
+    /**
+     * The name of the parameter
+     */
+    name: string;
+    /**
+     * A brief description of the parameter
+     */
+    description?: string;
+    /**
+     * Determines whether this parameter is mandatory
+     */
+    required?: boolean;
+    /**
+     * Specifies that a parameter is deprecated
+     */
+    deprecated?: boolean;
+    /**
+     * Example of the parameter's potential value
+     */
+    example?: unknown;
+    /**
+     * Examples of the parameter's potential value
+     */
+    examples?: Record<string, ExampleOrReferenceObject>;
+};
+
+type ParameterPropertiesForSchema = Exclude<ParameterProperties, "in"> & {
+    schema: SchemaObject;
+    /**
+     * When this is true, parameter values of type array or object generate separate parameters
+     */
+    explode?: boolean;
+    /**
+     * Determines whether the parameter value should be percent-encoded
+     * @default false
+     */
+    allowReserved?: boolean;
+}
+
+type ParameterStyleForPath = ParameterPropertiesForSchema & {
+    in: "path";
+    /**
+     * Describes how the parameter value will be serialized
+     * @default simple
+     */
+    style?: "simple" | "matrix" | "label";
+};
+
+type ParameterStyleForHeader = ParameterPropertiesForSchema & {
+    in: "header";
+    /**
+     * Describes how the parameter value will be serialized
+     * @default simple
+     */
+    style?: "simple";
+};
+type ParameterStyleForQuery = ParameterPropertiesForSchema & {
+    in: "query";
+    /**
+     * Describes how the parameter value will be serialized
+     * @default form
+     */
+    style?: "form" | "spaceDelimited" | "pipeDelimited" | "deepObject";
+    /**
+     * Specifies whether the parameter allows empty values
+     * Only applicable for query parameters
+     * @default false
+     */
+    allowEmptyValue?: boolean;
+};
+type ParameterStyleForCookie = ParameterPropertiesForSchema & {
+    in: "cookie";
+    /**
+     * Describes how the parameter value will be serialized
+     * @default form
+     */
+    style?: "form" | "cookie";
+};
+
+export type ParameterObjectWithSchema = ParameterStyleForPath | ParameterStyleForQuery | ParameterStyleForHeader | ParameterStyleForCookie;
+export type ParameterObjectWithContent = ParameterProperties & {
+    in?: "querystring";
+    /**
+     * A map containing the representations for the parameter
+     */
+    content: ContentObject;
+};
+/**
+ * Describes a single operation parameter
+ * $comment: https://spec.openapis.org/oas/v3.2#parameter-object
+ */
+export type ParameterObject = (ParameterObjectWithSchema | ParameterObjectWithContent) & SpecificationExtensions;
+
+// ===============
+// MARK: Request/Response Bodies
+// ===============
+
+/**
+ * Describes a single request body
+ * $comment: https://spec.openapis.org/oas/v3.2#request-body-object
+ */
+export type RequestBodyObject = {
+    /**
+     * A brief description of the request body
+     */
+    description?: string;
+    /**
+     * The content of the request body
+     */
+    content: ContentObject;
+    /**
+     * Determines if the request body is required in the request
+     */
+    required?: boolean;
+} & SpecificationExtensions;
+
+/**
+ * A container for the expected responses of an operation
+ * either default, or at least one response code property must exist
+ * $comment: https://spec.openapis.org/oas/v3.2#responses-object
+ */
+export type ResponsesObject = {
+    /**
+     * The documentation of responses other than the ones declared for specific HTTP response codes
+     */
+    default?: ResponseOrReferenceObject;
+    /**
+     * Any HTTP status code can be used as a property name
+     * statusCode pattern ^[1-5](?:[0-9]{2}|XX)$
+     */
+    [statusCode: `${number}` | `${number}XX`]: ResponseOrReferenceObject;
+} & SpecificationExtensions;
+
+/**
+ * Describes a single response from an API Operation
+ * $comment: https://spec.openapis.org/oas/v3.2#response-object
+ */
+export type ResponseObject = {
+    /**
+     * A short summary of the response
+     */
+    summary?: string;
+    /**
+     * A description of the response
+     */
+    description?: string;
+    /**
+     * Maps a header name to its definition
+     */
+    headers?: Record<string, HeaderOrReferenceObject>;
+    /**
+     * A map containing descriptions of potential response payloads
+     */
+    content?: ContentObject;
+    /**
+     * A map of operations links that can be followed from the response
+     */
+    links?: Record<string, LinkOrReferenceObject>;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Content and Media Types
+// ===============
+
+/**
+ * A map containing descriptions of potential response payloads
+ * $comment: https://spec.openapis.org/oas/v3.2#fixed-fields-10
+ */
+export interface ContentObject {
+    /**
+     * The media type of the content
+     */
+    [mediaType: string]: MediaTypeOrReferenceObject;
+}
+
+/**
+ * Provides schema and examples for the media type
+ * $comment: https://spec.openapis.org/oas/v3.2#media-type-object
+ */
+export type MediaTypeObject = {
+    /**
+     * A description of the media type
+     */
+    description?: string;
+    /**
+     * The schema defining the type used for the request body
+     */
+    schema?: SchemaObject;
+    /**
+     * The schema defining the type used for array items
+     */
+    itemSchema?: SchemaObject;
+    /**
+     * A map between a property name and its encoding information
+     */
+    encoding?: Record<string, EncodingObject>;
+    /**
+     * Encoding information for array prefixes
+     */
+    prefixEncoding?: EncodingObject[];
+    /**
+     * Encoding information for array items
+     */
+    itemEncoding?: EncodingObject;
+    /**
+     * Example of the media type
+     */
+    example?: unknown;
+    /**
+     * Examples of the media type
+     */
+    examples?: Record<string, ExampleOrReferenceObject>;
+} & SpecificationExtensions;
+
+/**
+ * A single encoding definition applied to a single schema property
+ * $comment: https://spec.openapis.org/oas/v3.2#encoding-object
+ */
+export type EncodingObject = {
+    /**
+     * The Content-Type for encoding a specific property
+     */
+    contentType?: string;
+    /**
+     * A map allowing additional information to be provided as headers
+     */
+    headers?: Record<string, HeaderOrReferenceObject>;
+    /**
+     * The style of the encoding
+     */
+    style?: "form" | "spaceDelimited" | "pipeDelimited" | "deepObject";
+    /**
+     * When this is true, property values of type array or object generate separate parameters
+     */
+    explode?: boolean;
+    /**
+     * Determines whether the parameter value should be percent-encoded
+     */
+    allowReserved?: boolean;
+    /**
+     * A map containing a mapping between property names and Encoding Objects
+     */
+    encoding?: Record<string, EncodingObject>;
+    /**
+     * Encoding information for array prefixes
+     */
+    prefixEncoding?: EncodingObject[];
+    /**
+     * Encoding information for array items
+     */
+    itemEncoding?: EncodingObject;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Examples
+// ===============
+
+/**
+ * Shows an example of a schema
+ * $comment: https://spec.openapis.org/oas/v3.2#example-object
+ */
+export type ExampleObject = {
+    /**
+     * Short description for the example
+     */
+    summary?: string;
+    /**
+     * Long description for the example
+     */
+    description?: string;
+    /**
+     * Embedded literal example
+     */
+    dataValue?: unknown;
+    /**
+     * A string representation of the example
+     */
+    serializedValue?: string;
+    /**
+     * The example value
+     */
+    value?: unknown;
+    /**
+     * A URL that points to the literal example
+     */
+    externalValue?: string;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Headers
+// ===============
+
+/**
+ * The Header Object follows the structure of the Parameter Object
+ * $comment: https://spec.openapis.org/oas/v3.2#header-object
+ */
+export type HeaderObject = {
+    /**
+     * A brief description of the header
+     */
+    description?: string;
+    /**
+     * Determines whether this header is mandatory
+     */
+    required?: boolean;
+    /**
+     * Specifies that a header is deprecated
+     */
+    deprecated?: boolean;
+    /**
+     * The schema defining the type used for the header
+     */
+    schema?: SchemaObject;
+    /**
+     * A map containing the representations for the header
+     */
+    content?: ContentObject;
+    /**
+     * The style of the header (always "simple" for headers)         */
+    style?: "simple";
+    /**
+     * When this is true, parameter values of type array or object generate separate parameters
+     */
+    explode?: boolean;
+    /**
+     * Determines whether header value should be percent-encoded
+     */
+    allowReserved?: boolean;
+    /**
+     * Example of the header's potential value
+     */
+    example?: unknown;
+    /**
+     * Examples of the header's potential value
+     */
+    examples?: Record<string, ExampleOrReferenceObject>;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Links
+// ===============
+
+/**
+ * The Link Object represents a possible design-time link for a response
+ * $comment: https://spec.openapis.org/oas/v3.2#link-object
+ */
+export type LinkObject = {
+    /**
+     * A relative or absolute reference to an OAS operation
+     */
+    operationRef?: string;
+    /**
+     * The name of an existing, resolvable OAS operation
+     */
+    operationId?: string;
+    /**
+     * A map representing parameters to pass to an operation
+     */
+    parameters?: MapOfString;
+    /**
+     * A literal value or runtime expression to use as a request body when calling the target operation
+     */
+    requestBody?: unknown;
+    /**
+     * A description of the link
+     */
+    description?: string;
+    /**
+     * A server object to be used by the target operation
+     */
+    server?: ServerObject;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Callbacks
+// ===============
+
+/**
+ * A map of possible out-of-band callbacks related to the parent operation
+ * $comment: https://spec.openapis.org/oas/v3.2#callback-object
+ */
+export type CallbacksObject = {
+    /**
+     * A path item object that contains the operation to call
+     */
+    [callbackName: string]: PathItemObject;
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Security
+// ===============
+
+/**
+ * A list of security requirement objects that specify which security schemes can be used
+ * $comment: https://spec.openapis.org/oas/v3.2#security-requirement-object
+ */
+export interface SecurityRequirementObject {
+    /**
+     * Each name must correspond to a security scheme declared in the Security Schemes under the Components Object
+     */
+    [securitySchemeName: string]: string[];
+}
+
+/**
+ * Defines a security scheme that can be used by the operations
+ * $comment: https://spec.openapis.org/oas/v3.2#security-scheme-object
+ */
+export type SecuritySchemeObject = {
+    /**
+     * The type of the security scheme
+     */
+    type: "apiKey" | "http" | "mutualTLS" | "oauth2" | "openIdConnect";
+    /**
+     * A description for security scheme
+     */
+    description?: string;
+    /**
+     * Declares this security scheme to be deprecated
+     */
+    deprecated?: boolean;
+    /**
+     * The name of the header or query parameter to be used (apiKey type)
+     */
+    name?: string;
+    /**
+     * The location of the API key (apiKey type)
+     */
+    in?: "query" | "header" | "cookie";
+    /**
+     * The name of the HTTP Authorization scheme (http type)
+     */
+    scheme?: string;
+    /**
+     * A hint to the client to identify how the bearer token is formatted (http bearer type)
+     */
+    bearerFormat?: string;
+    /**
+     * An object containing configuration information for the flow types supported (oauth2 type)
+     */
+    flows?: OAuthFlowsObject;
+    /**
+     * A URL to discover OAuth2 Authorization Server (oauth2 type)
+     */
+    oauth2MetadataUrl?: string;
+    /**
+     * OpenID Connect URL to discover OAuth2 Authorization Server (openIdConnect type)
+     */
+    openIdConnectUrl?: string;
+} & SpecificationExtensions;
+
+/**
+ * Configuration details for a supported OAuth Flow
+ */
+export type OAuthFlowsObject = {
+    /**
+     * Configuration for the OAuth Implicit flow
+     */
+    implicit?: {
+        /** The authorization URL for the implicit flow */
+        authorizationUrl: string;
+        /** The URL to refresh token */
+        refreshUrl?: string;
+        /**
+         * The available scopes for the OAuth2 security scheme
+         */
+        scopes: MapOfString;
+    };
+    /**
+     * Configuration for the OAuth Resource Owner Password flow
+     */
+    password?: {
+        /** The token URL for the password flow */
+        tokenUrl: string;
+        /** The URL to refresh token */
+        refreshUrl?: string;
+        /**
+         * The available scopes for the OAuth2 security scheme
+         */
+        scopes: MapOfString;
+    };
+    /**
+     * Configuration for the OAuth Client Credentials flow
+     */
+    clientCredentials?: {
+        /** The token URL for the client credentials flow */
+        tokenUrl: string;
+        /** The URL to refresh token */
+        refreshUrl?: string;
+        /**
+         * The available scopes for the OAuth2 security scheme
+         */
+        scopes: MapOfString;
+    };
+    /**
+     * Configuration for the OAuth Authorization Code flow
+     */
+    authorizationCode?: {
+        /** The authorization URL for the authorization code flow */
+        authorizationUrl: string;
+        /** The token URL for the authorization code flow */
+        tokenUrl: string;
+        /** The URL to refresh token */
+        refreshUrl?: string;
+        /**
+         * The available scopes for the OAuth2 security scheme
+         */
+        scopes: MapOfString;
+    };
+    /**
+     * Configuration for the OAuth Device Authorization flow
+     */
+    deviceAuthorization?: {
+        /** The device authorization URL for the device authorization flow */
+        deviceAuthorizationUrl: string;
+        /** The token URL for the device authorization flow */
+        tokenUrl: string;
+        /** The URL to refresh token */
+        refreshUrl?: string;
+        /**
+         * The available scopes for the OAuth2 security scheme
+         */
+        scopes: MapOfString;
+    };
+} & SpecificationExtensions;
+
+// ===============
+// MARK: Tags and ExternalDocumentation
+// ===============
+
+/**
+ * Adds metadata to a single tag that is used by the Operation Object
+ * $comment: https://spec.openapis.org/oas/v3.2#tag-object
+ */
+export type TagObject = {
+    /**
+     * The name of the tag
+     */
+    name: string;
+    /**
+     * A short description for the tag
+     */
+    summary?: string;
+    /**
+     * A description for the tag
+     */
+    description?: string;
+    /**
+     * Additional external documentation for this tag
+     */
+    externalDocs?: ExternalDocumentationObject;
+    /**
+     * The parent tag for hierarchical tags
+     */
+    parent?: string;
+    /**
+     * The kind of tag
+     */
+    kind?: string;
+} & SpecificationExtensions;
+
+/**
+ * Allows referencing an external resource for extended documentation
+ * $comment: https://spec.openapis.org/oas/v3.2#external-documentation-object
+ */
+export type ExternalDocumentationObject = {
+    /**
+     * A short description of the target documentation
+     */
+    description?: string;
+    /**
+     * The URL for the target documentation
+     */
+    url: string;
+} & SpecificationExtensions;
+
+// ===============
+// MARK:  Reference Union Types
+// ===============
+
+/**
+ * Defines an object that is either a full ExampleObject or a Reference Object.
+ */
+export type ExampleOrReferenceObject = ExampleObject | ReferenceObject;
+
+/**
+ * Defines an object that is either a full Parameter Object or a Reference Object.
+ */
+export type ParameterOrReferenceObject = ParameterObject | ReferenceObject;
+
+/**
+ * A request body or a reference to a request body
+ */
+export type RequestBodyOrReferenceObject = RequestBodyObject | ReferenceObject;
+
+/**
+ * Defines an object that is either a full Response Object or a Reference Object.
+ */
+export type ResponseOrReferenceObject = ResponseObject | ReferenceObject;
+
+/**
+ * Defines an object that is either a full Header Object or a Reference Object.
+ */
+export type HeaderOrReferenceObject = HeaderObject | ReferenceObject;
+
+/**
+ * A link or a reference to a link
+ */
+export type LinkOrReferenceObject = LinkObject | ReferenceObject;
+
+/**
+ * A media type or a reference to a media type
+ */
+export type MediaTypeOrReferenceObject = MediaTypeObject | ReferenceObject;
+
+/**
+ * A type that can be either the direct type or a reference
+ */
+export type PossiblyReferenced<T> = T | ReferenceObject;
+
+/**
+ * A security scheme or a reference to a security scheme
+ */
+export type SecuritySchemeOrReferenceObject =
+    | SecuritySchemeObject
+    | ReferenceObject;
+
+/**
+ * A callback or a reference to a callback
+ */
+export type CallbacksOrReferenceObject = CallbacksObject | ReferenceObject;
+
+// ===============
+// MARK: OpenAPIDocument
+// ===============
+
+/**
+ * The root document object for the OpenAPI Specification
+ * Contains all the information about the API
+ */
+export type OpenAPIDocumentProperties = {
+    /**
+     * The OpenAPI version string
+     * Must be in format "3.2.x" or "3.2.x-..."
+     */
+    openapi: string;
+    /**
+     * A self-reference to the document
+     * MUST NOT contain a fragment
+     */
+    $self?: string;
+    /**
+     * Provides metadata about the API
+     */
+    info: InfoObject;
+    /**
+     * The default JSON Schema dialect for operations
+     * @default https://spec.openapis.org/oas/3.2/dialect/2025-09-17
+     */
+    jsonSchemaDialect?: string;
+    /**
+     * An array of Server Objects
+     * Provides connectivity information to a target server
+     */
+    servers?: ServerObject[];
+    /**
+     * The available paths and operations for the API
+     */
+    paths?: PathsObject;
+    /**
+     * A map of possible out-of-band callbacks
+     * Key is the name of the callback
+     */
+    webhooks?: Record<string, PathItemObject>;
+    /**
+     * An element to hold various reusable objects
+     * Can include schemas, parameters, responses, etc.
+     */
+    components?: ComponentsObject;
+    /**
+     * A declaration of which security mechanisms can be used
+     */
+    security?: SecurityRequirementObject[];
+    /**
+     * A list of tags used by the specification
+     * Can be used for grouping operations
+     */
+    tags?: TagObject[];
+    /**
+     * Additional external documentation
+     */
+    externalDocs?: ExternalDocumentationObject;
+} & SpecificationExtensions;
+
+/**
+ * OpenAPI document that includes paths
+ * One of the required combinations for a valid OpenAPI document
+ */
+export type OpenAPIDocumentWithPaths = SchemaObject &
+    OpenAPIDocumentProperties & {
+        paths: PathsObject;
+    };
+
+/**
+ * OpenAPI document that includes components
+ * One of the required combinations for a valid OpenAPI document
+ */
+export type OpenAPIDocumentWithComponents = SchemaObject &
+    OpenAPIDocumentProperties & {
+        components: ComponentsObject;
+    };
+
+/**
+ * OpenAPI document that includes webhooks
+ * One of the required combinations for a valid OpenAPI document
+ */
+export type OpenAPIDocumentWithWebhooks = SchemaObject &
+    OpenAPIDocumentProperties & {
+        webhooks: Record<string, PathItemObject>;
+    };
+
+/**
+ * Complete OpenAPI document type
+ * Must include at least one of: paths, components, or webhooks
+ */
+export type OpenAPIDocument =
+    | OpenAPIDocumentWithPaths
+    | OpenAPIDocumentWithComponents
+    | OpenAPIDocumentWithWebhooks;