openapi-types/3.1/paths.ts

import type { Extension } from "./extensions";
import type { ExternalDocumentation } from "./externalDocs";
import type { Reference } from "./references";
import type { Schema } from "./schema";
import type { SecurityRequirement } from "./security";
import type { Server } from "./servers";
import type { ResponsesMap } from "./status";

/**
 * -----
 * Paths Object
 * -----
 *
 * Holds the relative paths to the individual endpoints and their operations.
 * The path is appended to the URL from the Server Object in order to construct
 * the full URL. The Paths may be empty, due to ACL constraints.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#paths-object | OpenAPI 3.1.1 Paths Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#paths-object | OpenAPI 3.1.0 Paths Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `/{path}` - A relative path to an individual endpoint
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The path keys must start with `/` and can contain path parameters in `{brackets}`.
 *
 * -----
 * Examples
 * -----
 *
 * @example (simple paths):
 * ```ts
 * const paths: Paths = {
 *   "/pets": {
 *     "get": {
 *       "summary": "List all pets",
 *       "responses": {
 *         "200": {
 *           "description": "A list of pets"
 *         }
 *       }
 *     }
 *   }
 * };
 * ```
 */
export type Paths = Record<string, PathItem | Reference>;

/**
 * -----
 * Path Item Object
 * -----
 *
 * Describes the operations available on a single path. A Path Item MAY be empty,
 * due to ACL constraints. The path itself is still exposed to the documentation
 * viewer but they will not know which operations and parameters are available.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#path-item-object | OpenAPI 3.1.1 Path Item Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#path-item-object | OpenAPI 3.1.0 Path Item Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `summary` - Optional An optional, string summary, intended to apply to all operations in this path
 * @property `description` - Optional An optional, string description, intended to apply to all operations in this path
 * @property `get` - Optional A definition of a GET operation on this path
 * @property `put` - Optional A definition of a PUT operation on this path
 * @property `post` - Optional A definition of a POST operation on this path
 * @property `delete` - Optional A definition of a DELETE operation on this path
 * @property `options` - Optional A definition of an OPTIONS operation on this path
 * @property `head` - Optional A definition of a HEAD operation on this path
 * @property `patch` - Optional A definition of a PATCH operation on this path
 * @property `trace` - Optional A definition of a TRACE operation on this path
 * @property `servers` - Optional An alternative server array to service all operations in this path
 * @property `parameters` - Optional A list of parameters that are applicable for all the operations described under this path
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * All fields are optional. The HTTP methods are mutually exclusive.
 *
 * -----
 * Examples
 * -----
 *
 * @example (simple path item):
 * ```ts
 * const pathItem: PathItem = {
 *   "get": {
 *     "summary": "List all pets",
 *     "responses": {
 *       "200": {
 *         "description": "A list of pets"
 *       }
 *     }
 *   }
 * };
 * ```
 */
export interface PathItem extends Extension {
	/**
	 * An optional, string summary, intended to apply to all operations in this path.
	 *
	 * @example "Pet operations"
	 * @example "User management"
	 */
	summary?: string;

	/**
	 * An optional, string description, intended to apply to all operations in this path.
	 * CommonMark syntax MAY be used for rich text representation.
	 *
	 * @example "Operations related to pet management"
	 * @example "All user-related operations"
	 */
	description?: string;

	/**
	 * A definition of a GET operation on this path.
	 */
	get?: Operation;

	/**
	 * A definition of a PUT operation on this path.
	 */
	put?: Operation;

	/**
	 * A definition of a POST operation on this path.
	 */
	post?: Operation;

	/**
	 * A definition of a DELETE operation on this path.
	 */
	delete?: Operation;

	/**
	 * A definition of an OPTIONS operation on this path.
	 */
	options?: Operation;

	/**
	 * A definition of a HEAD operation on this path.
	 */
	head?: Operation;

	/**
	 * A definition of a PATCH operation on this path.
	 */
	patch?: Operation;

	/**
	 * A definition of a TRACE operation on this path.
	 */
	trace?: Operation;

	/**
	 * An alternative server array to service all operations in this path.
	 *
	 * @example [{ url: "https://api.example.com/v1" }]
	 */
	servers?: Server[];

	/**
	 * A list of parameters that are applicable for all the operations described under
	 * this path. These parameters can be overridden at the operation level, but cannot
	 * be removed there. The list MUST NOT include duplicated parameters. A unique
	 * parameter is defined by a combination of a name and location.
	 *
	 * @example [{ name: "id", in: "path", required: true, schema: { type: "string" } }]
	 */
	parameters?: (Parameter | Reference)[];
}

