typia 9.3.1 → 9.5.0-dev.20250710

package/lib/schemas/json/IJsonSchemaCollection.d.mts

@@ -1,23 +1,181 @@
 import type { OpenApi, OpenApiV3 } from "@samchon/openapi";
 /**
- * Collection of JSON schemas.
+ * Collection of JSON schemas with OpenAPI specification support.
+ *
+ * `IJsonSchemaCollection` represents a comprehensive collection of JSON schemas
+ * that can be generated from TypeScript types using the `typia.json.schemas()` function.
+ * This interface supports both OpenAPI v3.0 and v3.1 specifications, with the ability
+ * to automatically generate appropriate schema definitions based on the specified version.
+ *
+ * The collection includes:
+ * - Generated JSON schemas array containing schema definitions for the specified types
+ * - Reusable components that can be referenced across different schemas
+ * - Version-specific formatting that adheres to either OpenAPI v3.0 or v3.1 standards
+ *
+ * Key differences between versions:
+ * - OpenAPI v3.0: Uses {@link OpenApiV3.IJsonSchema} format with limited tuple support
+ * - OpenAPI v3.1: Uses {@link OpenApi.IJsonSchema} format with full JSON Schema Draft 2020-12 compatibility
+ *
+ * @template Version The OpenAPI specification version to target ("3.0" or "3.1").
+ *                   Defaults to "3.1" for enhanced JSON Schema compatibility.
+ * @template Types   Array of original TypeScript types that were analyzed to generate
+ *                   the JSON schemas. This provides type safety and traceability
+ *                   back to the source TypeScript definitions.
+ *
+ * @example
+ * ```typescript
+ * // Generate schemas for OpenAPI v3.1 (default)
+ * const schemas = typia.json.schemas<[User, Product]>();
+ * // Type: IJsonSchemaCollection<"3.1", [User, Product]>
+ *
+ * // Generate schemas for OpenAPI v3.0 (Swagger compatibility)
+ * const swaggerSchemas = typia.json.schemas<[User, Product], "3.0">();
+ * // Type: IJsonSchemaCollection<"3.0", [User, Product]>
+ * ```
  *
- * @template Version Version of the OpenAPI specification.
- * @template Types Original TypeScript types used in the JSON schemas.
  * @author Jeongho Nam - https://github.com/samchon
  */
 export type IJsonSchemaCollection<Version extends "3.0" | "3.1" = "3.1", Types = unknown[]> = Version extends "3.0" ? IJsonSchemaCollection.IV3_0<Types> : IJsonSchemaCollection.IV3_1<Types>;
 export declare namespace IJsonSchemaCollection {
+    /**
+     * JSON Schema collection formatted for OpenAPI v3.0 specification.
+     *
+     * This interface represents a collection of JSON schemas that comply with
+     * OpenAPI v3.0 standards, which are compatible with Swagger tools and
+     * legacy OpenAPI implementations. OpenAPI v3.0 has some limitations
+     * compared to v3.1, particularly around tuple types and pattern properties.
+     *
+     * Key characteristics of v3.0:
+     * - Cannot express tuple types natively (falls back to array representations)
+     * - Cannot express pattern properties in object schemas
+     * - Uses nullable property instead of union with null type
+     * - Limited JSON Schema Draft compatibility (based on Draft 4)
+     *
+     * @template Types Array of original TypeScript types used to generate the schemas.
+     *                 This provides compile-time type information about what types
+     *                 were analyzed during schema generation.
+     */
     interface IV3_0<Types = unknown[]> {
+        /**
+         * OpenAPI specification version identifier.
+         *
+         * Always set to "3.0" to indicate this collection uses OpenAPI v3.0
+         * schema format and constraints.
+         */
         version: "3.0";
+        /**
+         * Array of generated JSON schemas.
+         *
+         * Contains the actual JSON schema definitions generated from the input TypeScript types.
+         * Each schema in this array corresponds to one of the types specified in the `Types`
+         * template parameter. The schemas follow OpenAPI v3.0 format and may contain
+         * references to components defined in the {@link components} property.
+         *
+         * Schema references typically use the format: `{ "$ref": "#/components/schemas/TypeName" }`
+         */
         schemas: OpenApiV3.IJsonSchema[];
+        /**
+         * Reusable schema components for OpenAPI v3.0.
+         *
+         * Contains reusable schema definitions, security schemes, and other components
+         * that can be referenced from the main schemas. This follows the OpenAPI v3.0
+         * components structure and enables schema reuse and modularity.
+         *
+         * Components include:
+         * - schemas: Named type definitions that can be referenced via $ref
+         * - securitySchemes: Authentication and authorization schemes
+         * - parameters: Reusable parameter definitions
+         * - requestBodies: Reusable request body definitions
+         * - responses: Reusable response definitions
+         * - headers: Reusable header definitions
+         * - examples: Reusable example definitions
+         */
         components: OpenApiV3.IComponents;
+        /**
+         * Type metadata for compile-time type tracking.
+         *
+         * This optional property stores the original TypeScript types that were
+         * used to generate the JSON schemas. It's primarily used for type safety
+         * and doesn't affect runtime behavior. The property is marked as optional
+         * and undefined to prevent it from appearing in serialized JSON output.
+         *
+         * This enables:
+         * - Compile-time type checking against the original types
+         * - IDE intellisense and autocompletion
+         * - Type-safe schema validation and usage
+         */
         __types?: Types | undefined;
     }
+    /**
+     * JSON Schema collection formatted for OpenAPI v3.1 specification.
+     *
+     * This interface represents a collection of JSON schemas that comply with
+     * OpenAPI v3.1 standards, which provide enhanced JSON Schema compatibility
+     * and support for modern JSON Schema features. OpenAPI v3.1 is based on
+     * JSON Schema Draft 2020-12 and offers significant improvements over v3.0.
+     *
+     * Key advantages of v3.1:
+     * - Full tuple type support with prefixItems
+     * - Pattern properties support for dynamic object keys
+     * - Proper null type handling via union types
+     * - Enhanced JSON Schema Draft 2020-12 compatibility
+     * - Better const, enum, and validation support
+     *
+     * @template Types Array of original TypeScript types used to generate the schemas.
+     *                 This provides compile-time type information about what types
+     *                 were analyzed during schema generation.
+     */
     interface IV3_1<Types = unknown[]> {
+        /**
+         * OpenAPI specification version identifier.
+         *
+         * Always set to "3.1" to indicate this collection uses OpenAPI v3.1
+         * schema format with enhanced JSON Schema compatibility.
+         */
         version: "3.1";
+        /**
+         * Reusable schema components for OpenAPI v3.1.
+         *
+         * Contains reusable schema definitions and other components following the
+         * OpenAPI v3.1 specification. This structure is similar to v3.0 but supports
+         * enhanced JSON Schema features and improved type definitions.
+         *
+         * Components include:
+         * - schemas: Named type definitions with enhanced JSON Schema support
+         * - securitySchemes: Authentication and authorization schemes
+         *
+         * The emended OpenAPI v3.1 format used here removes ambiguous expressions
+         * and standardizes certain patterns for better tooling compatibility.
+         */
         components: OpenApi.IComponents;
+        /**
+         * Array of generated JSON schemas with v3.1 enhancements.
+         *
+         * Contains JSON schema definitions that take advantage of OpenAPI v3.1's
+         * enhanced capabilities. These schemas can express more complex TypeScript
+         * types accurately, including:
+         * - Tuple types using prefixItems
+         * - Union types with proper null handling
+         * - Complex nested object structures
+         * - Pattern-based property definitions
+         *
+         * Each schema corresponds to one of the input TypeScript types and may
+         * reference components defined in the {@link components} property.
+         */
         schemas: OpenApi.IJsonSchema[];
+        /**
+         * Type metadata for compile-time type tracking.
+         *
+         * This optional property stores the original TypeScript types that were
+         * used to generate the JSON schemas. It provides compile-time type safety
+         * and enables better development experience without affecting runtime behavior.
+         *
+         * Benefits include:
+         * - Strong typing connection to original TypeScript definitions
+         * - Enhanced IDE support and autocompletion
+         * - Compile-time validation of schema usage
+         * - Type-safe integration with validation libraries
+         */
         __types?: Types | undefined;
     }
 }

