@api-client/core 0.19.18 → 0.19.20

package/src/modeling/generators/oas_312/types.ts

@@ -0,0 +1,1052 @@
+import { type JSONSchema } from 'json-schema-typed/draft-2020-12'
+
+/**
+ * This is the root object of the [OpenAPI Description](#openapi-description).
+ */
+export interface OpenApi312 {
+  /**
+   * This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI
+   * Document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI Document. This is _not_
+   * related to the [`info.version`](#info-version) string, which is the version of the OpenAPI Document.
+   */
+  openapi: '3.1.0' //'3.1.2'
+  /**
+   * Provides metadata about the API. The metadata MAY be used by tooling as required.
+   */
+  info: InfoObject
+  /**
+   * The default value for the `$schema` keyword within [Schema Objects](#schema-object) contained within this OAS
+   * document. This MUST be in the form of a URI.
+   */
+  jsonSchemaDialect?: string
+  /**
+   * An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is
+   * not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a
+   * [url](#server-url) value of `/`.
+   */
+  servers?: ServerObject[]
+  /**
+   * The available paths and operations for the API.
+   */
+  paths?: PathsObject
+  /**
+   * The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement.
+   * Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call,
+   * for example by an out of band registration. The key name is a unique string to refer to each webhook, while the
+   * (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the
+   * expected responses. An [example](https://learn.openapis.org/examples/v3.1/webhook-example.html) is available.
+   */
+  webhooks?: Record<string, PathItemObject>
+  /**
+   * An element to hold various Objects for the OpenAPI Description.
+   */
+  components?: ComponentsObject
+  /**
+   * A declaration of which security mechanisms can be used across the API. The list of values includes alternative
+   * Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to
+   * authorize a request. Individual operations can override this definition. The list can be incomplete, up to being
+   * empty or absent. To make security explicitly optional, an empty security requirement (`{}`) can be included in the
+   * array.
+   */
+  security?: SecurityRequirementObject[]
+  /**
+   * A list of tags used by the OpenAPI Description with additional metadata. The order of the tags can be used to
+   * reflect on their order by the parsing tools. Not all tags that are used by the [Operation
+   * Object](#operation-object) must be declared. The tags that are not declared MAY be organized randomly or based on
+   * the tools' logic. Each tag name in the list MUST be unique.
+   */
+  tags?: TagObject[]
+  /**
+   * Additional external documentation.
+   */
+  externalDocs?: ExternalDocumentationObject
+}
+
+/**
+ * The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented
+ * in editing or documentation generation tools for convenience.
+ */
+export interface InfoObject {
+  /**
+   * The title of the API.
+   */
+  title: string
+  /**
+   * A short summary of the API.
+   */
+  summary?: string
+  /**
+   * A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text
+   * representation.
+   */
+  description?: string
+  /**
+   * A URI for the Terms of Service for the API. This MUST be in the form of a URI.
+   */
+  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 (which is distinct from the [OpenAPI Specification
+   * version](#oas-version) or the version of the API being described or the version of the OpenAPI Description).
+   */
+  version: string
+}
+
+/**
+ * Contact information for the exposed API.
+ */
+export interface ContactObject {
+  /**
+   * The identifying name of the contact person/organization.
+   */
+  name?: string
+  /**
+   * The URI for the contact information. This MUST be in the form of a URI.
+   */
+  url?: string
+  /**
+   * The email address of the contact person/organization. This MUST be in the form of an email address.
+   */
+  email?: string
+}
+
+/**
+ * License information for the exposed API.
+ */
+export interface LicenseObject {
+  /**
+   * The license name used for the API.
+   */
+  name: string
+  /**
+   * An [SPDX](https://spdx.org/licenses/) license expression for the API. The `identifier` field is mutually exclusive
+   * of the `url` field.
+   */
+  identifier?: string
+  /**
+   * A URI for the license used for the API. This MUST be in the form of a URI. The `url` field is mutually exclusive of
+   * the `identifier` field.
+   */
+  url?: string
+}
+
+/**
+ * An object representing a Server.
+ */
+export interface ServerObject {
+  /**
+   * A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that
+   * the host location is relative to the location where the document containing the Server Object is being served.
+   * Query and fragment MUST NOT be part of this URL. Variable substitutions will be made when a variable is named in
+   * `{`braces`}`.
+   */
+  url: string
+  /**
+   * An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY
+   * be used for rich text representation.
+   */
+  description?: string
+  /**
+   * A map between a variable name and its value. The value is used for substitution in the server's URL template.
+   */
+  variables?: Record<string, ServerVariableObject>
+}
+
+/**
+ * An object representing a Server Variable for server URL template substitution.
+ */
+export interface ServerVariableObject {
+  /**
+   * An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT
+   * be empty.
+   */
+  enum?: string[]
+  /**
+   * The default value to use for substitution, which SHALL be sent if an alternate value is _not_
+   * supplied. If the [`enum`](#server-variable-enum) is defined, the value MUST exist in the enum's values. Note that
+   * this behavior is different from the [Schema Object](#schema-object)'s `default` keyword, which documents the
+   * receiver's behavior rather than inserting the value into the data.
+   */
+  default: string
+  /**
+   * An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for
+   * rich text representation.
+   */
+  description?: string
+}
+
+/**
+ * Holds a set of reusable objects for different aspects of the OAS. All objects defined within the Components Object
+ * will have no effect on the API unless they are explicitly referenced from outside the Components Object.
+ */
+export interface ComponentsObject {
+  /**
+   * An object to hold reusable [Schema Objects](#schema-object).
+   */
+  schemas?: Record<string, SchemaObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  responses?: Record<string, ResponseObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  parameters?: Record<string, ParameterObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  examples?: Record<string, ExampleObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  requestBodies?: Record<string, RequestBodyObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  headers?: Record<string, HeaderObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  securitySchemes?: Record<string, SecuritySchemeObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  links?: Record<string, LinkObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  callbacks?: Record<string, CallbackObject>
+  /**
+   * An object to hold reusable [Path Item Objects](#path-item-object).
+   */
+  pathItems?: Record<string, PathItemObject>
+}
+
+/**
+ * Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the
+ * [Server Object](#server-object) in order to construct the full URL. The Paths Object MAY be empty, due to [Access
+ * Control List (ACL) constraints](#security-filtering).
+ */
+export type PathsObject = Record<string, PathItemObject>
+
+/**
+ * Describes the operations available on a single path. A Path Item MAY be empty, due to [ACL
+ * constraints](#security-filtering). The path itself is still exposed to the documentation viewer but they will not
+ * know which operations and parameters are available.
+ */
+export interface PathItemObject {
+  /**
+   * Allows for a referenced definition of this path item. The value MUST be in the form of a URI, and the referenced
+   * structure MUST be in the form of a [Path Item Object](#path-item-object). In case a Path Item Object field appears
+   * both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving
+   * [Relative References](#relative-references-in-api-description-uris). _**Note:** The behavior of `$ref` with
+   * adjacent properties is likely to change in future versions of this specification to bring it into closer alignment
+   * with the behavior of the [Reference Object](#reference-object)._
+   */
+  $ref?: string
+  /**
+   * An optional string summary, intended to apply to all operations in this path.
+   */
+  summary?: string
+  /**
+   * An optional string description, intended to apply to all operations in this path. [CommonMark
+   * syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+   */
+  description?: string
+  /**
+   * 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 a 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
+  /**
+   * An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the
+   * [OpenAPI Object](#oas-servers) level, it will be overridden by this value.
+   */
+  servers?: ServerObject[]
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  parameters?: (ParameterObject | ReferenceObject)[]
+}
+
+/**
+ * Describes a single API operation on a path.
+ */
+export interface OperationObject {
+  /**
+   * A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or
+   * any other qualifier.
+   */
+  tags?: string[]
+  /**
+   * A short summary of what the operation does.
+   */
+  summary?: string
+  /**
+   * A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for
+   * rich text representation.
+   */
+  description?: string
+  /**
+   * Additional external documentation for this operation.
+   */
+  externalDocs?: ExternalDocumentationObject
+  /**
+   * Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The
+   * operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an
+   * operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
+   */
+  operationId?: string
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  parameters?: (ParameterObject | ReferenceObject)[]
+  /**
+   * [Reference Object](#reference-object)
+   */
+  requestBody?: RequestBodyObject | ReferenceObject
+  /**
+   * 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.
+   * The key is a unique identifier for the Callback Object.
+   * Each value in the map is a Callback Object that describes a request
+   * that may be initiated by the API provider and the expected responses.
+   */
+  callbacks?: Record<string, CallbackObject>
+  /**
+   * Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default
+   * value is `false`.
+   */
+  deprecated?: boolean
+  /**
+   * A declaration of which security mechanisms can be used for this operation. The list of values includes alternative
+   * Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to
+   * authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array.
+   * This definition overrides any declared top-level [`security`](#oas-security). To remove a top-level security
+   * declaration, an empty array can be used.
+   */
+  security?: SecurityRequirementObject[]
+  /**
+   * An alternative `servers` array to service this operation. If a `servers` array is specified at the [Path Item
+   * Object](#path-item-servers) or [OpenAPI Object](#oas-servers) level, it will be overridden by this value.
+   */
+  servers?: ServerObject[]
+}
+
+/**
+ * Allows referencing an external resource for extended documentation.
+ */
+export interface ExternalDocumentationObject {
+  /**
+   * A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich
+   * text representation.
+   */
+  description?: string
+  /**
+   * The URI for the target documentation. This MUST be in the form of a URI.
+   */
+  url: string
+}
+
+/**
+ * Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameter-name)
+ * and [location](#parameter-in). See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed
+ * examination of percent-encoding concerns, including interactions with the `application/x-www-form-urlencoded` query
+ * string format.
+ */
+export interface ParameterObject {
+  /**
+   * The name of the parameter. Parameter names are _case sensitive_. If [`in`](#parameter-in) is
+   * `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#paths-path) field
+   * in the [Paths Object](#paths-object). See [Path Templating](#path-templating) for further information.If
+   * [`in`](#parameter-in) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the
+   * parameter definition SHALL be ignored.For all other cases, the `name` corresponds to the parameter name used by the
+   * [`in`](#parameter-in) field.
+   */
+  name: string
+  /**
+   * The location of the parameter.
+   */
+  in: 'query' | 'header' | 'path' | 'cookie'
+  /**
+   * A brief description of the parameter. This could contain examples of use. [CommonMark
+   * syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+   */
+  description?: string
+  /**
+   * Determines whether this parameter is mandatory. If the [parameter location](#parameter-in) is `"path"`, this field
+   * is **REQUIRED** and its value MUST be `true`. Otherwise, the field MAY be included and its default value is
+   * `false`.
+   */
+  required: boolean
+  /**
+   * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
+   */
+  deprecated?: boolean
+  /**
+   * If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted
+   * entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If
+   * [`style`](#parameter-style) is used, and if [behavior is _n/a_ (cannot be serialized)](#style-examples), the value
+   * of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's [Schema
+   * Object](#schema-object) are implementation-defined. This field is valid only for `query` parameters. Use of this
+   * field is NOT RECOMMENDED, and it is likely to be removed in a later revision.
+   */
+  allowEmptyValue?: boolean
+  /**
+   * Describes how the parameter value will be serialized depending on the type of the parameter value. Default values
+   * (based on value of `in`): for `"query"` - `"form"`; for `"path"` - `"simple"`; for `"header"` - `"simple"`; for
+   * `"cookie"` - `"form"`.
+   */
+  style?: string
+  /**
+   * When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the
+   * array or key-value pair of the map. For other types of parameters this field has no effect. When
+   * [`style`](#parameter-style) is `"form"`, the default value is `true`. For all other styles, the default value is
+   * `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject`
+   * is undefined.
+   */
+  explode?: boolean
+  /**
+   * When this is true, parameter values are serialized using reserved expansion, as defined by
+   * [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character
+   * set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass
+   * through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of
+   * percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not
+   * allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a
+   * special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see [URL
+   * Percent-Encoding](#url-percent-encoding) for details. This field only applies to parameters with an `in` value of
+   * `query`. The default value is `false`.
+   */
+  allowReserved?: boolean
+  /**
+   * The schema defining the type used for the parameter.
+   */
+  schema?: SchemaObject
+  /**
+   * Example of the parameter's potential value; see [Working With Examples](#working-with-examples).
+   */
+  example?: unknown
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  examples?: Record<string, ExampleObject>
+  /**
+   * A map containing the representations for the parameter. The key is the media type and the value describes it. The
+   * map MUST only contain one entry.
+   */
+  content?: Record<string, MediaTypeObject>
+}
+
+/**
+ * Describes a single request body.
+ */
+export interface RequestBodyObject {
+  /**
+   * A brief description of the request body. This could contain examples of use. [CommonMark
+   * syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+   */
+  description?: string
+  /**
+   * The content of the request body. The key is a media type or [media type
+   * range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. The map SHOULD have at least one
+   * entry; if it does not, the behavior is implementation-defined. For requests that match multiple keys, only the most
+   * specific key is applicable. e.g. `"text/plain"` overrides `"text/*"`
+   */
+  content: Record<string, MediaTypeObject>
+  /**
+   * Determines if the request body is required in the request. Defaults to `false`.
+   */
+  required?: boolean
+}
+
+/**
+ * Each Media Type Object provides schema and examples for the media type identified by its key. When `example` or
+ * `examples` are provided, the example SHOULD match the specified schema and be in the correct format as specified by
+ * the media type and its encoding. The `example` and `examples` fields are mutually exclusive, and if either is present
+ * it SHALL _override_ any `example` in the schema. See [Working With Examples](#working-with-examples) for further
+ * guidance regarding the different ways of specifying examples, including non-JSON/YAML values.
+ */
+export interface MediaTypeObject {
+  /**
+   * The schema defining the content of the request, response, parameter, or header.
+   */
+  schema?: SchemaObject
+  /**
+   * Example of the media type; see [Working With Examples](#working-with-examples).
+   */
+  example?: unknown
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  examples?: Record<string, ExampleObject>
+  /**
+   * A map between a property name and its encoding information. The key, being the property name, MUST exist in the
+   * schema as a property. The `encoding` field SHALL only apply to [Request Body Objects](#request-body-object), and
+   * only when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided
+   * for a property, the behavior is determined by the default values documented for the Encoding Object.
+   */
+  encoding?: Record<string, EncodingObject>
+}
+
+/**
+ * A single encoding definition applied to a single schema property. See [Appendix B](#appendix-b-data-type-conversion)
+ * for a discussion of converting values of various types to string representations. Properties are correlated with
+ * `multipart` parts using the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of
+ * `Content-Disposition: form-data`, and with `application/x-www-form-urlencoded` using the query string parameter
+ * names. In both cases, their order is implementation-defined. See [Appendix
+ * E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for
+ * form media types.
+ */
+export interface EncodingObject {
+  /**
+   * The `Content-Type` for encoding a specific property. The value is a comma-separated list, each element of which is
+   * either a specific media type (e.g. `image/png`) or a wildcard media type (e.g. `image/*`). Default value depends on
+   * the property type as shown in the table below.
+   */
+  contentType?: string
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  headers?: Record<string, HeaderObject>
+  /**
+   * Describes how a specific property value will be serialized depending on its type. See [Parameter
+   * Object](#parameter-object) for details on the [`style`](#parameter-style) field. The behavior follows the same
+   * values as `query` parameters, including the default value of `"form"` which applies only when `contentType` is
+   * _not_ being used due to one or both of `explode` or `allowReserved` being explicitly specified. Note that the
+   * initial `?` used in query strings is not used in `application/x-www-form-urlencoded` message bodies, and MUST be
+   * removed (if using an RFC6570 implementation) or simply not added (if constructing the string manually). This field
+   * SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or
+   * `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type)
+   * (implicit or explicit) SHALL be ignored.
+   */
+  style?: string
+  /**
+   * When this is true, property values of type `array` or `object` generate separate parameters for each value of the
+   * array, or key-value-pair of the map. For other types of properties this field has no effect. When
+   * [`style`](#encoding-style) is `"form"`, the default value is `true`. For all other styles, the default value is
+   * `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject`
+   * is undefined. This field SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`
+   * or `multipart/form-data`. If a value is explicitly defined, then the value of
+   * [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored.
+   */
+  explode?: boolean
+  /**
+   * When this is true, parameter values are serialized using reserved expansion, as defined by
+   * [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character
+   * set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass
+   * through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of
+   * percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not
+   * allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a
+   * special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see [URL
+   * Percent-Encoding](#url-percent-encoding) for details. The default value is `false`. This field SHALL be ignored if
+   * the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is
+   * explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be
+   * ignored.
+   */
+  allowReserved?: boolean
+}
+
+/**
+ * A container for the expected responses of an operation. The container maps a HTTP response code to the expected
+ * response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may
+ * not be known in advance. However, documentation is expected to cover a successful operation response and any known
+ * errors. The `default` MAY be used as a default Response Object for all HTTP codes that are not covered individually
+ * by the Responses Object. The Responses Object MUST contain at least one response code, and if only one response code
+ * is provided it SHOULD be the response for a successful operation call.
+ */
+export interface ResponsesObject {
+  /**
+   * [Reference Object](#reference-object)
+   */
+  default?: ResponseObject | ReferenceObject
+  /**
+   * Pattern: [HTTP Status Code](#http-status-codes) [Reference Object](#reference-object)
+   */
+  [pattern: string]: ResponseObject | ReferenceObject | undefined
+}
+
+/**
+ * Describes a single response from an API operation, including design-time, static `links` to operations based on the
+ * response.
+ */
+export interface ResponseObject {
+  /**
+   * A description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich
+   * text representation.
+   */
+  description: string
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  headers?: Record<string, HeaderObject>
+  /**
+   * A map containing descriptions of potential response payloads. The key is a media type or [media type
+   * range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match
+   * multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"`
+   */
+  content?: Record<string, MediaTypeObject>
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  links?: Record<string, LinkObject>
+}
+
+/**
+ * A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item
+ * Object](#path-item-object) that describes a set of requests that may be initiated by the API provider and the
+ * expected responses. The key value used to identify the Path Item Object is an expression, evaluated at runtime, that
+ * identifies a URL to use for the callback operation. To describe incoming requests from the API provider independent
+ * from another API call, use the [`webhooks`](#oas-webhooks) field.
+ */
+export type CallbackObject = Record<string, PathItemObject>
+
+/**
+ * An object grouping an internal or external example value with basic `summary` and `description` metadata. This object
+ * is typically used in fields named `examples` (plural), and is a [referenceable](#reference-object) alternative to
+ * older `example` (singular) fields that do not support referencing or metadata. Examples allow demonstration of the
+ * usage of properties, parameters and objects within OpenAPI.
+ */
+export interface ExampleObject {
+  /**
+   * Short description for the example.
+   */
+  summary?: string
+  /**
+   * Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text
+   * representation.
+   */
+  description?: string
+  /**
+   * Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples
+   * of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example,
+   * escaping where necessary.
+   */
+  value?: unknown
+  /**
+   * A URI that identifies the literal example. This provides the capability to reference examples that cannot easily be
+   * included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. See the
+   * rules for resolving [Relative References](#relative-references-in-api-description-uris).
+   */
+  externalValue?: string
+}
+
+/**
+ * The Link Object represents a possible design-time link for a response. The presence of a link does not guarantee the
+ * caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between
+ * responses and other operations. Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS
+ * linking mechanism does not require link information in the runtime response. For computing links and providing
+ * instructions to execute them, a [runtime expression](#runtime-expressions) is used for accessing values in an
+ * operation and using them as parameters while invoking the linked operation.
+ */
+export interface LinkObject {
+  /**
+   * A URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to
+   * an [Operation Object](#operation-object). Relative `operationRef` values MAY be used to locate an existing
+   * [Operation Object](#operation-object) in the OpenAPI Description.
+   */
+  operationRef?: string
+  /**
+   * The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually
+   * exclusive of the `operationRef` field.
+   */
+  operationId?: string
+  /**
+   * [{expression}](#runtime-expressions)]
+   */
+  parameters?: Record<string, unknown>
+  /**
+   * [{expression}](#runtime-expressions)
+   */
+  requestBody?: unknown
+  /**
+   * A description of the link. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text
+   * representation.
+   */
+  description?: string
+  /**
+   * A server object to be used by the target operation.
+   */
+  server?: ServerObject
+}
+
+/**
+ * Describes a single header for [HTTP responses](#response-headers) and for [individual parts in `multipart`
+ * representations](#encoding-headers); see the relevant [Response Object](#response-object) and [Encoding
+ * Object](#encoding-object) documentation for restrictions on which headers can be described. The Header Object follows
+ * the structure of the [Parameter Object](#parameter-object), including determining its serialization strategy based on
+ * whether `schema` or `content` is present, with the following changes:
+ *
+ * 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.
+ * 2. `in` MUST NOT be specified, it is implicitly in `header`.
+ * 3. All traits that are affected by the location MUST be applicable to a location of `header` (for example,
+ *    [`style`](#parameter-style)). This means that `allowEmptyValue` and `allowReserved` MUST NOT be used, and `style`,
+ *    if used, MUST be limited to `"simple"`.
+ * 4. `name` MUST NOT be specified, it is given in the corresponding `headers` map.
+ * 5. `in` MUST NOT be specified, it is implicitly in `header`.
+ * 6. All traits that are affected by the location MUST be applicable to a location of `header` (for example,
+ *    [`style`](#parameter-style)). This means that `allowEmptyValue` and `allowReserved` MUST NOT be used, and `style`,
+ *    if used, MUST be limited to `"simple"`.
+ */
+export interface HeaderObject {
+  /**
+   * A brief description of the header. This could contain examples of use. [CommonMark
+   * syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+   */
+  description?: string
+  /**
+   * Determines whether this header is mandatory. The default value is `false`.
+   */
+  required?: boolean
+  /**
+   * Specifies that the header is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
+   */
+  deprecated?: boolean
+  /**
+   * Describes how the header value will be serialized. The default (and only legal value for headers) is `"simple"`.
+   */
+  style?: 'simple'
+  /**
+   * When this is true, header values of type `array` or `object` generate a single header whose value is a
+   * comma-separated list of the array items or key-value pairs of the map, see [Style Examples](#style-examples). For
+   * other data types this field has no effect. The default value is `false`.
+   */
+  explode?: boolean
+  /**
+   * The schema defining the type used for the header.
+   */
+  schema?: SchemaObject
+  /**
+   * Example of the header's potential value; see [Working With Examples](#working-with-examples).
+   */
+  example?: unknown
+  /**
+   * [Reference Object](#reference-object)]
+   */
+  examples?: Record<string, ExampleObject>
+  /**
+   * A map containing the representations for the header. The key is the media type and the value describes it. The map
+   * MUST only contain one entry.
+   */
+  content?: Record<string, MediaTypeObject>
+}
+
+/**
+ * Adds metadata to a single tag that is used by the [Operation Object](#operation-object). It is not mandatory to have
+ * a Tag Object per tag defined in the Operation Object instances.
+ */
+export interface TagObject {
+  /**
+   * The name of the tag.
+   */
+  name: string
+  /**
+   * A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text
+   * representation.
+   */
+  description?: string
+  /**
+   * Additional external documentation for this tag.
+   */
+  externalDocs?: ExternalDocumentationObject
+}
+
+/**
+ * A simple object to allow referencing other components in the OpenAPI Description, internally and externally. The
+ * `$ref` string value contains a URI [RFC3986](https://tools.ietf.org/html/rfc3986), which identifies the value being
+ * referenced. See the rules for resolving [Relative References](#relative-references-in-api-description-uris).
+ */
+export interface ReferenceObject {
+  /**
+   * The reference identifier. This MUST be in the form of a URI.
+   */
+  $ref: string
+  /**
+   * A short summary which by default SHOULD override that of the referenced component. If the referenced object-type
+   * does not allow a `summary` field, then this field has no effect.
+   */
+  summary?: string
+  /**
+   * A description which by default SHOULD override that of the referenced component. [CommonMark
+   * syntax](https://spec.commonmark.org/) MAY be used for rich text representation. If the referenced object-type does
+   * not allow a `description` field, then this field has no effect.
+   */
+  description?: string
+}
+
+/**
+ * The Schema Object allows the definition of input and output data types. These types can be objects, but also
+ * primitives and arrays. This object is a superset of the [JSON Schema Specification Draft
+ * 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00). The empty schema (which allows any instance to
+ * validate) MAY be represented by the boolean value `true` and a schema which allows no instance to validate MAY be
+ * represented by the boolean value `false`. For more information about the keywords, see [JSON Schema
+ * Core](https://tools.ietf.org/html/draft-bhutton-json-schema-00) and [JSON Schema
+ * Validation](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00). Unless stated otherwise, the
+ * keyword definitions follow those of JSON Schema and do not add any additional semantics; this includes keywords such
+ * as `$schema`, `$id`, `$ref`, and `$dynamicRef` being URIs rather than URLs. Where JSON Schema indicates that behavior
+ * is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application
+ * consuming the OpenAPI document.
+ */
+export type SchemaObject = JSONSchema & {
+  /**
+   * Adds support for polymorphism. The discriminator is used to determine which of a set of schemas a payload is
+   * expected to satisfy. See [Composition and Inheritance](#composition-and-inheritance-polymorphism) for more
+   * details.
+   */
+  discriminator?: DiscriminatorObject
+  /**
+   * This MAY be used only on property schemas. It has no effect on root schemas. Adds additional metadata to describe
+   * the XML representation of this property.
+   */
+  xml?: XMLObject
+  /**
+   * Additional external documentation for this schema.
+   */
+  externalDocs?: ExternalDocumentationObject
+  /**
+   * A free-form field to include an example of an instance for this schema. To represent examples that cannot be
+   * naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where
+   * necessary. **Deprecated:** The `example` field has been deprecated in favor of the JSON Schema `examples` keyword.
+   * Use of `example` is discouraged, and later versions of this specification may remove it.
+   */
+  example?: unknown
+}
+
+/**
+ * When request bodies or response payloads may be one of a number of different schemas, a Discriminator Object gives a
+ * hint about the expected schema of the document. This hint can be used to aid in serialization, deserialization, and
+ * validation. The Discriminator Object does this by implicitly or explicitly associating the possible values of a named
+ * property with alternative schemas. Note that `discriminator` MUST NOT change the validation outcome of the schema.
+ */
+export interface DiscriminatorObject {
+  /**
+   * The name of the property in the payload that will hold the discriminating value. This property SHOULD
+   * be required in the payload schema, as the behavior when the property is absent is undefined.
+   */
+  propertyName: string
+  /**
+   * An object to hold mappings between payload values and schema names or URI references.
+   */
+  mapping?: Record<string, string>
+}
+
+/**
+ * A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are
+ * _not_ inferred (for singular/plural forms) and the `name` field SHOULD be used to add that information. See examples
+ * for expected behavior.
+ */
+export interface XMLObject {
+  /**
+   * Replaces the inferred name of the element/attribute used for the described schema property. For the root schema
+   * object of a [schema component](#components-schemas), the inferred name is the name of the component; for other
+   * schemas the name is inferred from the parent property name. When defined within `items`, it will affect the name of
+   * the individual XML elements within the list. When defined alongside `type` being `"array"` (outside the `items`),
+   * it will affect the wrapping element if and only if `wrapped` is `true`. If `wrapped` is `false`, it will be
+   * ignored.
+   */
+  name?: string
+  /**
+   * The URI of the namespace definition. Value MUST be in the form of a non-relative URI.
+   */
+  namespace?: string
+  /**
+   * The prefix to be used for the [name](#xml-name).
+   */
+  prefix?: string
+  /**
+   * Declares whether the property definition translates to an attribute instead of an element. Default value is
+   * `false`.
+   */
+  attribute?: boolean
+  /**
+   * MAY be used only for an array definition. Signifies whether the array is wrapped (for example, `) or unwrapped (`).
+   * Default value is `false`. The definition takes effect only when defined alongside `type` being `"array"` (outside
+   * the `items`).
+   */
+  wrapped?: boolean
+}
+
+/**
+ * Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key
+ * (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's
+ * common flows (implicit, password, client credentials and authorization code) as defined in
+ * [RFC6749](https://tools.ietf.org/html/rfc6749), and [[OpenID-Connect-Core]]. Please note that as of 2020, the
+ * implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current
+ * Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use cases is
+ * Authorization Code Grant flow with PKCE.
+ */
+
+/**
+ * Allows configuration of the supported OAuth Flows.
+ */
+export interface OAuthFlowsObject {
+  /**
+   * Configuration for the OAuth Implicit flow
+   */
+  implicit?: ImplicitOAuthFlowObject
+  /**
+   * Configuration for the OAuth Resource Owner Password flow
+   */
+  password?: PasswordOAuthFlowObject
+  /**
+   * Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0.
+   */
+  clientCredentials?: ClientCredentialsOAuthFlowObject
+  /**
+   * Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0.
+   */
+  authorizationCode?: AuthorizationCodeOAuthFlowObject
+}
+
+/**
+ * Configuration details for a supported OAuth Flow
+ */
+export interface OAuthFlowObject {
+  /**
+   * The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the
+   * use of TLS. Applies To:
+   *
+   * - Implicit
+   * - AuthorizationCode
+   */
+  authorizationUrl?: string
+  /**
+   * The device authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard
+   * requires the use of TLS. Applies To:
+   *
+   * - Password
+   * - ClientCredentials
+   * - AuthorizationCode
+   */
+  tokenUrl?: string
+  /**
+   * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires
+   * the use of TLS.
+   */
+  refreshUrl?: string
+  /**
+   * The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.
+   * The map MAY be empty.
+   */
+  scopes: Record<string, string>
+}
+
+export interface ImplicitOAuthFlowObject extends OAuthFlowObject {
+  authorizationUrl: string
+}
+
+export interface AuthorizationCodeOAuthFlowObject extends OAuthFlowObject {
+  authorizationUrl: string
+  tokenUrl: string
+}
+
+export interface PasswordOAuthFlowObject extends OAuthFlowObject {
+  tokenUrl: string
+}
+
+export interface ClientCredentialsOAuthFlowObject extends OAuthFlowObject {
+  tokenUrl: string
+}
+
+/**
+ * Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a
+ * security scheme declared in the [Security Schemes](#components-security-schemes) under the [Components
+ * Object](#components-object). A Security Requirement Object MAY refer to multiple security schemes in which case all
+ * schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query
+ * parameters or HTTP headers are required to convey security information. When the `security` field is defined on the
+ * [OpenAPI Object](#openapi-object) or [Operation Object](#operation-object) and contains multiple Security Requirement
+ * Objects, only one of the entries in the list needs to be satisfied to authorize the request. This enables support for
+ * scenarios where the API allows multiple, independent security schemes. An empty Security Requirement Object (`{}`)
+ * indicates anonymous access is supported.
+ */
+export type SecurityRequirementObject = Record<string, string[]>
+
+export type SecuritySchemeObject =
+  | HttpSecurityScheme
+  | ApiKeySecurityScheme
+  | OAuth2SecurityScheme
+  | OpenIdSecurityScheme
+
+interface SecuritySchemeBase {
+  description?: string
+  deprecated?: boolean
+}
+
+export interface HttpSecurityScheme extends SecuritySchemeBase {
+  type: 'http'
+  /**
+   * The name of the HTTP Authentication scheme to be used in the Authorization header as defined in [RFC9110] Section
+   * 16.4.1. The values used SHOULD be registered in the IANA Authentication Scheme registry. The value is
+   * case-insensitive, as defined in [RFC9110] Section 11.1.
+   */
+  scheme: 'Basic' | 'Bearer' | string
+  /**
+   * A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an
+   * authorization server, so this information is primarily for documentation purposes.
+   */
+  bearerFormat?: string
+}
+
+export interface ApiKeySecurityScheme extends SecuritySchemeBase {
+  type: 'apiKey'
+  /**
+   * The name of the header, query or cookie parameter to be used.
+   */
+  name: string
+  /**
+   * The location of the API key.
+   */
+  in: 'query' | 'header' | 'cookie'
+}
+
+export interface OAuth2SecurityScheme extends SecuritySchemeBase {
+  type: 'oauth2'
+  /**
+   * An object containing configuration information for the flow types supported.
+   */
+  flows: OAuthFlowsObject
+}
+
+export interface OpenIdSecurityScheme extends SecuritySchemeBase {
+  type: 'openIdConnect'
+  /**
+   * OpenID Connect Discovery URL as defined by [OpenID-Connect-Discovery-1.0].
+   */
+  openIdConnectUrl: string
+}