/**
 * -----
 * Operation Object
 * -----
 *
 * Describes a single API operation on a path.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#operation-object | OpenAPI 3.1.1 Operation Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#operation-object | OpenAPI 3.1.0 Operation Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `tags` - Optional A list of tags for API documentation control
 * @property `summary` - Optional A short summary of what the operation does
 * @property `description` - Optional A verbose explanation of the operation behavior
 * @property `externalDocs` - Optional Additional external documentation for this operation
 * @property `operationId` - Optional Unique string used to identify the operation
 * @property `parameters` - Optional A list of parameters that are applicable for this operation
 * @property `requestBody` - Optional The request body applicable for this operation
 * @property `responses` - Required The list of possible responses as they are returned from executing this operation
 * @property `callbacks` - Optional A map of possible out-of band callbacks related to the parent operation
 * @property `deprecated` - Optional Declares this operation to be deprecated
 * @property `security` - Optional A declaration of which security mechanisms can be used for this operation
 * @property `servers` - Optional An alternative server array to service this operation
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `responses` field is required.
 *
 * -----
 * Examples
 * -----
 *
 * @example (simple operation):
 * ```ts
 * const operation: Operation = {
 *   "summary": "List all pets",
 *   "responses": {
 *     "200": {
 *       "description": "A list of pets"
 *     }
 *   }
 * };
 * ```
 */
export interface Operation extends Extension {
	/**
	 * A list of tags for API documentation control. Tags can be used for logical
	 * grouping of operations by resources or any other qualifier.
	 *
	 * @example ["pets", "list"]
	 * @example ["users", "authentication"]
	 */
	tags?: string[];

	/**
	 * A short summary of what the operation does.
	 *
	 * @example "List all pets"
	 * @example "Create a new user"
	 */
	summary?: string;

	/**
	 * A verbose explanation of the operation behavior. CommonMark syntax MAY be used
	 * for rich text representation.
	 *
	 * @example "Returns all pets from the system that the user has access to"
	 * @example "Creates a new user account with the provided information"
	 */
	description?: string;

	/**
	 * Additional external documentation for this operation.
	 *
	 * @example { description: "Find out more about pet operations", url: "https://example.com/docs/pets" }
	 */
	externalDocs?: ExternalDocumentation;

	/**
	 * 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.
	 *
	 * @example "listPets"
	 * @example "createUser"
	 */
	operationId?: string;

	/**
	 * A list of parameters that are applicable for this operation. If a parameter
	 * is already defined at the Path Item, the new definition will override it but
	 * can never remove it. The list MUST NOT include duplicated parameters.
	 *
	 * @example [{ name: "limit", in: "query", schema: { type: "integer" } }]
	 */
	parameters?: (Parameter | Reference)[];

	/**
	 * The request body applicable for this operation. The requestBody is only supported
	 * in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined
	 * semantics for request bodies.
	 *
	 * @example { description: "Pet to add to the store", content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } } }
	 */
	requestBody?: RequestBody | Reference;

	/**
	 * The list of possible responses as they are returned from executing this operation.
	 * This field is required.
	 *
	 * @example { "200": { description: "A list of pets" }, "default": { description: "Unexpected error" } }
	 */
	responses: ResponsesMap;

	/**
	 * 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.
	 *
	 * @example { "myCallback": { "{$request.body#/callbackUrl}": { post: { requestBody: { description: "Callback payload" } } } } }
	 */
	callbacks?: Record<string, Callback | Reference>;

	/**
	 * Declares this operation to be deprecated. Consumers SHOULD refrain from using
	 * the declared operation. Default value is false.
	 *
	 * @example true
	 * @example false
	 * @default 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.
	 *
	 * @example [{ "petstore_auth": ["write:pets", "read:pets"] }]
	 */
	security?: SecurityRequirement[];

	/**
	 * An alternative server array to service this operation. If an alternative
	 * server object is specified at the Path Item Object level, it will be
	 * overridden by this value.
	 *
	 * @example [{ url: "https://api.example.com/v1" }]
	 */
	servers?: Server[];
}