package/lib/schemas/json/IJsonSchemaCollection.d.ts

@@ -1,23 +1,181 @@
 import type { OpenApi, OpenApiV3 } from "@samchon/openapi";
 /**
- * Collection of JSON schemas.
+ * Collection of JSON schemas with OpenAPI specification support.
+ *
+ * `IJsonSchemaCollection` represents a comprehensive collection of JSON schemas
+ * that can be generated from TypeScript types using the `typia.json.schemas()` function.
+ * This interface supports both OpenAPI v3.0 and v3.1 specifications, with the ability
+ * to automatically generate appropriate schema definitions based on the specified version.
+ *
+ * The collection includes:
+ * - Generated JSON schemas array containing schema definitions for the specified types
+ * - Reusable components that can be referenced across different schemas
+ * - Version-specific formatting that adheres to either OpenAPI v3.0 or v3.1 standards
+ *
+ * Key differences between versions:
+ * - OpenAPI v3.0: Uses {@link OpenApiV3.IJsonSchema} format with limited tuple support
+ * - OpenAPI v3.1: Uses {@link OpenApi.IJsonSchema} format with full JSON Schema Draft 2020-12 compatibility
+ *
+ * @template Version The OpenAPI specification version to target ("3.0" or "3.1").
+ *                   Defaults to "3.1" for enhanced JSON Schema compatibility.
+ * @template Types   Array of original TypeScript types that were analyzed to generate
+ *                   the JSON schemas. This provides type safety and traceability
+ *                   back to the source TypeScript definitions.
+ *
+ * @example
+ * ```typescript
+ * // Generate schemas for OpenAPI v3.1 (default)
+ * const schemas = typia.json.schemas<[User, Product]>();
+ * // Type: IJsonSchemaCollection<"3.1", [User, Product]>
+ *
+ * // Generate schemas for OpenAPI v3.0 (Swagger compatibility)
+ * const swaggerSchemas = typia.json.schemas<[User, Product], "3.0">();
+ * // Type: IJsonSchemaCollection<"3.0", [User, Product]>
+ * ```
  *
- * @template Version Version of the OpenAPI specification.
- * @template Types Original TypeScript types used in the JSON schemas.
  * @author Jeongho Nam - https://github.com/samchon
  */
 export type IJsonSchemaCollection<Version extends "3.0" | "3.1" = "3.1", Types = unknown[]> = Version extends "3.0" ? IJsonSchemaCollection.IV3_0<Types> : IJsonSchemaCollection.IV3_1<Types>;
 export declare namespace IJsonSchemaCollection {
+    /**
+     * JSON Schema collection formatted for OpenAPI v3.0 specification.
+     *
+     * This interface represents a collection of JSON schemas that comply with
+     * OpenAPI v3.0 standards, which are compatible with Swagger tools and
+     * legacy OpenAPI implementations. OpenAPI v3.0 has some limitations
+     * compared to v3.1, particularly around tuple types and pattern properties.
+     *
+     * Key characteristics of v3.0:
+     * - Cannot express tuple types natively (falls back to array representations)
+     * - Cannot express pattern properties in object schemas
+     * - Uses nullable property instead of union with null type
+     * - Limited JSON Schema Draft compatibility (based on Draft 4)
+     *
+     * @template Types Array of original TypeScript types used to generate the schemas.
+     *                 This provides compile-time type information about what types
+     *                 were analyzed during schema generation.
+     */
     interface IV3_0<Types = unknown[]> {
+        /**
+         * OpenAPI specification version identifier.
+         *
+         * Always set to "3.0" to indicate this collection uses OpenAPI v3.0
+         * schema format and constraints.
+         */
         version: "3.0";
+        /**
+         * Array of generated JSON schemas.
+         *
+         * Contains the actual JSON schema definitions generated from the input TypeScript types.
+         * Each schema in this array corresponds to one of the types specified in the `Types`
+         * template parameter. The schemas follow OpenAPI v3.0 format and may contain
+         * references to components defined in the {@link components} property.
+         *
+         * Schema references typically use the format: `{ "$ref": "#/components/schemas/TypeName" }`
+         */
         schemas: OpenApiV3.IJsonSchema[];
+        /**
+         * Reusable schema components for OpenAPI v3.0.
+         *
+         * Contains reusable schema definitions, security schemes, and other components
+         * that can be referenced from the main schemas. This follows the OpenAPI v3.0
+         * components structure and enables schema reuse and modularity.
+         *
+         * Components include:
+         * - schemas: Named type definitions that can be referenced via $ref
+         * - securitySchemes: Authentication and authorization schemes
+         * - parameters: Reusable parameter definitions
+         * - requestBodies: Reusable request body definitions
+         * - responses: Reusable response definitions
+         * - headers: Reusable header definitions
+         * - examples: Reusable example definitions
+         */
         components: OpenApiV3.IComponents;
+        /**
+         * Type metadata for compile-time type tracking.
+         *
+         * This optional property stores the original TypeScript types that were
+         * used to generate the JSON schemas. It's primarily used for type safety
+         * and doesn't affect runtime behavior. The property is marked as optional
+         * and undefined to prevent it from appearing in serialized JSON output.
+         *
+         * This enables:
+         * - Compile-time type checking against the original types
+         * - IDE intellisense and autocompletion
+         * - Type-safe schema validation and usage
+         */
         __types?: Types | undefined;
     }
+    /**
+     * JSON Schema collection formatted for OpenAPI v3.1 specification.
+     *
+     * This interface represents a collection of JSON schemas that comply with
+     * OpenAPI v3.1 standards, which provide enhanced JSON Schema compatibility
+     * and support for modern JSON Schema features. OpenAPI v3.1 is based on
+     * JSON Schema Draft 2020-12 and offers significant improvements over v3.0.
+     *
+     * Key advantages of v3.1:
+     * - Full tuple type support with prefixItems
+     * - Pattern properties support for dynamic object keys
+     * - Proper null type handling via union types
+     * - Enhanced JSON Schema Draft 2020-12 compatibility
+     * - Better const, enum, and validation support
+     *
+     * @template Types Array of original TypeScript types used to generate the schemas.
+     *                 This provides compile-time type information about what types
+     *                 were analyzed during schema generation.
+     */
     interface IV3_1<Types = unknown[]> {
+        /**
+         * OpenAPI specification version identifier.
+         *
+         * Always set to "3.1" to indicate this collection uses OpenAPI v3.1
+         * schema format with enhanced JSON Schema compatibility.
+         */
         version: "3.1";
+        /**
+         * Reusable schema components for OpenAPI v3.1.
+         *
+         * Contains reusable schema definitions and other components following the
+         * OpenAPI v3.1 specification. This structure is similar to v3.0 but supports
+         * enhanced JSON Schema features and improved type definitions.
+         *
+         * Components include:
+         * - schemas: Named type definitions with enhanced JSON Schema support
+         * - securitySchemes: Authentication and authorization schemes
+         *
+         * The emended OpenAPI v3.1 format used here removes ambiguous expressions
+         * and standardizes certain patterns for better tooling compatibility.
+         */
         components: OpenApi.IComponents;
+        /**
+         * Array of generated JSON schemas with v3.1 enhancements.
+         *
+         * Contains JSON schema definitions that take advantage of OpenAPI v3.1's
+         * enhanced capabilities. These schemas can express more complex TypeScript
+         * types accurately, including:
+         * - Tuple types using prefixItems
+         * - Union types with proper null handling
+         * - Complex nested object structures
+         * - Pattern-based property definitions
+         *
+         * Each schema corresponds to one of the input TypeScript types and may
+         * reference components defined in the {@link components} property.
+         */
         schemas: OpenApi.IJsonSchema[];
+        /**
+         * Type metadata for compile-time type tracking.
+         *
+         * This optional property stores the original TypeScript types that were
+         * used to generate the JSON schemas. It provides compile-time type safety
+         * and enables better development experience without affecting runtime behavior.
+         *
+         * Benefits include:
+         * - Strong typing connection to original TypeScript definitions
+         * - Enhanced IDE support and autocompletion
+         * - Compile-time validation of schema usage
+         * - Type-safe integration with validation libraries
+         */
         __types?: Types | undefined;
     }
 }

