import type { ReferenceSchema, StringSchema, NumberSchema, IntegerSchema, BooleanSchema, ArraySchema, ObjectSchema, CompositionSchema, } from "./data-types" import type { Reference } from "./references" import type { XML } from "./xml" import type { ExternalDocumentation } from "./externalDocs" import type { Components } from "./components" // Discriminator will be defined below to avoid circular reference /** * ----- * Schema Object (OpenAPI 3.0.x) * ----- * * 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 based on JSON Schema Specification Draft 7 and uses the same * formatting rules. * * This discriminated union enforces the OpenAPI 3.0.x mutual-exclusion and * co-occurrence rules, ensuring that only valid combinations of properties * can be used together. * * | Version | Reference | * |---|-----| * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#schema-object | OpenAPI 3.0.0 Schema Object} | * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#schema-object | OpenAPI 3.0.1 Schema Object} | * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#schema-object | OpenAPI 3.0.2 Schema Object} | * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#schema-object | OpenAPI 3.0.3 Schema Object} | * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#schema-object | OpenAPI 3.0.4 Schema Object} | * * ----- * Schema Types * ----- * * @key `ReferenceSchema` - Reference-only schemas ($ref with optional description) * @key `StringSchema` - String schemas with string-specific constraints * @key `NumberSchema` - Number schemas with numeric constraints * @key `IntegerSchema` - Integer schemas with integer constraints * @key `BooleanSchema` - Boolean schemas with basic validation * @key `ArraySchema` - Array schemas with array-specific constraints * @key `ObjectSchema` - Object schemas with object-specific constraints * @key `CompositionSchema` - Composition schemas (allOf/anyOf/oneOf/not) * * @note * The discriminated union enforces these OpenAPI 3.0.x rules: * - `$ref` is mutually exclusive with all other properties except description and extensions * - Type-specific constraints are only valid with their corresponding type * - Composition keywords are mutually exclusive with `$ref` but can appear with validation keywords * - Metadata keywords can appear with any valid combination * * ----- * Examples * ----- * * @example (reference schema): * ```ts * const refSchema: Schema = { * $ref: "#/components/schemas/User", * description: "A reference to the User schema" * }; * ``` * * @example (string schema): * ```ts * const stringSchema: Schema = { * type: "string", * minLength: 1, * maxLength: 100, * pattern: "^[a-zA-Z]+$" * }; * ``` * * @example (object schema): * ```ts * const objectSchema: Schema = { * type: "object", * properties: { * name: { type: "string" }, * age: { type: "integer" } * }, * required: ["name"] * }; * ``` * * @example (composition schema): * ```ts * const composedSchema: Schema = { * allOf: [ * { $ref: "#/components/schemas/BaseUser" }, * { type: "object", required: ["id"] } * ] * }; * ``` */ export type Schema = | ReferenceSchema | StringSchema | NumberSchema | IntegerSchema | BooleanSchema | ArraySchema | ObjectSchema | CompositionSchema /** * ----- * Discriminator Object * ----- * * When request bodies or response payloads may be one of a number of different schemas, * a discriminator object can be used to aid in serialization, deserialization, and validation. * The discriminator is a specific object in a schema which is used to inform the consumer * of the specification of an alternative schema based on the value associated with it. * * | Version | Reference | * |---|-----| * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#discriminator-object | OpenAPI 3.0.0 Discriminator Object} | * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#discriminator-object | OpenAPI 3.0.1 Discriminator Object} | * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#discriminator-object | OpenAPI 3.0.2 Discriminator Object} | * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#discriminator-object | OpenAPI 3.0.3 Discriminator Object} | * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#discriminator-object | OpenAPI 3.0.4 Discriminator Object} | * * ----- * Fields * ----- * * @key `propertyName` - The name of the property in the schema that is used as a discriminator * @key `mapping` - An object to hold mappings between payload values and schema names or references * @key `x-${string}` - Specification Extensions * * @note * The discriminator property name MUST be defined at this schema and it MUST be in the * required property list. When used, the value MUST be the name of this schema or any * schema that inherits it. * * ----- * Examples * ----- * * @example (basic discriminator): * ```ts * const discriminator: Discriminator = { * propertyName: "petType" * }; * ``` * * @example (discriminator with mapping): * ```ts * const discriminator: Discriminator = { * propertyName: "petType", * mapping: { * "dog": "#/components/schemas/Dog", * "cat": "#/components/schemas/Cat" * } * }; * ``` */ export interface Discriminator { /** * The name of the property in the schema that is used as a discriminator. * * @example "petType" * @example "type" * @example "kind" */ propertyName: string /** * An object to hold mappings between payload values and schema names or references. * * @example { "dog": "Dog", "cat": "Cat" } * @example { "admin": "AdminUser", "user": "RegularUser" } */ mapping?: Record } /** * ----- * XML Object * ----- * * 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 property should be used to add that information. * * | Version | Reference | * |---|-----| * | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#xml-object | OpenAPI 3.0.0 XML Object} | * | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#xml-object | OpenAPI 3.0.1 XML Object} | * | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#xml-object | OpenAPI 3.0.2 XML Object} | * | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#xml-object | OpenAPI 3.0.3 XML Object} | * | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#xml-object | OpenAPI 3.0.4 XML Object} | * * ----- * Fields * ----- * * @key `name` - Replaces the name of the element/attribute used for the described schema property * @key `namespace` - The URL of the namespace definition * @key `prefix` - The prefix to be used for the name * @key `attribute` - Declares whether the property definition translates to an attribute instead of an element * @key `wrapped` - Signifies whether the array is wrapped * @key `x-${string}` - Specification Extensions * * @note * 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 * and only if wrapped is true. * * ----- * Examples * ----- * * @example (basic XML): * ```ts * const xml: XML = { * name: "animal", * namespace: "http://example.com/schema", * prefix: "ex" * }; * ``` * * @example (XML attribute): * ```ts * const xml: XML = { * name: "id", * attribute: true * }; * ``` * * @example (wrapped array): * ```ts * const xml: XML = { * name: "items", * wrapped: true * }; * ``` */