/**
 * -----
 * Example Object
 * -----
 *
 * In all cases, the example value is expected to be compatible with the type schema
 * of its associated value. Tooling implementations MAY choose to validate compatibility
 * automatically, and reject the example value(s) if incompatible.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#example-object | OpenAPI 3.1.1 Example Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#example-object | OpenAPI 3.1.0 Example Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `summary` - Optional Short description for the example
 * @property `description` - Optional Long description for the example
 * @property `value` - Optional Embedded literal example
 * @property `externalValue` - Optional A URI that points to the literal example
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `value` and `externalValue` fields are mutually exclusive.
 *
 * -----
 * Examples
 * -----
 *
 * @example (embedded example):
 * ```ts
 * const example: Example = {
 *   summary: "A user example",
 *   value: {
 *     id: 1,
 *     name: "John Doe",
 *     email: "john@example.com"
 *   }
 * };
 * ```
 *
 * @example (external example):
 * ```ts
 * const example: Example = {
 *   summary: "External user example",
 *   externalValue: "https://example.com/examples/user-example.json"
 * };
 * ```
 */
export interface Example extends Extension {
	/**
	 * Short description for the example.
	 *
	 * @example "A user example"
	 * @example "Error response example"
	 */
	summary?: string;

	/**
	 * Long description for the example. CommonMark syntax MAY be used for rich text representation.
	 *
	 * @example "This example shows a typical user object with all required fields"
	 * @example "This example demonstrates an error response when validation fails"
	 */
	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.
	 *
	 * @example { id: 1, name: "John Doe" }
	 * @example "example string"
	 * @example 42
	 */
	value?: unknown;

	/**
	 * A URI that points to 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.
	 *
	 * @example "https://example.com/examples/user-example.json"
	 * @example "https://example.com/examples/error-example.xml"
	 */
	externalValue?: string;
}

/**
 * -----
 * Parameter Object
 * -----
 *
 * Describes a single operation parameter. A unique parameter is defined by a combination
 * of a name and location. The parameter name is case sensitive.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#parameter-object | OpenAPI 3.1.1 Parameter Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#parameter-object | OpenAPI 3.1.0 Parameter Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `name` - Required The name of the parameter
 * @property `in` - Required The location of the parameter
 * @property `description` - Optional A brief description of the parameter
 * @property `required` - Optional Determines whether this parameter is mandatory
 * @property `deprecated` - Optional Specifies that a parameter is deprecated
 * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued parameters
 * @property `style` - Optional Describes how the parameter value will be serialized
 * @property `explode` - Optional When this is true, parameter values of type array or object generate separate parameters for each value
 * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters
 * @property `schema` - Optional The schema defining the type used for the parameter
 * @property `example` - Optional Example of the parameter's potential value
 * @property `examples` - Optional Examples of the parameter's potential value
 * @property `content` - Optional A map containing the representations for the parameter
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `schema` and `content` fields are mutually exclusive. For path parameters, `required` must be true.
 *
 * -----
 * Examples
 * -----
 *
 * @example (query parameter):
 * ```ts
 * const parameter: Parameter = {
 *   name: "limit",
 *   in: "query",
 *   description: "Maximum number of items to return",
 *   required: false,
 *   schema: { type: "integer", minimum: 1, maximum: 100 }
 * };
 * ```
 *
 * @example (path parameter):
 * ```ts
 * const parameter: Parameter = {
 *   name: "userId",
 *   in: "path",
 *   description: "The user ID",
 *   required: true,
 *   schema: { type: "string" }
 * };
 * ```
 */
export interface Parameter extends Extension {
	/**
	 * The name of the parameter. Parameter names are case sensitive.
	 *
	 * @example "userId"
	 * @example "limit"
	 * @example "X-API-Key"
	 */
	name: string;

	/**
	 * The location of the parameter. Possible values are "query", "header", "path" or "cookie".
	 *
	 * @example "query"
	 * @example "path"
	 * @example "header"
	 * @example "cookie"
	 */
	in: "query" | "header" | "path" | "cookie";

	/**
	 * A brief description of the parameter. This could contain examples of use.
	 * CommonMark syntax MAY be used for rich text representation.
	 *
	 * @example "The user ID to retrieve"
	 * @example "Maximum number of items to return"
	 */
	description?: string;

	/**
	 * Determines whether this parameter is mandatory. If the parameter location is "path",
	 * this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be
	 * included and its default value is false.
	 *
	 * @example true
	 * @example false
	 */
	required?: boolean;

	/**
	 * Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
	 * Default value is false.
	 *
	 * @example true
	 * @example false
	 */
	deprecated?: boolean;