package/lib/schemas/json/IJsonSchemaUnit.d.mts

@@ -1,26 +1,236 @@
 import { OpenApi, OpenApiV3 } from "@samchon/openapi";
 /**
- * Unit of JSON schema.
+ * Single unit of JSON schema representation.
  *
- * `IJsonSchemaUnit` is a type that represents a single JSON schema unit
- * containing the schema and components.
+ * `IJsonSchemaUnit` represents a self-contained JSON schema unit that encapsulates
+ * a single schema definition along with its associated reusable components. This is
+ * typically used when generating a JSON schema for a single TypeScript type, as
+ * opposed to a collection of multiple types.
  *
- * @template Version Version of the OpenAPI specification
- * @template Type Original TypeScript type used in the JSON schema
+ * Unlike {@link IJsonSchemaCollection} which handles multiple schemas, `IJsonSchemaUnit`
+ * focuses on representing a single schema with its dependencies. This makes it ideal
+ * for scenarios where you need to work with individual type definitions or when
+ * integrating with systems that expect single schema documents.
+ *
+ * The unit contains:
+ * - A single JSON schema definition for the specified TypeScript type
+ * - All necessary reusable components that the schema may reference
+ * - Version-specific formatting for either OpenAPI v3.0 or v3.1 compatibility
+ * - Optional type metadata for compile-time type safety
+ *
+ * Key differences from collection:
+ * - Contains only one schema instead of an array of schemas
+ * - More lightweight for single-type use cases
+ * - Simpler structure for direct schema consumption
+ * - Still maintains full component reference support
+ *
+ * @template Version The OpenAPI specification version to target ("3.0" or "3.1").
+ *                   Defaults to "3.1" for enhanced JSON Schema Draft 2020-12 compatibility.
+ *                   This determines the schema format, validation capabilities, and
+ *                   available features like tuple support and null type handling.
+ * @template Type    The original TypeScript type that was analyzed to generate this
+ *                   JSON schema unit. This provides compile-time type safety and
+ *                   enables IDEs to provide better intellisense and validation.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email?: string;
+ * }
+ *
+ * // Generate a single schema unit for OpenAPI v3.1 (default)
+ * const userSchema = typia.json.schema<User>();
+ * // Type: IJsonSchemaUnit<"3.1", User>
+ *
+ * // Generate a single schema unit for OpenAPI v3.0 (Swagger compatibility)
+ * const swaggerUserSchema = typia.json.schema<User, "3.0">();
+ * // Type: IJsonSchemaUnit<"3.0", User>
+ * ```
+ *
+ * @see {@link IJsonSchemaCollection} For handling multiple schemas at once
  * @author Jeongho Nam - https://github.com/samchon
  */
 export type IJsonSchemaUnit<Version extends "3.0" | "3.1" = "3.1", Type = unknown> = Version extends "3.0" ? IJsonSchemaUnit.IV3_0<Type> : IJsonSchemaUnit.IV3_1<Type>;
 export declare namespace IJsonSchemaUnit {
+    /**
+     * JSON Schema unit formatted for OpenAPI v3.0 specification.
+     *
+     * This interface represents a single JSON schema unit that complies with
+     * OpenAPI v3.0 standards. It contains one schema definition along with
+     * any reusable components that the schema references, formatted according
+     * to OpenAPI v3.0 constraints and limitations.
+     *
+     * OpenAPI v3.0 characteristics affecting this unit:
+     * - Schema follows OpenAPI v3.0 JSON Schema subset
+     * - Limited support for advanced JSON Schema features
+     * - Uses nullable property for optional null values
+     * - Cannot natively express tuple types or pattern properties
+     * - Based on JSON Schema Draft 4 with OpenAPI-specific extensions
+     *
+     * Use cases for v3.0:
+     * - Integration with legacy Swagger tooling
+     * - Compatibility with older OpenAPI implementations
+     * - Systems that specifically require OpenAPI v3.0 format
+     * - Code generation tools that expect v3.0 schemas
+     *
+     * @template Type The original TypeScript type represented by this schema unit.
+     *                Provides compile-time type information and enables type-safe
+     *                operations on the schema.
+     */
     interface IV3_0<Type> {
+        /**
+         * OpenAPI specification version identifier.
+         *
+         * Always set to "3.0" to indicate this schema unit uses OpenAPI v3.0
+         * format and adheres to its specific constraints and limitations.
+         */
         version: "3.0";
+        /**
+         * The primary JSON schema definition.
+         *
+         * Contains the main JSON schema that represents the TypeScript type specified
+         * in the `Type` template parameter. This schema follows OpenAPI v3.0 format
+         * and may contain references to reusable components defined in the
+         * {@link components} property.
+         *
+         * The schema structure includes:
+         * - Type definitions following OpenAPI v3.0 constraints
+         * - Property definitions with v3.0-compatible validation rules
+         * - References to shared components using $ref syntax
+         * - Nullable properties for optional fields that can be null
+         *
+         * Example schema reference: `{ "$ref": "#/components/schemas/NestedType" }`
+         */
         schema: OpenApiV3.IJsonSchema;
+        /**
+         * Reusable schema components for OpenAPI v3.0.
+         *
+         * Contains all reusable schema definitions and components that may be
+         * referenced by the main schema. This enables schema modularity and
+         * prevents duplication when the same types are used in multiple places
+         * within the schema definition.
+         *
+         * Component categories include:
+         * - schemas: Named type definitions for complex objects, arrays, and unions
+         * - securitySchemes: Authentication and authorization definitions
+         * - parameters: Reusable parameter specifications
+         * - requestBodies: Reusable request body definitions
+         * - responses: Reusable response specifications
+         * - headers: Reusable header definitions
+         * - examples: Reusable example values
+         *
+         * All components follow OpenAPI v3.0 format restrictions and capabilities.
+         */
         components: OpenApiV3.IComponents;
+        /**
+         * Type metadata for compile-time type safety.
+         *
+         * This optional property maintains a reference to the original TypeScript
+         * type that was used to generate this schema unit. It provides compile-time
+         * type information without affecting the runtime JSON representation.
+         *
+         * Benefits of type metadata:
+         * - Enables type-safe schema validation and usage
+         * - Provides IDE intellisense and autocompletion
+         * - Allows compile-time checking of schema operations
+         * - Maintains traceability to original TypeScript definitions
+         *
+         * The property is intentionally marked as optional and undefined to ensure
+         * it doesn't appear in serialized JSON output while preserving type information
+         * at compile time.
+         */
         __type?: Type | undefined;
     }
+    /**
+     * JSON Schema unit formatted for OpenAPI v3.1 specification.
+     *
+     * This interface represents a single JSON schema unit that takes advantage
+     * of OpenAPI v3.1's enhanced capabilities and improved JSON Schema compatibility.
+     * It provides a more feature-rich and accurate representation of TypeScript
+     * types compared to the v3.0 format.
+     *
+     * OpenAPI v3.1 advantages for this unit:
+     * - Full JSON Schema Draft 2020-12 compatibility
+     * - Native tuple type support using prefixItems
+     * - Proper null type handling via union types
+     * - Pattern properties for dynamic object keys
+     * - Enhanced const, enum, and validation capabilities
+     * - Better support for complex nested structures
+     *
+     * Use cases for v3.1:
+     * - Modern OpenAPI implementations and tooling
+     * - Systems requiring accurate TypeScript type representation
+     * - Applications needing advanced JSON Schema features
+     * - New projects without legacy compatibility requirements
+     *
+     * @template Type The original TypeScript type represented by this schema unit.
+     *                Enables compile-time type safety and provides enhanced
+     *                development experience with better IDE support.
+     */
     interface IV3_1<Type> {
+        /**
+         * OpenAPI specification version identifier.
+         *
+         * Always set to "3.1" to indicate this schema unit uses OpenAPI v3.1
+         * format with enhanced JSON Schema compatibility and modern features.
+         */
         version: "3.1";
+        /**
+         * The primary JSON schema definition with v3.1 enhancements.
+         *
+         * Contains the main JSON schema that accurately represents the TypeScript
+         * type using OpenAPI v3.1's enhanced capabilities. This schema can express
+         * complex TypeScript constructs that were not possible or accurate in v3.0.
+         *
+         * Enhanced schema features include:
+         * - Tuple types using prefixItems for exact array structure
+         * - Union types with proper null handling via oneOf
+         * - Const values for literal types
+         * - Pattern properties for Record<string, T> types
+         * - Advanced validation constraints and metadata
+         * - Recursive type definitions with proper $ref handling
+         *
+         * The schema follows the emended OpenAPI v3.1 format used by typia,
+         * which removes ambiguous expressions while maintaining full compatibility.
+         */
         schema: OpenApi.IJsonSchema;
+        /**
+         * Reusable schema components for OpenAPI v3.1.
+         *
+         * Contains reusable schema definitions and components that leverage
+         * OpenAPI v3.1's enhanced capabilities. These components provide better
+         * type representation and more accurate schema definitions compared to v3.0.
+         *
+         * Enhanced component features:
+         * - schemas: More accurate type definitions with v3.1 JSON Schema features
+         * - securitySchemes: Enhanced authentication scheme definitions
+         * - Better support for complex nested references
+         * - Improved handling of recursive and circular type dependencies
+         *
+         * The components structure follows the emended OpenAPI v3.1 specification
+         * that simplifies certain patterns while maintaining full expressiveness.
+         */
         components: OpenApi.IComponents;
+        /**
+         * Type metadata for enhanced compile-time type safety.
+         *
+         * This optional property preserves the original TypeScript type information
+         * for compile-time type checking and enhanced development experience. It
+         * enables type-safe operations and better IDE support without affecting
+         * the runtime JSON schema representation.
+         *
+         * Enhanced type safety features:
+         * - Strong typing connection to original TypeScript definitions
+         * - Better IDE intellisense and error detection
+         * - Compile-time validation of schema usage patterns
+         * - Type-safe integration with validation and serialization libraries
+         * - Enhanced debugging and development experience
+         *
+         * The property remains optional and undefined to maintain clean JSON
+         * serialization while preserving valuable compile-time information.
+         */
         __type?: Type | undefined;
     }
 }