	/**
	 * Sets the ability to pass empty-valued parameters. This is valid only for query
	 * parameters and allows sending a parameter with an empty value. Default value is false.
	 *
	 * @example true
	 * @example false
	 */
	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.
	 *
	 * @example "simple"
	 * @example "form"
	 * @example "matrix"
	 * @example "label"
	 * @example "spaceDelimited"
	 * @example "pipeDelimited"
	 * @example "deepObject"
	 */
	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 property has no effect. When style is form, the default value is true. For all other
	 * styles, the default value is false.
	 *
	 * @example true
	 * @example false
	 */
	explode?: boolean;

	/**
	 * Determines whether the parameter value SHOULD allow reserved characters, as defined by
	 * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only
	 * applies to parameters with an in value of query. The default value is false.
	 *
	 * @example true
	 * @example false
	 */
	allowReserved?: boolean;

	/**
	 * The schema defining the type used for the parameter. This field is mutually exclusive
	 * with the content field.
	 *
	 * @example { type: "string" }
	 * @example { type: "integer", minimum: 1 }
	 */
	schema?: Schema;

	/**
	 * Example of the parameter's potential value. The example SHOULD match the specified
	 * schema and encoding properties if present. The example field is mutually exclusive
	 * of the examples field. Furthermore, if referencing a schema that contains an example,
	 * the example value SHALL override the example provided by the schema.
	 *
	 * @example "example value"
	 * @example 42
	 * @example { id: 1, name: "John" }
	 */
	example?: unknown;

	/**
	 * Examples of the parameter's potential value. Each example SHOULD contain a value in
	 * the correct format as specified in the parameter encoding. The examples field is
	 * mutually exclusive of the example field. Furthermore, if referencing a schema that
	 * contains an example, the examples value SHALL override the example provided by the schema.
	 *
	 * @example { "user1": { summary: "A user example", value: { id: 1, name: "John" } } }
	 */
	examples?: Record<string, Example | Reference>;

	/**
	 * 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. This field is
	 * mutually exclusive with the schema field.
	 *
	 * @example { "application/json": { schema: { type: "string" } } }
	 */
	content?: Record<string, MediaType>;
}

/**
 * -----
 * Request Body Object
 * -----
 *
 * Describes a single request body. A request body is the payload sent with an HTTP request.
 * The request body is only supported in HTTP methods where the HTTP 1.1 specification
 * RFC7231 has explicitly defined semantics for request bodies.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#request-body-object | OpenAPI 3.1.1 Request Body Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#request-body-object | OpenAPI 3.1.0 Request Body Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `description` - Optional A brief description of the request body
 * @property `content` - Required The content of the request body
 * @property `required` - Optional Determines if the request body is required in the request
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `content` field is required and must contain at least one media type.
 *
 * -----
 * Examples
 * -----
 *
 * @example (JSON request body):
 * ```ts
 * const requestBody: RequestBody = {
 *   description: "User data to create",
 *   required: true,
 *   content: {
 *     "application/json": {
 *       schema: { $ref: "#/components/schemas/User" }
 *     }
 *   }
 * };
 * ```
 *
 * @example (multipart request body):
 * ```ts
 * const requestBody: RequestBody = {
 *   description: "File upload",
 *   content: {
 *     "multipart/form-data": {
 *       schema: {
 *         type: "object",
 *         properties: {
 *           file: { type: "string", format: "binary" }
 *         }
 *       }
 *     }
 *   }
 * };
 * ```
 */
export interface RequestBody extends Extension {
	/**
	 * A brief description of the request body. This could contain examples of use.
	 * CommonMark syntax MAY be used for rich text representation.
	 *
	 * @example "User data to create"
	 * @example "File upload with metadata"
	 */
	description?: string;

	/**
	 * The content of the request body. The key is a media type or media type range and
	 * the value describes it. For request bodies that are sent using multipart/form-data,
	 * the encoding property is used to describe the encoding of the request body.
	 *
	 * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } }
	 * @example { "multipart/form-data": { schema: { type: "object", properties: { file: { type: "string", format: "binary" } } } } }
	 */
	content: Record<string, MediaType>;

	/**
	 * Determines if the request body is required in the request. Defaults to false.
	 *
	 * @example true
	 * @example false
	 */
	required?: boolean;
}

/**
 * -----
 * Response Object
 * -----
 *
 * Describes a single response from an API Operation, including design-time, static links
 * to operations based on the response.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#response-object | OpenAPI 3.1.1 Response Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#response-object | OpenAPI 3.1.0 Response Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `description` - Required A short description of the response
 * @property `headers` - Optional Maps a header name to its definition
 * @property `content` - Optional A map containing descriptions of potential response payloads
 * @property `links` - Optional A map of operations links that can be followed from the response
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `description` field is required and should describe the response.
 *
 * -----
 * Examples
 * -----
 *
 * @example (basic response):
 * ```ts
 * const response: Response = {
 *   description: "A list of users",
 *   content: {
 *     "application/json": {
 *       schema: { type: "array", items: { $ref: "#/components/schemas/User" } }
 *     }
 *   }
 * };
 * ```
 *
 * @example (response with headers):
 * ```ts
 * const response: Response = {
 *   description: "User created successfully",
 *   headers: {
 *     "Location": {
 *       description: "URL of the created user",
 *       schema: { type: "string" }
 *     }
 *   },
 *   content: {
 *     "application/json": {
 *       schema: { $ref: "#/components/schemas/User" }
 *     }
 *   }
 * };
 * ```
 */
export interface Response extends Extension {
	/**
	 * A short description of the response. CommonMark syntax MAY be used for rich text representation.
	 * This field is required.
	 *
	 * @example "A list of users"
	 * @example "User created successfully"
	 * @example "Bad request - validation failed"
	 */
	description: string;

	/**
	 * Maps a header name to its definition. RFC7230 states header names are case insensitive.
	 * If a response header is defined with the name "Content-Type", it SHALL be ignored.
	 *
	 * @example { "X-RateLimit-Limit": { description: "Rate limit per hour", schema: { type: "integer" } } }
	 */
	headers?: Record<string, Header | Reference>;

	/**
	 * A map containing descriptions of potential response payloads. The key is a media type
	 * or media type range and the value describes it. For responses that match multiple keys,
	 * only the most specific key is applicable. e.g. text/plain overrides text/*
	 *
	 * @example { "application/json": { schema: { $ref: "#/components/schemas/User" } } }
	 * @example { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/User" } } } }
	 */
	content?: Record<string, MediaType>;

	/**
	 * A map of operations links that can be followed from the response. The key of the map
	 * is a short name for the link, following the naming constraints of the names for
	 * Component Objects.
	 *
	 * @example { "GetUser": { operationId: "getUserById", parameters: { userId: "$response.body#/id" } } }
	 */
	links?: Record<string, Link | Reference>;
}

/**
 * -----
 * Header Object
 * -----
 *
 * The Header Object follows the structure of the Parameter Object 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).
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#header-object | OpenAPI 3.1.1 Header Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#header-object | OpenAPI 3.1.0 Header Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `description` - Optional A brief description of the header
 * @property `required` - Optional Determines whether this header is mandatory
 * @property `deprecated` - Optional Specifies that a header is deprecated
 * @property `allowEmptyValue` - Optional Sets the ability to pass empty-valued headers
 * @property `style` - Optional Describes how the header value will be serialized
 * @property `explode` - Optional When this is true, header values of type array or object generate separate headers for each value
 * @property `allowReserved` - Optional Determines whether the header value SHOULD allow reserved characters
 * @property `schema` - Optional The schema defining the type used for the header
 * @property `example` - Optional Example of the header's potential value
 * @property `examples` - Optional Examples of the header's potential value
 * @property `content` - Optional A map containing the representations for the header
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `schema` and `content` fields are mutually exclusive.
 *
 * -----
 * Examples
 * -----
 *
 * @example (simple header):
 * ```ts
 * const header: Header = {
 *   description: "Rate limit per hour",
 *   required: false,
 *   schema: { type: "integer" }
 * };
 * ```
 *
 * @example (header with content):
 * ```ts
 * const header: Header = {
 *   description: "Custom header with JSON content",
 *   content: {
 *     "application/json": {
 *       schema: { type: "object", properties: { value: { type: "string" } } }
 *     }
 *   }
 * };
 * ```
 */
export interface Header extends Extension {
	/**
	 * A brief description of the header. This could contain examples of use.
	 * CommonMark syntax MAY be used for rich text representation.
	 *
	 * @example "Rate limit per hour"
	 * @example "Custom authentication token"
	 */
	description?: string;

	/**
	 * Determines whether this header is mandatory. The property MAY be included and its
	 * default value is false.
	 *
	 * @example true
	 * @example false
	 */
	required?: boolean;

	/**
	 * Specifies that a header is deprecated and SHOULD be transitioned out of usage.
	 * Default value is false.
	 *
	 * @example true
	 * @example false
	 */
	deprecated?: boolean;

	/**
	 * Sets the ability to pass empty-valued headers. This is valid only for headers
	 * and allows sending a header with an empty value. Default value is false.
	 *
	 * @example true
	 * @example false
	 */
	allowEmptyValue?: boolean;

	/**
	 * Describes how the header value will be serialized. The default value is "simple".
	 *
	 * @example "simple"
	 * @example "form"
	 */
	style?: string;

	/**
	 * When this is true, header values of type array or object generate separate headers
	 * for each value of the array or key-value pair of the map. For other types of headers
	 * this property has no effect. When style is form, the default value is true. For all other
	 * styles, the default value is false.
	 *
	 * @example true
	 * @example false
	 */
	explode?: boolean;

	/**
	 * Determines whether the header value SHOULD allow reserved characters, as defined by
	 * RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false.
	 *
	 * @example true
	 * @example false
	 */
	allowReserved?: boolean;

	/**
	 * The schema defining the type used for the header. This field is mutually exclusive
	 * with the content field.
	 *
	 * @example { type: "string" }
	 * @example { type: "integer", minimum: 0 }
	 */
	schema?: Schema;

	/**
	 * Example of the header's potential value. The example SHOULD match the specified
	 * schema and encoding properties if present. The example field is mutually exclusive
	 * of the examples field.
	 *
	 * @example "example value"
	 * @example 42
	 */
	example?: unknown;

	/**
	 * Examples of the header's potential value. Each example SHOULD contain a value in
	 * the correct format as specified in the header encoding. The examples field is
	 * mutually exclusive of the example field.
	 *
	 * @example { "header1": { summary: "A header example", value: "example value" } }
	 */
	examples?: Record<string, Example | Reference>;

	/**
	 * 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. This field is
	 * mutually exclusive with the schema field.
	 *
	 * @example { "application/json": { schema: { type: "string" } } }
	 */
	content?: Record<string, MediaType>;
}

/**
 * -----
 * Media Type Object
 * -----
 *
 * Each Media Type Object provides schema and examples for the media type identified by its key.
 * Media Type Objects can be used in a Content Object.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#media-type-object | OpenAPI 3.1.1 Media Type Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#media-type-object | OpenAPI 3.1.0 Media Type Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `schema` - Optional The schema defining the content of the request, response, or parameter
 * @property `example` - Optional Example of the media type
 * @property `examples` - Optional Examples of the media type
 * @property `encoding` - Optional A map between a property name and its encoding information
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `example` and `examples` fields are mutually exclusive.
 *
 * -----
 * Examples
 * -----
 *
 * @example (JSON media type):
 * ```ts
 * const mediaType: MediaType = {
 *   schema: { $ref: "#/components/schemas/User" },
 *   example: { id: 1, name: "John Doe" }
 * };
 * ```
 *
 * @example (multipart media type with encoding):
 * ```ts
 * const mediaType: MediaType = {
 *   schema: {
 *     type: "object",
 *     properties: {
 *       file: { type: "string", format: "binary" },
 *       description: { type: "string" }
 *     }
 *   },
 *   encoding: {
 *     file: { contentType: "image/png" },
 *     description: { contentType: "text/plain" }
 *   }
 * };
 * ```
 */
export interface MediaType extends Extension {
	/**
	 * The schema defining the content of the request, response, or parameter.
	 *
	 * @example { $ref: "#/components/schemas/User" }
	 * @example { type: "array", items: { type: "string" } }
	 */
	schema?: Schema;

	/**
	 * Example of the media type. The example SHOULD match the specified schema and encoding
	 * properties if present. The example field is mutually exclusive of the examples field.
	 * Furthermore, if referencing a schema that contains an example, the example value
	 * SHALL override the example provided by the schema.
	 *
	 * @example { id: 1, name: "John Doe" }
	 * @example "example string"
	 * @example 42
	 */
	example?: unknown;

	/**
	 * Examples of the media type. Each example SHOULD contain a value in the correct format
	 * as specified in the media type encoding. The examples field is mutually exclusive
	 * of the example field. Furthermore, if referencing a schema that contains an example,
	 * the examples value SHALL override the example provided by the schema.
	 *
	 * @example { "user1": { summary: "A user example", value: { id: 1, name: "John" } } }
	 */
	examples?: Record<string, Example | Reference>;

	/**
	 * 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 object SHALL only apply to
	 * requestBody objects when the media type is multipart or application/x-www-form-urlencoded.
	 *
	 * @example { "file": { contentType: "image/png" }, "description": { contentType: "text/plain" } }
	 */
	encoding?: Record<string, Encoding>;
}

/**
 * -----
 * Encoding Object
 * -----
 *
 * A single encoding definition applied to a single schema property.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#encoding-object | OpenAPI 3.1.1 Encoding Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#encoding-object | OpenAPI 3.1.0 Encoding Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `contentType` - Optional The Content-Type for encoding a specific property
 * @property `headers` - Optional A map allowing additional information to be provided as headers
 * @property `style` - Optional Describes how a specific property value will be serialized
 * @property `explode` - Optional When this is true, property values of type array or object generate separate parameters for each value
 * @property `allowReserved` - Optional Determines whether the parameter value SHOULD allow reserved characters
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `style` property only applies to form data and query parameters.
 *
 * -----
 * Examples
 * -----
 *
 * @example (basic encoding):
 * ```ts
 * const encoding: Encoding = {
 *   contentType: "image/png",
 *   style: "form"
 * };
 * ```
 *
 * @example (encoding with headers):
 * ```ts
 * const encoding: Encoding = {
 *   contentType: "application/json",
 *   headers: {
 *     "X-Custom-Header": {
 *       description: "Custom header for this encoding",
 *       schema: { type: "string" }
 *     }
 *   }
 * };
 * ```
 */
export interface Encoding extends Extension {
	/**
	 * The Content-Type for encoding a specific property. Default value depends on the
	 * property type: for string with format being binary – application/octet-stream;
	 * for other primitive types – text/plain; for object – application/json;
	 * for array – the default is determined based on the inner type.
	 *
	 * @example "image/png"
	 * @example "application/json"
	 * @example "text/plain"
	 */
	contentType?: string;

	/**
	 * A map allowing additional information to be provided as headers, for example
	 * Content-Disposition. Content-Type is described separately and SHALL be ignored
	 * in this section. This property SHALL be ignored if the request body media type
	 * is not a multipart.
	 *
	 * @example { "Content-Disposition": { description: "File attachment", schema: { type: "string" } } }
	 */
	headers?: Record<string, Header | Reference>;

	/**
	 * Describes how a specific property value will be serialized depending on its type.
	 * See Parameter Object for details on the style property. The behavior follows the
	 * same values as query parameters, including default values. This property SHALL be
	 * ignored if the request body media type is not application/x-www-form-urlencoded
	 * or multipart/form-data.
	 *
	 * @example "form"
	 * @example "spaceDelimited"
	 * @example "pipeDelimited"
	 * @example "deepObject"
	 */
	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 property has no effect. When style is form, the default
	 * value is true. For all other styles, the default value is false. This property
	 * SHALL be ignored if the request body media type is not application/x-www-form-urlencoded
	 * or multipart/form-data.
	 *
	 * @example true
	 * @example false
	 */
	explode?: boolean;

	/**
	 * Determines whether the parameter value SHOULD allow reserved characters, as defined
	 * by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default
	 * value is false. This property SHALL be ignored if the request body media type is
	 * not application/x-www-form-urlencoded.
	 *
	 * @example true
	 * @example false
	 */
	allowReserved?: boolean;
}

/**
 * -----
 * Link Object
 * -----
 *
 * 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.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#link-object | OpenAPI 3.1.1 Link Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#link-object | OpenAPI 3.1.0 Link Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `operationRef` - Optional A relative or absolute reference to an OAS operation
 * @property `operationId` - Optional The name of an existing, resolvable OAS operation
 * @property `parameters` - Optional A map representing parameters to pass to an operation
 * @property `requestBody` - Optional A literal value or expression to use as a request body
 * @property `description` - Optional A description of the link
 * @property `server` - Optional A server object to be used by the target operation
 * @property `x-${string}` - Specification Extensions
 *
 * @note
 * The `operationRef` and `operationId` fields are mutually exclusive.
 *
 * -----
 * Examples
 * -----
 *
 * @example (link with operationId):
 * ```ts
 * const link: Link = {
 *   operationId: "getUserById",
 *   parameters: {
 *     userId: "$response.body#/id"
 *   },
 *   description: "Get the user by ID"
 * };
 * ```
 *
 * @example (link with operationRef):
 * ```ts
 * const link: Link = {
 *   operationRef: "#/paths/~1users~1{userId}/get",
 *   parameters: {
 *     userId: "$response.body#/id"
 *   }
 * };
 * ```
 */
export interface Link extends Extension {
	/**
	 * A relative or absolute reference to an OAS operation. This field is mutually exclusive
	 * of the operationId field, and MUST point to an Operation Object. Relative operationRef
	 * values MAY be used to locate an existing Operation Object in the OpenAPI definition.
	 *
	 * @example "#/paths/~1users~1{userId}/get"
	 * @example "https://example.com/openapi.json#/paths/~1users~1{userId}/get"
	 */
	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.
	 *
	 * @example "getUserById"
	 * @example "createUser"
	 */
	operationId?: string;

	/**
	 * A map representing parameters to pass to an operation as specified with operationId
	 * or identified via operationRef. The key is the parameter name to be used, whereas
	 * the value can be a constant or an expression to be evaluated and passed to the linked
	 * operation. The parameter name can be qualified using the parameter location [{in}.]{name}
	 * for operations that use the same parameter name in different locations (e.g. path.id).
	 *
	 * @example { "userId": "$response.body#/id" }
	 * @example { "path.id": "$response.body#/id", "query.limit": 10 }
	 */
	parameters?: Record<string, unknown>;

	/**
	 * A literal value or expression to use as a request body when calling the target operation.
	 *
	 * @example { "name": "John Doe", "email": "john@example.com" }
	 * @example "$request.body"
	 */
	requestBody?: unknown;

	/**
	 * A description of the link. CommonMark syntax MAY be used for rich text representation.
	 *
	 * @example "Get the user by ID"
	 * @example "Create a new user with the provided data"
	 */
	description?: string;

	/**
	 * A server object to be used by the target operation.
	 *
	 * @example { url: "https://api.example.com/v1" }
	 */
	server?: Server;
}

/**
 * -----
 * Callback Object
 * -----
 *
 * A map of possible out-of band callbacks related to the parent operation. Each value in the map
 * is a 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 callback object is an expression,
 * evaluated at runtime, that identifies a URL to use for the callback operation.
 *
 * | Version | Reference |
 * |---|-----|
 * | 3.1.1   | {@link https://spec.openapis.org/oas/v3.1.1#callback-object | OpenAPI 3.1.1 Callback Object} |
 * | 3.1.0   | {@link https://spec.openapis.org/oas/v3.1.0#callback-object | OpenAPI 3.1.0 Callback Object} |
 *
 * -----
 * Fields
 * -----
 *
 * @property `{expression}` - A Path Item Object or Reference to a Path Item Object
 *
 * @note
 * The key is a runtime expression that identifies a URL to use for the callback operation.
 * The expression is evaluated at runtime and MUST resolve to a URL.
 *
 * -----
 * Examples
 * -----
 *
 * @example (simple callback):
 * ```ts
 * const callback: Callback = {
 *   "{$request.body#/callbackUrl}": {
 *     post: {
 *       requestBody: {
 *         description: "Callback payload",
 *         content: {
 *           "application/json": {
 *             schema: { $ref: "#/components/schemas/CallbackPayload" }
 *           }
 *         }
 *       },
 *       responses: {
 *         "200": {
 *           description: "Callback received successfully"
 *         }
 *       }
 *     }
 *   }
 * };
 * ```
 *
 * @example (callback with multiple operations):
 * ```ts
 * const callback: Callback = {
 *   "{$request.body#/callbackUrl}": {
 *     post: {
 *       summary: "Success callback",
 *       requestBody: { description: "Success payload" }
 *     },
 *     put: {
 *       summary: "Update callback",
 *       requestBody: { description: "Update payload" }
 *     }
 *   }
 * };
 * ```
 */
export interface Callback {
	/**
	 * A runtime expression that identifies a URL to use for the callback operation.
	 * The expression is evaluated at runtime and MUST resolve to a URL. The value
	 * is a Path Item Object that describes the callback operations.
	 *
	 * @example "{$request.body#/callbackUrl}"
	 * @example "{$request.body#/webhookUrl}"
	 * @example "{$request.body#/notificationUrl}"
	 */
	[expression: string]: PathItem | Reference;
}