import { AutoBePrisma } from "./AutoBePrisma";
 
/**
 * Union type representing the result of Prisma schema validation.
 *
 * This type encapsulates the outcome of validating an AutoBePrisma.IApplication
 * structure against Prisma schema rules and business constraints. The
 * validation process checks for structural integrity, referential consistency,
 * naming conventions, and compliance with the established schema generation
 * rules.
 *
 * The validation can result in either complete success (all rules satisfied) or
 * failure with detailed error information for precise error resolution.
 *
 * @author Samchon
 */
export type IAutoBePrismaValidation =
  | IAutoBePrismaValidation.ISuccess
  | IAutoBePrismaValidation.IFailure;
 
/**
 * Namespace containing all interfaces for Prisma schema validation results.
 *
 * This namespace defines the structure for validation responses from the schema
 * validation system, providing detailed feedback about schema correctness and
 * specific error locations when validation fails.
 */
export namespace IAutoBePrismaValidation {
  /**
   * Interface representing a successful validation result.
   *
   * This interface is returned when the AutoBePrisma.IApplication structure
   * passes all validation rules including:
   *
   * - No duplicate model names across all files
   * - No duplicate field names within any model
   * - No duplicate relation names within any model
   * - All foreign key references point to existing models
   * - All field types are valid and properly configured
   * - All indexes follow the established rules (no single foreign key indexes)
   * - All naming conventions are properly applied (plural models, snake_case
   *   fields)
   * - All business constraints are satisfied
   */
  export interface ISuccess {
    /**
     * Validation success indicator.
     *
     * Always true for successful validation results. This discriminator
     * property allows TypeScript to properly narrow the union type and provides
     * runtime type checking for validation result processing.
     */
    success: true;
 
    /**
     * The validated and approved AutoBePrisma application structure.
     *
     * This contains the complete, validation-passed schema definition that can
     * be safely passed to the code generator for Prisma schema file creation.
     * All models, fields, relationships, and indexes in this structure have
     * been verified for correctness and compliance with schema rules.
     *
     * Important: This may not be identical to the original input application.
     * The validation process can apply automatic corrections to resolve
     * validation issues such as removing duplicates or fixing structural
     * problems. These corrections preserve the original business intent while
     * ensuring schema consistency and data integrity.
     */
    data: AutoBePrisma.IApplication;
  }
 
  /**
   * Interface representing a failed validation result with detailed error
   * information.
   *
   * This interface is returned when the AutoBePrisma.IApplication structure
   * contains one or more validation errors. It provides both the original
   * (potentially flawed) application structure and a comprehensive list of
   * specific errors that need to be resolved.
   *
   * The error information is structured to enable precise error location
   * identification and targeted fixes without affecting unrelated parts of the
   * schema.
   */
  export interface IFailure {
    /**
     * Validation failure indicator.
     *
     * Always false for failed validation results. This discriminator property
     * allows TypeScript to properly narrow the union type and indicates that
     * the errors array contains specific validation issues that must be
     * resolved.
     */
    success: false;
 
    /**
     * The original AutoBePrisma application structure that failed validation.
     *
     * This contains the complete schema definition as it was submitted for
     * validation, including all the elements that caused validation errors.
     * This structure serves as the baseline for error analysis and correction,
     * allowing error-fixing systems to understand the full context of the
     * schema while addressing specific validation issues.
     */
    data: AutoBePrisma.IApplication;
 
    /**
     * Array of specific validation errors found in the application structure.
     *
     * Each error provides precise location information (file path, model name,
     * field name) and detailed error descriptions to enable targeted fixes.
     * Errors are ordered by severity and location to facilitate systematic
     * resolution. The array will never be empty when success is false.
     *
     * Common error categories include:
     *
     * - Duplication errors (duplicate models, fields, relations)
     * - Reference errors (invalid foreign key targets, missing models)
     * - Type validation errors (invalid field types, constraint violations)
     * - Index configuration errors (invalid field references, forbidden single FK
     *   indexes)
     * - Naming convention violations (non-plural models, invalid field names)
     */
    errors: IError[];
  }
 
  /**
   * Interface representing a specific validation error with precise location
   * information.
   *
   * This interface provides detailed information about individual validation
   * errors, including exact location within the schema structure and
   * comprehensive error descriptions. The location information enables
   * error-fixing systems to pinpoint exactly where problems occur without
   * manual search or guesswork.
   *
   * Each error represents a specific violation of schema rules that must be
   * resolved for successful validation.
   */
  export interface IError {
    /**
     * File path where the validation error occurs.
     *
     * Specifies the exact schema file within the
     * AutoBePrisma.IApplication.files array where this error was detected. This
     * corresponds to the filename property of the IFile interface and enables
     * targeted file-level error resolution.
     *
     * Examples: "schema-01-articles.prisma", "schema-03-actors.prisma"
     *
     * This path information allows error-fixing systems to:
     *
     * - Navigate directly to the problematic file
     * - Understand cross-file reference issues
     * - Apply fixes within the correct file context
     * - Maintain proper file organization during error resolution
     */
    path: string;
 
    /**
     * Name of the model (database table) where the validation error occurs.
     *
     * Specifies the exact model within the identified file that contains the
     * validation error. This corresponds to the name property of the IModel
     * interface and enables targeted model-level error resolution.
     *
     * Examples: "shopping_customers", "bbs_articles",
     * "mv_shopping_sale_last_snapshots"
     *
     * When null, indicates file-level errors such as:
     *
     * - Duplicated file names
     * - Invalid file names
     *
     * This model information allows error-fixing systems to:
     *
     * - Navigate directly to the problematic model definition
     * - Understand model-specific constraint violations
     * - Apply fixes within the correct model context
     * - Resolve cross-model relationship issues
     */
    table: string | null;
 
    /**
     * Name of the specific field (column) where the validation error occurs.
     *
     * Specifies the exact field within the identified model that contains the
     * validation error, or null for model-level errors that don't relate to a
     * specific field. This corresponds to field names in primaryField,
     * foreignFields, or plainFields arrays of the IModel interface.
     *
     * Examples: "shopping_customer_id", "created_at", "name", null
     *
     * When null, indicates model-level errors such as:
     *
     * - Duplicate model names across files
     * - Missing primary key definitions
     * - Invalid model naming conventions
     * - Model-level constraint violations
     *
     * When string, indicates field-level errors such as:
     *
     * - Duplicate field names within the model
     * - Invalid field types or constraints
     * - Invalid foreign key configurations
     * - Field naming convention violations
     *
     * This field information allows error-fixing systems to:
     *
     * - Navigate directly to the problematic field definition
     * - Distinguish between model-level and field-level issues
     * - Apply targeted fixes without affecting other fields
     * - Resolve field-specific constraint violations
     */
    field: string | null;
 
    /**
     * Detailed human-readable description of the validation error.
     *
     * Provides comprehensive information about what validation rule was
     * violated, why it's problematic, and often hints at how to resolve the
     * issue. The message is designed to be informative enough for both
     * automated error-fixing systems and human developers to understand and
     * address the problem.
     *
     * Message format typically includes:
     *
     * - Clear description of what rule was violated
     * - Specific details about the problematic element
     * - Context about why this causes validation failure
     * - Sometimes suggestions for resolution approaches
     *
     * This message information allows error-fixing systems to:
     *
     * - Understand the exact nature of the validation failure
     * - Implement appropriate resolution strategies
     * - Provide meaningful feedback to developers
     * - Log detailed error information for debugging
     * - Make informed decisions about fix approaches
     */
    message: string;
  }
}

import { tags } from "typia";
 
/**
 * Namespace containing all interfaces for generating Prisma ORM schema through
 * code generation.
 *
 * This namespace defines the structure for converting requirements into Prisma
 * schema files, following the patterns observed in the uploaded schema files
 * where models are organized by business domains (Systematic, Actors, Sales,
 * Carts, Orders, Coupons, Coins, Inquiries, Favorites, Articles).
 *
 * @author Samchon
 */
export namespace AutoBePrisma {
  /**
   * Root interface representing the entire Prisma application schema.
   *
   * Contains multiple schema files that will be generated, typically organized
   * by business domain. Based on the uploaded schemas, applications usually
   * contain 8-10 files covering different functional areas like user
   * management, sales, orders, etc.
   */
  export interface IApplication {
    /**
     * Array of Prisma schema files to be generated.
     *
     * Each file represents a specific business domain or functional area.
     * Examples from uploaded schemas: systematic (channels/sections), actors
     * (users/customers), sales (products/snapshots), carts, orders, coupons,
     * coins (deposits/mileage), inquiries, favorites, and articles (BBS
     * system).
     */
    files: IFile[];
  }
 
  /**
   * Interface representing a single Prisma schema file within the application.
   *
   * Each file focuses on a specific business domain and contains related
   * models. File organization follows domain-driven design principles as seen
   * in the uploaded schemas.
   */
  export interface IFile {
    /**
     * Name of the schema file to be generated.
     *
     * Should follow the naming convention: "schema-{number}-{domain}.prisma"
     * Examples: "schema-02-systematic.prisma", "schema-03-actors.prisma" The
     * number indicates the dependency order for schema generation.
     */
    filename: string & tags.Pattern<"^[a-zA-Z0-9._-]+\\.prisma$">;
 
    /**
     * Business domain namespace that groups related models.
     *
     * Used in Prisma documentation comments as "@\namespace directive".
     * Examples from uploaded schemas: "Systematic", "Actors", "Sales", "Carts",
     * "Orders", "Coupons", "Coins", "Inquiries", "Favorites", "Articles"
     */
    namespace: string;
 
    /**
     * Array of Prisma models (database tables) within this domain.
     *
     * Each model represents a business entity or concept within the namespace.
     * Models can reference each other through foreign key relationships.
     */
    models: IModel[];
  }
 
  /**
   * Interface representing a single Prisma model (database table).
   *
   * Based on the uploaded schemas, models follow specific patterns:
   *
   * - Main business entities (e.g., shopping_sales, shopping_customers)
   * - Snapshot/versioning entities for audit trails (e.g.,
   *   shopping_sale_snapshots)
   * - Junction tables for M:N relationships (e.g.,
   *   shopping_cart_commodity_stocks)
   * - Materialized views for performance (prefixed with mv_)
   */
  export interface IModel {
    /**
     * Name of the Prisma model (database table name).
     *
     * Should follow snake_case convention with domain prefix. Examples:
     * "shopping_customers", "shopping_sale_snapshots", "bbs_articles"
     * Materialized views use "mv_" prefix: "mv_shopping_sale_last_snapshots"
     */
    name: string & tags.Pattern<"^[a-z][a-z0-9_]*$">;
 
    /**
     * Detailed description explaining the business purpose and usage of the
     * model.
     *
     * Should include:
     *
     * - Business context and purpose
     * - Key relationships with other models
     * - Important behavioral notes or constraints
     * - References to related entities using "{@\link ModelName}" syntax Example:
     *   "Customer information, but not a person but a **connection** basis..."
     */
    description: string;
 
    /**
     * Indicates whether this model represents a materialized view for
     * performance optimization.
     *
     * Materialized views are read-only computed tables that cache complex query
     * results. They're marked as "@\hidden" in documentation and prefixed with
     * "mv_" in naming. Examples: mv_shopping_sale_last_snapshots,
     * mv_shopping_cart_commodity_prices
     */
    material: boolean;
 
    //----
    // FIELDS
    //----
    /**
     * The primary key field of the model.
     *
     * In all uploaded schemas, primary keys are always UUID type with "@\id"
     * directive. Usually named "id" and marked with "@\db.Uuid" for PostgreSQL
     * mapping.
     */
    primaryField: IPrimaryField;
 
    /**
     * Array of foreign key fields that reference other models.
     *
     * These establish relationships between models and include Prisma relation
     * directives. Can be nullable (optional relationships) or required
     * (mandatory relationships). May have unique constraints for 1:1
     * relationships.
     */
    foreignFields: IForeignField[];
 
    /**
     * Array of regular data fields that don't reference other models.
     *
     * Include business data like names, descriptions, timestamps, flags,
     * amounts, etc. Common patterns: created_at, updated_at, deleted_at for
     * soft deletion and auditing.
     */
    plainFields: IPlainField[];
 
    //----
    // INDEXES
    //----
    /**
     * Array of unique indexes for enforcing data integrity constraints.
     *
     * Ensure uniqueness across single or multiple columns. Examples: unique
     * email addresses, unique codes within a channel, unique combinations like
     * (channel_id, nickname).
     */
    uniqueIndexes: IUniqueIndex[];
 
    /**
     * Array of regular indexes for query performance optimization.
     *
     * Speed up common query patterns like filtering by foreign keys, date
     * ranges, or frequently searched fields. Examples: indexes on created_at,
     * foreign key fields, search fields.
     */
    plainIndexes: IPlainIndex[];
 
    /**
     * Array of GIN (Generalized Inverted Index) indexes for full-text search.
     *
     * Used specifically for PostgreSQL text search capabilities using trigram
     * operations. Applied to text fields that need fuzzy matching or partial
     * text search. Examples: searching names, nicknames, titles, content
     * bodies.
     */
    ginIndexes: IGinIndex[];
  }
 
  /**
   * Interface representing the primary key field of a Prisma model.
   *
   * All models in the uploaded schemas use UUID as primary key for better
   * distributed system compatibility and security (no sequential ID exposure).
   */
  export interface IPrimaryField {
    /**
     * Name of the primary key field.
     *
     * Consistently named "id" across all models in the uploaded schemas.
     * Represents the unique identifier for each record in the table.
     */
    name: string & tags.Pattern<"^[a-z][a-z0-9_]*$">;
 
    /**
     * Data type of the primary key field.
     *
     * Always "uuid" in the uploaded schemas for better distributed system
     * support and to avoid exposing sequential IDs that could reveal business
     * information.
     */
    type: "uuid";
 
    /**
     * Description of the primary key field's purpose.
     *
     * Standard description is "Primary Key." across all models. Serves as the
     * unique identifier for the model instance.
     */
    description: string;
  }
 
  /**
   * Interface representing a foreign key field that establishes relationships
   * between models.
   *
   * Foreign keys create associations between models, enabling relational data
   * modeling. They can represent 1:1, 1:N, or participate in M:N relationships
   * through junction tables.
   */
  export interface IForeignField {
    /**
     * Name of the foreign key field.
     *
     * Follows convention: "{target_model_name_without_prefix}_id" Examples:
     * "shopping_customer_id", "bbs_article_id", "attachment_file_id" For
     * self-references: "parent_id" (e.g., in hierarchical structures)
     */
    name: string & tags.Pattern<"^[a-z][a-z0-9_]*$">;
 
    /**
     * Data type of the foreign key field.
     *
     * Always "uuid" to match the primary key type of referenced models. Ensures
     * referential integrity and consistency across the schema.
     */
    type: "uuid";
 
    /**
     * Description explaining the purpose and target of this foreign key
     * relationship.
     *
     * Should reference the target model using format: "Target model's {@\link
     * ModelName.id}" Examples: "Belonged customer's {@\link
     * shopping_customers.id}" May include additional context about the
     * relationship's business meaning.
     */
    description: string;
 
    /**
     * Prisma relation configuration defining the association details.
     *
     * Specifies how this foreign key connects to the target model, including
     * relation name, target model, and target field.
     */
    relation: {
      /**
       * Name of the relation property in the Prisma model.
       *
       * Used to access the related model instance. Usually a descriptive name
       * of the relationship. Examples: "customer", "channel", "parent",
       * "snapshot"
       */
      name: string & tags.Pattern<"^[a-zA-Z_][a-zA-Z0-9_]*$">;
 
      /**
       * Name of the target model being referenced.
       *
       * Must match exactly with an existing model name in the schema. Examples:
       * "shopping_customers", "shopping_channels", "bbs_articles"
       */
      targetModel: string;
 
      /** @internal */
      mappingName?: string;
    };
 
    /**
     * Whether this foreign key has a unique constraint.
     *
     * True: Creates a 1:1 relationship (e.g., user profile, order publish
     * details) false: Allows 1:N relationship (e.g., customer to multiple
     * orders) Used for enforcing business rules about relationship
     * cardinality.
     */
    unique: boolean;
 
    /**
     * Whether this foreign key can be null (optional relationship).
     *
     * True: Relationship is optional, foreign key can be null false:
     * Relationship is required, foreign key cannot be null Reflects business
     * rules about mandatory vs optional associations.
     */
    nullable: boolean;
  }
 
  /**
   * Interface representing a regular data field that stores business
   * information.
   *
   * These fields contain the actual business data like names, amounts,
   * timestamps, flags, descriptions, and other domain-specific information.
   */
  export interface IPlainField {
    /**
     * Name of the field in the database table.
     *
     * Should use snake_case convention. Common patterns from uploaded schemas:
     *
     * - Timestamps: created_at, updated_at, deleted_at, opened_at, closed_at
     * - Identifiers: code, name, nickname, title
     * - Business data: value, quantity, price, volume, balance
     * - Flags: primary, required, exclusive, secret, multiplicative
     */
    name: string & tags.Pattern<"^[a-z][a-z0-9_]*$">;
 
    /**
     * Data type of the field for Prisma schema generation.
     *
     * Maps to appropriate Prisma/PostgreSQL types:
     *
     * - Boolean: Boolean flags and yes/no values
     * - Int: Integer numbers, quantities, sequences
     * - Double: Decimal numbers, prices, monetary values, percentages
     * - String: Text data, names, descriptions, codes
     * - Uri: URL/URI fields for links and references
     * - Uuid: UUID fields (for non-foreign-key UUIDs)
     * - Date: Date-only values (rare, mostly for business dates)
     * - Datetime: Timestamp fields with date and time
     */
    type: "boolean" | "int" | "double" | "string" | "uri" | "uuid" | "datetime";
 
    /**
     * Description explaining the business purpose and usage of this field.
     *
     * Should clearly explain:
     *
     * - What business concept this field represents
     * - Valid values or constraints if applicable
     * - How it relates to business processes
     * - Any special behavioral notes Example: "Amount of cash payment." or
     *   "Whether the unit is required or not."
     */
    description: string;
 
    /**
     * Whether this field can contain null values.
     *
     * True: Field is optional and can be null (e.g., middle name, description)
     * false: Field is required and cannot be null (e.g., creation timestamp,
     * name) Reflects business rules about mandatory vs optional data.
     */
    nullable: boolean;
  }
 
  /**
   * Interface representing a unique index constraint on one or more fields.
   *
   * Unique indexes enforce data integrity by ensuring no duplicate values exist
   * for the specified field combination. Essential for business rules that
   * require uniqueness like email addresses, codes, or composite keys.
   */
  export interface IUniqueIndex {
    /**
     * Array of field names that together form the unique constraint.
     *
     * Can be single field (e.g., ["email"]) or composite (e.g., ["channel_id",
     * "code"]). All field names must exist in the model. Order matters for
     * composite indexes. Examples: ["code"], ["shopping_channel_id",
     * "nickname"], ["email"]
     */
    fieldNames: string[] & tags.MinItems<1> & tags.UniqueItems;
 
    /**
     * Explicit marker indicating this is a unique index.
     *
     * Always true to distinguish from regular indexes. Used by code generator
     * to emit "@@unique" directive in Prisma schema instead of "@@index".
     */
    unique: true;
  }
 
  /**
   * Interface representing a regular (non-unique) index for query performance.
   *
   * Regular indexes speed up database queries by creating optimized data
   * structures for common search patterns. Essential for foreign keys, date
   * ranges, and frequently filtered fields.
   */
  export interface IPlainIndex {
    /**
     * Array of field names to include in the performance index.
     *
     * Can be single field (e.g., ["created_at"]) or composite (e.g.,
     * ["customer_id", "created_at"]). All field names must exist in the model.
     * Order matters for composite indexes and should match common query
     * patterns. Examples: ["created_at"], ["shopping_customer_id",
     * "created_at"], ["ip"]
     */
    fieldNames: string[] & tags.MinItems<1> & tags.UniqueItems;
  }
 
  /**
   * Interface representing a GIN (Generalized Inverted Index) for full-text
   * search.
   *
   * GIN indexes enable advanced PostgreSQL text search capabilities including
   * fuzzy matching and partial text search using trigram operations. Essential
   * for user-facing search features on text content.
   */
  export interface IGinIndex {
    /**
     * Name of the text field to index for full-text search capabilities.
     *
     * Must be a string field in the model that contains searchable text.
     * Examples from uploaded schemas: "nickname", "title", "body", "name" Used
     * with PostgreSQL gin_trgm_ops for trigram-based fuzzy text search.
     */
    fieldName: string;
  }
}

/**
 * Union type representing the result of type validation
 *
 * This is the return type of {@link typia.validate} functions, returning
 * {@link IValidation.ISuccess} on validation success and
 * {@link IValidation.IFailure} on validation failure. When validation fails, it
 * provides detailed, granular error information that precisely describes what
 * went wrong, where it went wrong, and what was expected.
 *
 * This comprehensive error reporting makes `IValidation` particularly valuable
 * for AI function calling scenarios, where Large Language Models (LLMs) need
 * specific feedback to correct their parameter generation. The detailed error
 * information is used by ILlmFunction.validate() to provide validation feedback
 * to AI agents, enabling iterative correction and improvement of function
 * calling accuracy.
 *
 * This type uses the Discriminated Union pattern, allowing type specification
 * through the success property:
 *
 * ```typescript
 * const result = typia.validate<string>(input);
 * if (result.success) {
 *   // IValidation.ISuccess<string> type
 *   console.log(result.data); // validated data accessible
 * } else {
 *   // IValidation.IFailure type
 *   console.log(result.errors); // detailed error information accessible
 * }
 * ```
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @template T The type to validate
 */
export type IValidation<T = unknown> =
  | IValidation.ISuccess<T>
  | IValidation.IFailure;
 
export namespace IValidation {
  /**
   * Interface returned when type validation succeeds
   *
   * Returned when the input value perfectly conforms to the specified type T.
   * Since success is true, TypeScript's type guard allows safe access to the
   * validated data through the data property.
   *
   * @template T The validated type
   */
  export interface ISuccess<T = unknown> {
    /** Indicates validation success */
    success: true;
 
    /** The validated data of type T */
    data: T;
  }
 
  /**
   * Interface returned when type validation fails
   *
   * Returned when the input value does not conform to the expected type.
   * Contains comprehensive error information designed to be easily understood
   * by both humans and AI systems. Each error in the errors array provides
   * precise details about validation failures, including the exact path to the
   * problematic property, what type was expected, and what value was actually
   * provided.
   *
   * This detailed error structure is specifically optimized for AI function
   * calling validation feedback. When LLMs make type errors during function
   * calling, these granular error reports enable the AI to understand exactly
   * what went wrong and how to fix it, improving success rates in subsequent
   * attempts.
   *
   * Example error scenarios:
   *
   * - Type mismatch: expected "string" but got number 5
   * - Format violation: expected "string & Format<'uuid'>" but got
   *   "invalid-format"
   * - Missing properties: expected "required property 'name'" but got undefined
   * - Array type errors: expected "Array<string>" but got single string value
   *
   * The errors are used by ILlmFunction.validate() to provide structured
   * feedback to AI agents, enabling them to correct their parameter generation
   * and achieve improved function calling accuracy.
   */
  export interface IFailure {
    /** Indicates validation failure */
    success: false;
 
    /** The original input data that failed validation */
    data: unknown;
 
    /** Array of detailed validation errors */
    errors: IError[];
  }
 
  /**
   * Detailed information about a specific validation error
   *
   * Each error provides granular, actionable information about validation
   * failures, designed to be immediately useful for both human developers and
   * AI systems. The error structure follows a consistent format that enables
   * precise identification and correction of type mismatches.
   *
   * This error format is particularly valuable for AI function calling
   * scenarios, where LLMs need to understand exactly what went wrong to
   * generate correct parameters. The combination of path, expected type, and
   * actual value provides the AI with sufficient context to make accurate
   * corrections, which is why ILlmFunction.validate() can achieve such high
   * success rates in validation feedback loops.
   *
   * Real-world examples from AI function calling:
   *
   *     {
   *       path: "input.member.age",
   *       expected: "number & Format<'uint32'>",
   *       value: 20.75  // AI provided float instead of uint32
   *     }
   *
   *     {
   *       path: "input.categories",
   *       expected: "Array<string>",
   *       value: "technology"  // AI provided string instead of array
   *     }
   *
   *     {
   *       path: "input.id",
   *       expected: "string & Format<'uuid'>",
   *       value: "invalid-uuid-format"  // AI provided malformed UUID
   *     }
   */
  export interface IError {
    /**
     * The path to the property that failed validation (e.g.,
     * "input.member.age")
     */
    path: string;
 
    /** Description of the expected type or format */
    expected: string;
 
    /** The actual value that caused the validation failure */
    value: any;
  }
}

/**
 * OpenAPI Generative TypeScript Interface
 *
 * `AutoBeOpenApi` is a TypeScript interface for the OpenAPI Generative.
 *
 * `AutoBeOpenApi` follows the OpenAPI v3.1 specification, but is streamlined to
 * remove ambiguous and duplicated expressions for improved clarity, AI
 * generation capabilities, and developer understanding.
 *
 * @author Samchon
 */
export namespace AutoBeOpenApi {
  /* -----------------------------------------------------------
    DOCUMENT
  ----------------------------------------------------------- */
  /**
   * Document of the Restful API operations.
   *
   * This interface serves as the root document for defining Restful API
   * {@link operations} and {@link components}. It corresponds to the top-level
   * structure of an OpenAPI specification document, containing all API
   * operations and reusable components.
   *
   * This simplified version focuses only on the operations and components,
   * omitting other OpenAPI elements like info, servers, security schemes, etc.
   * to keep the structure concise for AI-based code generation.
   *
   * IMPORTANT: When creating this document, you MUST ensure that:
   *
   * 1. The API operations and component schemas directly correspond to the Prisma
   *    DB schema
   * 2. All entity types and their properties reference and incorporate the
   *    description comments from the related Prisma DB schema tables and
   *    columns
   * 3. Descriptions are detailed and organized into multiple paragraphs
   * 4. The API fully represents all entities and relationships defined in the
   *    Prisma schema
   * 5. EVERY SINGLE TABLE in the Prisma DB schema MUST have corresponding API
   *    operations for CRUD actions (Create, Read, Update, Delete) as
   *    applicable
   * 6. NO TABLE should be omitted from the API design - all tables require API
   *    coverage
   *
   * ## Type Naming Conventions
   *
   * When defining component schemas, follow these naming conventions for
   * consistency:
   *
   * - **Main Entity Types**: Use `IEntityName` format for main entity with
   *   detailed information (e.g., `IShoppingSale`)
   *
   *   - These MUST directly correspond to entity tables in the Prisma schema
   *   - Their descriptions MUST incorporate the table description comments from the
   *       Prisma schema
   *   - Each property MUST reference the corresponding column description from the
   *       Prisma schema
   *   - Entity types should represent the full, detailed version of domain entities
   * - **Related Operation Types**: Use `IEntityName.IOperation` format with these
   *   common suffixes:
   *
   *   - `IEntityName.ICreate`: Request body for creation operations (POST)
   *
   *       - Should include all required fields from the Prisma schema entity
   *   - `IEntityName.IUpdate`: Request body for update operations (PUT)
   *
   *       - Should include updatable fields as defined in the Prisma schema
   *   - `IEntityName.ISummary`: Simplified response version with essential
   *       properties
   *   - `IEntityName.IRequest`: Request parameters for list operations (often with
   *       search/pagination)
   *   - `IEntityName.IInvert`: Alternative view of an entity from a different
   *       perspective
   *   - `IPageIEntityName`: Paginated results container with `pagination` and
   *       `data` properties
   *
   * These consistent naming patterns create a predictable and self-documenting
   * API that accurately reflects the underlying Prisma schema, making it easier
   * for developers to understand the purpose of each schema and its
   * relationship to the database model.
   */
  export interface IDocument {
    /**
     * List of API operations.
     *
     * This array contains all the API endpoints with their HTTP methods,
     * descriptions, parameters, request/response structures, etc. Each
     * operation corresponds to an entry in the paths section of an OpenAPI
     * document.
     *
     * CRITICAL: This array MUST include operations for EVERY TABLE defined in
     * the Prisma schema. The AI generation MUST NOT skip or omit any tables
     * when creating operations. The operations array MUST be complete and
     * exhaustive, covering all database entities without exception.
     *
     * IMPORTANT: For each API operation, ensure that:
     *
     * 1. EVERY independent entity table in the Prisma schema has corresponding API
     *    operations for basic CRUD functions (at minimum)
     * 2. ALL TABLES from the Prisma schema MUST have at least one API operation,
     *    no matter how many tables are in the schema
     * 3. DO NOT STOP generating API operations until ALL tables have been
     *    addressed
     * 4. The description field refers to and incorporates the description comments
     *    from the related DB schema tables and columns
     * 5. The description must be VERY detailed and organized into MULTIPLE
     *    PARAGRAPHS separated by line breaks, not just a single paragraph
     * 6. The description should explain the purpose, functionality, and any
     *    relationships to other entities in the database schema
     *
     * Note that, combination of {@link AutoBeOpenApi.IOperation.path} and
     * {@link AutoBeOpenApi.IOperation.method} must be unique.
     *
     * Also, never forget any specification that is listed on the requirement
     * analysis report and DB design documents. Every feature must be
     * implemented in the API operations.
     *
     * @minItems 1
     */
    operations: AutoBeOpenApi.IOperation[];
 
    /**
     * Reusable components of the API operations.
     *
     * This contains schemas, parameters, responses, and other reusable elements
     * referenced throughout the API operations. It corresponds to the
     * components section in an OpenAPI document.
     *
     * CRITICAL: Components MUST include type definitions for EVERY TABLE in the
     * Prisma schema. The AI generation process MUST create schema components
     * for ALL database entities without exception, regardless of how many
     * tables are in the database.
     *
     * IMPORTANT: For all component types and their properties:
     *
     * 1. EVERY component MUST have a detailed description that references the
     *    corresponding Prisma DB schema table's description comments
     * 2. EACH property within component types MUST have detailed descriptions that
     *    reference the corresponding column description comments in the Prisma
     *    DB schema
     * 3. All descriptions MUST be organized into MULTIPLE PARAGRAPHS (separated by
     *    line breaks) based on different aspects of the entity
     * 4. Descriptions should be comprehensive enough that anyone who reads them
     *    can understand the purpose, functionality, and relationships of the
     *    type
     * 5. ALL TABLES from the Prisma schema MUST have corresponding schema
     *    components, no matter how many tables are in the schema
     *
     * All request and response bodies must reference named types defined in
     * this components section. This ensures consistency and reusability across
     * the API.
     *
     * ## Type Naming Conventions in Components
     *
     * When defining schema components, follow these standardized naming
     * patterns for consistency and clarity:
     *
     * ### Main Entity Types
     *
     * - `IEntityName`
     *
     *   - Primary entity objects (e.g., `IShoppingSale`, `IShoppingOrder`)
     *   - These represent the full, detailed version of domain entities
     *
     * ### Operation-Specific Types
     *
     * - `IEntityName.ICreate`
     *
     *   - Request body schemas for creation operations (POST)
     *   - Contains all fields needed to create a new entity
     * - `IEntityName.IUpdate`
     *
     *   - Request body schemas for update operations (PUT)
     *   - Contains fields that can be modified on an existing entity
     * - `IEntityName.IRequest`
     *
     *   - Parameters for search/filter/pagination in list operations
     *   - Often contains `search`, `sort`, `page`, and `limit` properties
     *
     * ### View Types
     *
     * - `IEntityName.ISummary`
     *
     *   - Simplified view of entities for list operations
     *   - Contains essential properties only, omitting detailed nested objects
     * - `IEntityName.IAbridge`: Intermediate view with more details than Summary
     *   but less than full entity
     * - `IEntityName.IInvert`: Alternative representation of an entity from a
     *   different perspective
     *
     * ### Container Types
     *
     * - `IPageIEntityName`
     *
     *   - Paginated results container
     *   - Usually contains `pagination` and `data` properties
     *
     * These naming conventions create a self-documenting API where the purpose
     * of each schema is immediately clear from its name. This helps both
     * developers and AI tools understand and maintain the API structure.
     */
    components: AutoBeOpenApi.IComponents;
  }
 
  /**
   * Operation of the Restful API.
   *
   * This interface defines a single API endpoint with its HTTP {@link method},
   * {@link path}, {@link parameters path parameters},
   * {@link requestBody request body}, and {@link responseBody} structure. It
   * corresponds to an individual operation in the paths section of an OpenAPI
   * document.
   *
   * Each operation requires a detailed explanation of its purpose through the
   * reason and description fields, making it clear why the API was designed and
   * how it should be used.
   *
   * All request bodies and responses for this operation must be object types
   * and must reference named types defined in the components section. The
   * content-type is always `application/json`. For file upload/download
   * operations, use `string & tags.Format<"uri">` in the appropriate schema
   * instead of binary data formats.
   *
   * In OpenAPI, this might represent:
   *
   * ```json
   * {
   *   "/shoppings/customers/orders": {
   *     "post": {
   *       "description": "Create a new order application from shopping cart...",
   *       "parameters": [...],
   *       "requestBody": {...},
   *       "responses": {...}
   *     }
   *   }
   * }
   * ```
   */
  export interface IOperation extends IEndpoint {
    /**
     * Specification of the API operation.
     *
     * Before defining the API operation interface, please describe what you're
     * planning to write in this `specification` field.
     *
     * The specification must be fully detailed and clear, so that anyone can
     * understand the purpose and functionality of the API operation and its
     * related components (e.g., {@link path}, {@link parameters},
     * {@link requestBody}).
     *
     * IMPORTANT: The specification MUST identify which Prisma DB table this
     * operation is associated with, helping ensure complete coverage of all
     * database entities.
     */
    specification: string;
 
    /**
     * Detailed description about the API operation.
     *
     * IMPORTANT: This field MUST be extensively detailed and MUST reference the
     * description comments from the related Prisma DB schema tables and
     * columns. The description should be organized into MULTIPLE PARAGRAPHS
     * separated by line breaks to improve readability and comprehension.
     *
     * For example, include separate paragraphs for:
     *
     * - The purpose and overview of the API operation
     * - Security considerations and user permissions
     * - Relationship to underlying database entities
     * - Validation rules and business logic
     * - Related API operations that might be used together with this one
     * - Expected behavior and error handling
     *
     * When writing the description, be sure to incorporate the corresponding DB
     * schema's description comments, matching the level of detail and style of
     * those comments. This ensures consistency between the API documentation
     * and database structure.
     *
     * If there's a dependency to other APIs, please describe the dependency API
     * operation in this field with detailed reason. For example, if this API
     * operation needs a pre-execution of other API operation, it must be
     * explicitly described.
     *
     * - `GET /shoppings/customers/sales` must be pre-executed to get entire list
     *   of summarized sales. Detailed sale information would be obtained by
     *   specifying the sale ID in the path parameter.
     *
     * > MUST be written in English. Never use other languages.
     */
    description: string;
 
    /**
     * Short summary of the API operation.
     *
     * This should be a concise description of the API operation, typically one
     * sentence long. It should provide a quick overview of what the API does
     * without going into too much detail.
     *
     * This summary will be used in the OpenAPI documentation to give users a
     * quick understanding of the API operation's purpose.
     *
     * IMPORTANT: The summary should clearly indicate which Prisma DB table this
     * operation relates to, helping to ensure all tables have API coverage.
     *
     * > MUST be written in English. Never use other languages
     */
    summary: string;
 
    /**
     * List of path parameters.
     *
     * Note that, the {@link AutoBeOpenApi.IParameter.name identifier name} of
     * path parameter must be corresponded to the
     * {@link path API operation path}.
     *
     * For example, if there's an API operation which has {@link path} of
     * `/shoppings/customers/sales/{saleId}/questions/${questionId}/comments/${commentId}`,
     * its list of {@link AutoBeOpenApi.IParameter.name path parameters} must be
     * like:
     *
     * - `saleId`
     * - `questionId`
     * - `commentId`
     */
    parameters: AutoBeOpenApi.IParameter[];
 
    /**
     * Request body of the API operation.
     *
     * Defines the payload structure for the request. Contains a description and
     * schema reference to define the expected input data.
     *
     * Should be `null` for operations that don't require a request body, such
     * as most "get" operations.
     */
    requestBody: AutoBeOpenApi.IRequestBody | null;
 
    /**
     * Response body of the API operation.
     *
     * Defines the structure of the successful response data. Contains a
     * description and schema reference for the returned data.
     *
     * Should be null for operations that don't return any data.
     */
    responseBody: AutoBeOpenApi.IResponseBody | null;
  }
 
  /**
   * Path parameter information for API routes.
   *
   * This interface defines a path parameter that appears in the URL of an API
   * endpoint. Path parameters are enclosed in curly braces in the
   * {@link AutoBeOpenApi.IOperation.path operation path} and must be defined
   * with their types and descriptions.
   *
   * For example, if API operation path is
   * `/shoppings/customers/sales/{saleId}/questions/${questionId}/comments/${commentId}`,
   * the path parameters should be like below:
   *
   * ```json
   * {
   *   "path": "/shoppings/customers/sales/{saleId}/questions/${questionId}/comments/${commentId}",
   *   "method": "get",
   *   "parameters": [
   *     {
   *       "name": "saleId",
   *       "in": "path",
   *       "schema": { "type": "string", "format": "uuid" },
   *       "description": "Target sale's ID"
   *     },
   *     {
   *       "name": "questionId",
   *       "in": "path",
   *       "schema": { "type": "string", "format": "uuid" },
   *       "description": "Target question's ID"
   *     },
   *     {
   *       "name": "commentId",
   *       "in": "path",
   *       "schema": { "type": "string", "format": "uuid" },
   *       "description": "Target comment's ID"
   *     }
   *   ]
   * }
   * ```
   */
  export interface IParameter {
    /**
     * Identifier name of the path parameter.
     *
     * This name must match exactly with the parameter name in the route path.
     * It must be corresponded to the
     * {@link AutoBeOpenApi.IOperation.path API operation path}.
     */
    name: string;
 
    /**
     * Description about the path parameter.
     *
     * Make short, concise and clear description about the path parameter.
     *
     * > MUST be written in English. Never use other languages.
     */
    description: string;
 
    /**
     * Type schema of the path parameter.
     *
     * Path parameters are typically primitive types like
     * {@link AutoBeOpenApi.IJsonSchema.IString strings},
     * {@link AutoBeOpenApi.IJsonSchema.IInteger integers},
     * {@link AutoBeOpenApi.IJsonSchema.INumber numbers}.
     *
     * If you need other types, please use request body instead with object type
     * encapsulation.
     */
    schema:
      | AutoBeOpenApi.IJsonSchema.IInteger
      | AutoBeOpenApi.IJsonSchema.INumber
      | AutoBeOpenApi.IJsonSchema.IString;
  }
 
  /**
   * Request body information of OpenAPI operation.
   *
   * This interface defines the structure for request bodies in API routes. It
   * corresponds to the requestBody section in OpenAPI specifications, providing
   * both a description and schema reference for the request payload.
   *
   * The content-type for all request bodies is always `application/json`. Even
   * when file uploading is required, don't use `multipart/form-data` or
   * `application/x-www-form-urlencoded` content types. Instead, just define an
   * URI string property in the request body schema.
   *
   * Note that, all body schemas must be transformable to a
   * {@link AutoBeOpenApi.IJsonSchema.IReference reference} type defined in the
   * {@link AutoBeOpenApi.IComponents.schemas components section} as an
   * {@link AutoBeOpenApi.IJsonSchema.IObject object} type.
   *
   * In OpenAPI, this might represent:
   *
   * ```json
   * {
   *   "requestBody": {
   *     "description": "Creation info of the order",
   *     "content": {
   *       "application/json": {
   *         "schema": {
   *           "$ref": "#/components/schemas/IShoppingOrder.ICreate"
   *         }
   *       }
   *     }
   *   }
   * }
   * ```
   */
  export interface IRequestBody {
    /**
     * Description about the request body.
     *
     * Make short, concise and clear description about the request body.
     *
     * > MUST be written in English. Never use other languages.
     */
    description: string;
 
    /**
     * Request body type name.
     *
     * This specifies the data structure expected in the request body, that will
     * be transformed to {@link AutoBeOpenApi.IJsonSchema.IReference reference}
     * type in the {@link AutoBeOpenApi.IComponents.schemas components section}
     * as an {@link AutoBeOpenApi.IJsonSchema.Object object} type.
     *
     * Here is the naming convention for the request body type:
     *
     * - `IEntityName.ICreate`: Request body for creation operations (POST)
     * - `IEntityName.IUpdate`: Request body for update operations (PUT)
     * - `IEntityName.IRequest`: Request parameters for list operations (often
     *   with search/pagination)
     *
     * What you write:
     *
     * ```json
     * {
     *   "typeName": "IShoppingOrder.ICreate"
     * }
     * ```
     *
     * Transformed to:
     *
     * ```json
     * {
     *   "schema": {
     *     "$ref": "#/components/schemas/IShoppingOrder.ICreate"
     *   }
     * }
     * ```
     */
    typeName: string;
  }
 
  /**
   * Response body information for OpenAPI operation.
   *
   * This interface defines the structure of a successful response from an API
   * operation. It provides a description of the response and a schema reference
   * to define the returned data structure.
   *
   * The content-type for all responses is always `application/json`. Even when
   * file downloading is required, don't use `application/octet-stream` or
   * `multipart/form-data` content types. Instead, just define an URI string
   * property in the response body schema.
   *
   * In OpenAPI, this might represent:
   *
   * ```json
   * {
   *   "responses": {
   *     "200": {
   *       "description": "Order information",
   *       "content": {
   *         "application/json": {
   *           "schema": { "$ref": "#/components/schemas/IShoppingOrder" }
   *         }
   *       }
   *     }
   *   }
   * }
   * ```
   */
  export interface IResponseBody {
    /**
     * Description about the response body.
     *
     * Make short, concise and clear description about the response body.
     *
     * > MUST be written in English. Never use other languages.
     */
    description: string;
 
    /**
     * Response body's data type.
     *
     * Specifies the structure of the returned data (response body), that will
     * be transformed to {@link AutoBeOpenApi.IJsonSchema.IReference} type in the
     * {@link AutoBeOpenApi.IComponents.schemas components section} as an
     * {@link AutoBeOpenApi.IJsonSchema.IObject object} type.
     *
     * Here is the naming convention for the response body type:
     *
     * - `IEntityName`: Main entity with detailed information (e.g.,
     *   `IShoppingSale`)
     * - `IEntityName.ISummary`: Simplified response version with essential
     *   properties
     * - `IEntityName.IInvert`: Alternative view of an entity from a different
     *   perspective
     * - `IPageIEntityName`: Paginated results container with `pagination` and
     *   `data` properties
     *
     * What you write:
     *
     * ```json
     * {
     *   "typeName": "IShoppingOrder"
     * }
     * ```
     *
     * Transformed to:
     *
     * ```json
     * {
     *   "schema": {
     *     "$ref": "#/components/schemas/IShoppingOrder"
     *   }
     * }
     * ```
     */
    typeName: string;
  }
 
  /* -----------------------------------------------------------
    JSON SCHEMA
  ----------------------------------------------------------- */
  /**
   * Reusable components in OpenAPI.
   *
   * A storage of reusable components in OpenAPI document.
   *
   * In other words, it is a storage of named DTO schemas and security schemes.
   */
  export interface IComponents {
    /**
     * An object to hold reusable DTO schemas.
     *
     * In other words, a collection of named JSON schemas.
     *
     * IMPORTANT: For each schema in this collection:
     *
     * 1. EVERY schema MUST have a detailed description that references and aligns
     *    with the description comments from the corresponding Prisma DB schema
     *    tables
     * 2. EACH property within the schema MUST have detailed descriptions that
     *    reference and align with the description comments from the
     *    corresponding DB schema columns
     * 3. All descriptions MUST be organized into MULTIPLE PARAGRAPHS (separated by
     *    line breaks) when appropriate
     * 4. Descriptions should be comprehensive enough that anyone reading them can
     *    understand the purpose, functionality, and constraints of each type
     *    and property without needing to reference other documentation
     */
    schemas: Record<string, IJsonSchemaDescriptive>;
 
    /** Whether includes `Authorization` header or not. */
    authorization?: "header" | undefined;
  }
 
  /**
   * Type schema info.
   *
   * `AutoBeOpenApi.IJsonSchema` is a type schema info of the OpenAPI
   * Generative.
   *
   * `AutoBeOpenApi.IJsonSchema` basically follows the JSON schema specification
   * of OpenAPI v3.1, but a little bit shrunk to remove ambiguous and duplicated
   * expressions of OpenAPI v3.1 for the convenience, clarity, and AI
   * generation.
   */
  export type IJsonSchema =
    | IJsonSchema.IConstant
    | IJsonSchema.IBoolean
    | IJsonSchema.IInteger
    | IJsonSchema.INumber
    | IJsonSchema.IString
    | IJsonSchema.IArray
    | IJsonSchema.IObject
    | IJsonSchema.IReference;
  export namespace IJsonSchema {
    /** Constant value type. */
    export interface IConstant {
      /** The constant value. */
      const: boolean | number | string;
    }
 
    /** Boolean type info. */
    export interface IBoolean extends ISignificant<"boolean"> {}
 
    /** Integer type info. */
    export interface IInteger extends ISignificant<"integer"> {
      /**
       * Minimum value restriction.
       *
       * @type int64
       */
      minimum?: number;
 
      /**
       * Maximum value restriction.
       *
       * @type int64
       */
      maximum?: number;
 
      /** Exclusive minimum value restriction. */
      exclusiveMinimum?: number;
 
      /** Exclusive maximum value restriction. */
      exclusiveMaximum?: number;
 
      /**
       * Multiple of value restriction.
       *
       * @type uint64
       * @exclusiveMinimum 0
       */
      multipleOf?: number;
    }
 
    /** Number (double) type info. */
    export interface INumber extends ISignificant<"number"> {
      /** Minimum value restriction. */
      minimum?: number;
 
      /** Maximum value restriction. */
      maximum?: number;
 
      /** Exclusive minimum value restriction. */
      exclusiveMinimum?: number;
 
      /** Exclusive maximum value restriction. */
      exclusiveMaximum?: number;
 
      /**
       * Multiple of value restriction.
       *
       * @exclusiveMinimum 0
       */
      multipleOf?: number;
    }
 
    /** String type info. */
    export interface IString extends ISignificant<"string"> {
      /** Format restriction. */
      format?:
        | "binary"
        | "byte"
        | "password"
        | "regex"
        | "uuid"
        | "email"
        | "hostname"
        | "idn-email"
        | "idn-hostname"
        | "iri"
        | "iri-reference"
        | "ipv4"
        | "ipv6"
        | "uri"
        | "uri-reference"
        | "uri-template"
        | "url"
        | "date-time"
        | "date"
        | "time"
        | "duration"
        | "json-pointer"
        | "relative-json-pointer"
        | (string & {});
 
      /** Pattern restriction. */
      pattern?: string;
 
      /** Content media type restriction. */
      contentMediaType?: string;
 
      /**
       * Minimum length restriction.
       *
       * @type uint64
       */
      minLength?: number;
 
      /**
       * Maximum length restriction.
       *
       * @type uint64
       */
      maxLength?: number;
    }
 
    /** Array type info. */
    export interface IArray extends ISignificant<"array"> {
      /**
       * Items type info.
       *
       * The `items` means the type of the array elements. In other words, it is
       * the type schema info of the `T` in the TypeScript array type
       * `Array<T>`.
       */
      items: IJsonSchema;
 
      /**
       * Unique items restriction.
       *
       * If this property value is `true`, target array must have unique items.
       */
      uniqueItems?: boolean;
 
      /**
       * Minimum items restriction.
       *
       * Restriction of minimum number of items in the array.
       *
       * @type uint64
       */
      minItems?: number;
 
      /**
       * Maximum items restriction.
       *
       * Restriction of maximum number of items in the array.
       *
       * @type uint64
       */
      maxItems?: number;
    }
 
    /** Object type info. */
    export interface IObject extends ISignificant<"object"> {
      /**
       * Properties of the object.
       *
       * The `properties` means a list of key-value pairs of the object's
       * regular properties. The key is the name of the regular property, and
       * the value is the type schema info.
       *
       * IMPORTANT: Each property in this object MUST have a detailed
       * description that references and aligns with the description comments
       * from the corresponding Prisma DB schema column.
       *
       * If you need additional properties that is represented by dynamic key,
       * you can use the {@link additionalProperties} instead.
       */
      properties: Record<string, IJsonSchemaDescriptive>;
 
      /**
       * Additional properties' info.
       *
       * The `additionalProperties` means the type schema info of the additional
       * properties that are not listed in the {@link properties}.
       *
       * If the value is `false`, it means that the additional properties are
       * not specified. Otherwise, if the value is {@link IJsonSchema} type, it
       * means that the additional properties must follow the type schema info.
       *
       * - `false`: No additional properties
       * - `IJsonSchema`: `Record<string, T>`
       */
      additionalProperties?: false | IJsonSchema;
 
      /**
       * List of key values of the required properties.
       *
       * The `required` means a list of the key values of the required
       * {@link properties}. If some property key is not listed in the `required`
       * list, it means that property is optional. Otherwise some property key
       * exists in the `required` list, it means that the property must be
       * filled.
       *
       * Below is an example of the {@link properties} and `required`.
       *
       * ```typescript
       * interface SomeObject {
       *   id: string;
       *   email: string;
       *   name?: string;
       * }
       * ```
       *
       * As you can see, `id` and `email` {@link properties} are {@link required},
       * so that they are listed in the `required` list.
       *
       * ```json
       * {
       *   "type": "object",
       *   "properties": {
       *     "id": { "type": "string" },
       *     "email": { "type": "string" },
       *     "name": { "type": "string" }
       *   },
       *   "required": ["id", "email"]
       * }
       * ```
       */
      required: string[];
    }
 
    /** Reference type directing named schema. */
    export interface IReference {
      /**
       * Reference to the named schema.
       *
       * The `ref` is a reference to the named schema. Format of the `$ref` is
       * following the JSON Pointer specification. In the OpenAPI, the `$ref`
       * starts with `#/components/schemas/` which means the type is stored in
       * the {@link AutoBeOpenApi.IComponents.schemas} object.
       *
       * - `#/components/schemas/SomeObject`
       * - `#/components/schemas/AnotherObject`
       */
      $ref: string;
    }
 
    /**
     * Union type.
     *
     * `IOneOf` represents an union type of the TypeScript (`A | B | C`).
     *
     * For reference, even though your Swagger (or OpenAPI) document has defined
     * `anyOf` instead of the `oneOf`, {@link AutoBeOpenApi} forcibly converts it
     * to `oneOf` type.
     */
    export interface IOneOf {
      /** List of the union types. */
      oneOf: Exclude<IJsonSchema, IJsonSchema.IOneOf>[];
 
      /** Discriminator info of the union type. */
      discriminator?: IOneOf.IDiscriminator;
    }
    export namespace IOneOf {
      /** Discriminator info of the union type. */
      export interface IDiscriminator {
        /** Property name for the discriminator. */
        propertyName: string;
 
        /**
         * Mapping of the discriminator value to the schema name.
         *
         * This property is valid only for {@link IReference} typed
         * {@link IOneOf.oneof} elements. Therefore, `key` of `mapping` is the
         * discriminator value, and `value` of `mapping` is the schema name like
         * `#/components/schemas/SomeObject`.
         */
        mapping?: Record<string, string>;
      }
    }
 
    /** Null type. */
    export interface INull extends ISignificant<"null"> {}
 
    interface ISignificant<Type extends string> {
      /** Discriminator value of the type. */
      type: Type;
    }
  }
 
  /**
   * Descriptive type schema info.
   *
   * `AutoBeOpenApi.IJsonSchemaDescriptive` is a type schema info of the OpenAPI
   * Generative, but it has a `description` property which is required.
   *
   * `AutoBeOpenApi.IJsonSchemaDescriptive` basically follows the JSON schema
   * specification of OpenAPI v3.1, but a little bit shrunk to remove ambiguous
   * and duplicated expressions of OpenAPI v3.1 for the convenience, clarity,
   * and AI generation.
   *
   * CRITICAL INSTRUCTIONS FOR OPTIMAL AI GENERATION:
   *
   * When creating descriptions for components, types, and properties:
   *
   * 1. ALWAYS refer to and incorporate the description comments from the
   *    corresponding Prisma DB schema tables and columns. The descriptions
   *    should match the style, level of detail, and terminology used in the
   *    Prisma schema.
   * 2. ALL descriptions MUST be organized into MULTIPLE PARAGRAPHS separated by
   *    line breaks. Single-paragraph descriptions should be avoided.
   * 3. Descriptions should comprehensively cover:
   *
   *    - The purpose and business meaning of the type or property
   *    - Relationships to other entities
   *    - Validation rules, constraints, and edge cases
   *    - Usage context and examples when helpful
   * 4. For each property of an object type, ensure its description reflects the
   *    corresponding column description in the Prisma DB schema, maintaining
   *    the same level of detail and terminology
   * 5. Descriptions should be so detailed and clear that anyone reading them can
   *    fully understand the type or property without needing to reference any
   *    other documentation
   */
  export type IJsonSchemaDescriptive<Schema extends IJsonSchema = IJsonSchema> =
    Omit<Schema, "description"> & {
      /**
       * Description about the type.
       *
       * CRITICAL: This description MUST be extensively detailed and MUST
       * reference and align with the description comments from the
       * corresponding Prisma DB schema tables and columns.
       *
       * The description MUST be organized into MULTIPLE PARAGRAPHS (separated
       * by line breaks) based on different aspects of the type:
       *
       * - The purpose and business meaning of the type
       * - Relationships to other entities in the system
       * - Validation rules, constraints, and edge cases
       * - Usage context and examples when helpful
       *
       * This structured approach improves readability and helps readers better
       * understand the type's various characteristics and use cases. The
       * description should be so comprehensive that anyone reading it can fully
       * understand the type without needing to reference other documentation.
       *
       * > MUST be written in English. Never use other languages.
       */
      description: string;
    };
 
  /* -----------------------------------------------------------
    BACKGROUNDS
  ----------------------------------------------------------- */
  /** API endpoint information. */
  export interface IEndpoint {
    /**
     * HTTP path of the API operation.
     *
     * The URL path for accessing this API operation, using path parameters
     * enclosed in curly braces (e.g., `/shoppings/customers/sales/{saleId}`).
     *
     * It must be corresponded to the {@link parameters path parameters}.
     *
     * The path structure should clearly indicate which database entity this
     * operation is manipulating, helping to ensure all entities have
     * appropriate API coverage.
     */
    path: string;
 
    /**
     * HTTP method of the API operation.
     *
     * Note that, if the API operation has {@link requestBody}, method must not
     * be `get`.
     *
     * Also, even though the API operation has been designed to only get
     * information, but it needs complicated request information, it must be
     * defined as `patch` method with {@link requestBody} data specification.
     *
     * - `get`: get information
     * - `patch`: get information with complicated request data
     *   ({@link requestBody})
     * - `post`: create new record
     * - `put`: update existing record
     * - `delete`: remove record
     */
    method: "get" | "post" | "put" | "delete" | "patch";
  }
}

import { OpenApiV3 } from "./OpenApiV3";
import { OpenApiV3_1 } from "./OpenApiV3_1";
import { SwaggerV2 } from "./SwaggerV2";
import { OpenApiV3Downgrader } from "./converters/OpenApiV3Downgrader";
import { OpenApiV3Upgrader } from "./converters/OpenApiV3Upgrader";
import { OpenApiV3_1Emender } from "./converters/OpenApiV3_1Emender";
import { SwaggerV2Downgrader } from "./converters/SwaggerV2Downgrader";
import { SwaggerV2Upgrader } from "./converters/SwaggerV2Upgrader";
import { IJsonSchemaAttribute } from "./structures/IJsonSchemaAttribute";
 
/**
 * Emended OpenAPI v3.1 definition used by `typia` and `nestia`.
 *
 * `OpenApi` is a namespace containing functions and interfaces for emended
 * OpenAPI v3.1 specification. The keyword "emended" means that `OpenApi` is not
 * a direct OpenAPI v3.1 specification ({@link OpenApiV3_1}), but a little bit
 * shrunk to remove ambiguous and duplicated expressions of OpenAPI v3.1 for the
 * convenience of `typia` and `nestia`.
 *
 * For example, when representing nullable type, OpenAPI v3.1 supports three
 * ways. In that case, `OpenApi` remains only the third way, so that makes
 * `typia` and `nestia` (especially `@nestia/editor`) to be simple and easy to
 * implement.
 *
 * 1. `{ type: ["string", "null"] }`
 * 2. `{ type: "string", nullable: true }`
 * 3. `{ oneOf: [{ type: "string" }, { type: "null" }] }`
 *
 * Here is the entire list of differences between OpenAPI v3.1 and emended
 * `OpenApi`.
 *
 * - Operation
 *
 *   - Merge {@link OpenApiV3_1.IPath.parameters} to
 *       {@link OpenApi.IOperation.parameters}
 *   - Resolve {@link OpenApi.IJsonSchema.IReference references} of
 *       {@link OpenApiV3_1.IOperation} members
 *   - Escape references of {@link OpenApiV3_1.IComponents.examples}
 * - JSON Schema
 *
 *   - Decompose mixed type: {@link OpenApiV3_1.IJsonSchema.IMixed}
 *   - Resolve nullable property:
 *       {@link OpenApiV3_1.IJsonSchema.__ISignificant.nullable}
 *   - Array type utilizes only single {@link OpenApi.IJsonSchema.IArray.items}
 *   - Tuple type utilizes only {@link OpenApi.IJsonSchema.ITuple.prefixItems}
 *   - Merge {@link OpenApiV3_1.IJsonSchema.IAllOf} to
 *       {@link OpenApi.IJsonSchema.IObject}
 *   - Merge {@link OpenApiV3_1.IJsonSchema.IAnyOf} to
 *       {@link OpenApi.IJsonSchema.IOneOf}
 *   - Merge {@link OpenApiV3_1.IJsonSchema.IRecursiveReference} to
 *       {@link OpenApi.IJsonSchema.IReference}
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export namespace OpenApi {
  /** Method of the operation. */
  export type Method =
    | "get"
    | "post"
    | "put"
    | "delete"
    | "options"
    | "head"
    | "patch"
    | "trace";
 
  /**
   * Convert Swagger or OpenAPI document into emended OpenAPI v3.1 document.
   *
   * @param input Swagger or OpenAPI document to convert
   * @returns Emended OpenAPI v3.1 document
   */
  export function convert(
    input:
      | SwaggerV2.IDocument
      | OpenApiV3.IDocument
      | OpenApiV3_1.IDocument
      | OpenApi.IDocument,
  ): IDocument {
    if (OpenApiV3_1.is(input))
      return OpenApiV3_1Emender.convert(input) as IDocument;
    else if (OpenApiV3.is(input))
      return OpenApiV3Upgrader.convert(input) as IDocument;
    else if (SwaggerV2.is(input))
      return SwaggerV2Upgrader.convert(input) as IDocument;
    throw new TypeError("Unrecognized Swagger/OpenAPI version.");
  }
 
  /**
   * Downgrade to Swagger v2.0 document.
   *
   * Downgrade the given document (emeneded OpenAPI v3.1) into Swagger v2.0.
   *
   * @param document Emended OpenAPI v3.1 document to downgrade
   * @param version Version to downgrade
   * @returns Swagger v2.0 document
   */
  export function downgrade(
    document: IDocument,
    version: "2.0",
  ): SwaggerV2.IDocument;
 
  /**
   * Downgrade to OpenAPI v3.0 document.
   *
   * Downgrade the given document (emeneded OpenAPI v3.1) into OpenAPI v3.0.
   *
   * @param document Emended OpenAPI v3.1 document to downgrade
   * @param version Version to downgrade
   * @returns OpenAPI v3.0 document
   */
  export function downgrade(
    document: IDocument,
    version: "3.0",
  ): OpenApiV3.IDocument;
 
  /** @internal */
  export function downgrade(
    document: IDocument,
    version: string,
  ): SwaggerV2.IDocument | OpenApiV3.IDocument {
    if (version === "2.0") return SwaggerV2Downgrader.downgrade(document);
    else if (version === "3.0") return OpenApiV3Downgrader.downgrade(document);
    throw new TypeError("Unrecognized Swagger/OpenAPI version.");
  }
 
  /* -----------------------------------------------------------
    PATH ITEMS
  ----------------------------------------------------------- */
  /**
   * OpenAPI document.
   *
   * `OpenApi.IDocument` represents an OpenAPI document of emended OpenAPI v3.1.
   *
   * In other words, `OpenApi.IDocument` is a structure of `swagger.json` file
   * of OpenAPI v3.1 specification, but a little bit shrunk to remove ambiguous
   * and duplicated expressions of OpenAPI v3.1 for the convenience and
   * clarity.
   */
  export interface IDocument {
    /** OpenAPI version number. */
    openapi: `3.1.${number}`;
 
    /** List of servers that provide the API. */
    servers?: IServer[];
 
    /** Information about the API. */
    info?: IDocument.IInfo;
 
    /**
     * An object to hold reusable data structures.
     *
     * It stores both DTO schemas and security schemes.
     *
     * For reference, `nestia` defines every object and alias types as reusable
     * DTO schemas. The alias type means that defined by `type` keyword in
     * TypeScript.
     */
    components: IComponents;
 
    /**
     * The available paths and operations for the API.
     *
     * The 1st key is the path, and the 2nd key is the HTTP method.
     */
    paths?: Record<string, IPath>;
 
    /**
     * An object to hold Webhooks.
     *
     * Its structure is same with {@link paths}, so that the 1st key is the path,
     * and the 2nd key is the HTTP method.
     */
    webhooks?: Record<string, IPath>;
 
    /**
     * A declaration of which security mechanisms can be used across the API.
     *
     * When this property be configured, it would be overwritten in every API
     * routes.
     *
     * For reference, key means the name of security scheme and value means the
     * `scopes`. The `scopes` can be used only when target security scheme is
     * `oauth2` type, especially for
     * {@link ISwaggerSecurityScheme.IOAuth2.IFlow.scopes} property.
     */
    security?: Record<string, string[]>[];
 
    /**
     * List of tag names with description.
     *
     * It is possible to omit this property or skip some tag name even if the
     * tag name is used in the API routes. In that case, the tag name would be
     * displayed (in Swagger-UI) without description.
     */
    tags?: IDocument.ITag[];
 
    /** Flag for indicating this document is emended by `@samchon/openapi` v4. */
    "x-samchon-emended-v4": true;
  }
  export namespace IDocument {
    /** Information about the API. */
    export interface IInfo {
      /** The title of the API. */
      title: string;
 
      /** A short summary of the API. */
      summary?: string;
 
      /** A full description of the API. */
      description?: string;
 
      /** A URL to the Terms of Service for the API. */
      termsOfService?: string;
 
      /** The contact information for the exposed API. */
      contact?: IContact;
 
      /** The license information for the exposed API. */
      license?: ILicense;
 
      /** Version of the API. */
      version: string;
    }
 
    /**
     * OpenAPI tag information.
     *
     * It is possible to skip composing this structure, even if some tag names
     * are registered in the API routes ({@link OpenApi.IOperation.tags}). In
     * that case, the tag name would be displayed in Swagger-UI without
     * description.
     *
     * However, if you want to describe the tag name, you can compose this
     * structure and describe the tag name in the {@link description} property.
     */
    export interface ITag {
      /** The name of the tag. */
      name: string;
 
      /** An optional string describing the tag. */
      description?: string;
    }
 
    /** Contact information for the exposed API. */
    export interface IContact {
      /** The identifying name of the contact person/organization. */
      name?: string;
 
      /** The URL pointing to the contact information. */
      url?: string;
 
      /**
       * The email address of the contact person/organization.
       *
       * @format email
       */
      email?: string;
    }
 
    /** License information for the exposed API. */
    export interface ILicense {
      /** The license name used for the API. */
      name: string;
 
      /**
       * Identifier for the license used for the API.
       *
       * Example: MIT
       */
      identifier?: string;
 
      /** A URL to the license used for the API. */
      url?: string;
    }
  }
 
  /** The remote server that provides the API. */
  export interface IServer {
    /** A URL to the target host. */
    url: string;
 
    /** An optional string describing the target server. */
    description?: string;
 
    /**
     * A map between a variable name and its value.
     *
     * When the server {@link url} is a type of template, this property would be
     * utilized to fill the template with actual values.
     */
    variables?: Record<string, IServer.IVariable>;
  }
  export namespace IServer {
    /** A variable for the server URL template. */
    export interface IVariable {
      /** Default value to use for substitution. */
      default: string;
 
      /** List of available values for the variable. */
      enum?: string[];
 
      /** An optional description for the server variable. */
      description?: string;
    }
  }
 
  /* -----------------------------------------------------------
    OPERATORS
  ----------------------------------------------------------- */
  /**
   * Path item.
   *
   * `OpenApi.IPath` represents a path item of emended OpenAPI v3.1, collecting
   * multiple method operations in a single path.
   */
  export interface IPath extends Partial<Record<Method, IOperation>> {
    /** Servers that provide the path operations. */
    servers?: IServer[];
 
    /** Summary of the path. */
    summary?: string;
 
    /** Description of the path. */
    description?: string;
  }
 
  /**
   * Remote operation info.
   *
   * `OpenApi.IOperation` represents an Restful API operation provided by the
   * remote server.
   */
  export interface IOperation {
    /** Unique string used to identify the operation. */
    operationId?: string;
 
    /** List of parameters that are applicable for this operation. */
    parameters?: IOperation.IParameter[];
 
    /** The request body applicable for this operation. */
    requestBody?: IOperation.IRequestBody;
 
    /**
     * The list of possible responses as they are returned from executing this
     * operation. Its key is the HTTP status code, and the value is the metadata
     * of the response in the HTTP status code.
     */
    responses?: Record<string, IOperation.IResponse>;
 
    /** A list of servers providing this API operation. */
    servers?: IServer[];
 
    /** A short summary of what the operation does. */
    summary?: string;
 
    /** A verbose explanation of the operation behavior. */
    description?: string;
 
    /**
     * List of securities and their scopes that are required for execution.
     *
     * When this property be configured, the Restful API operation requires the
     * matched security value for execution. Its key means security key matched
     * with {@link OpenApi.IDocument.security}.
     *
     * The value means scopes required for the security key when the security
     * type is {@link OpenApi.ISecurityScheme.IOAuth2}. Otherwise the target
     * security type is not {@link OpenApi.ISecurityScheme.IOAuth2}, the value
     * would be empty array.
     */
    security?: Record<string, string[]>[];
 
    /** Tags for API documentation control. */
    tags?: string[];
 
    /** Flag for indicating this operation is deprecated. */
    deprecated?: boolean;
 
    /**
     * Flag for indicating this operation is human-only.
     *
     * If this property value is `true`, {@link HttpLlm.application} function
     * will not convert this operation schema into the LLM function calling
     * schema that is represented by the {@link IHttpLlmFunction} interface.
     */
    "x-samchon-human"?: boolean;
 
    /**
     * Accessor of the operation.
     *
     * If you configure this property, the assigned value would be used as
     * {@link IHttpMigrateRoute.accessor}. Also, it also can be used as the
     * {@link IHttpLlmFunction.name} by joininig with `.` character in the LLM
     * function calling application.
     *
     * Note that, the `x-samchon-accessor` value must be unique in the entire
     * OpenAPI document operations. If there're duplicated `x-samchon-accessor`
     * values, {@link IHttpMigrateRoute.accessor} will ignore every duplicated
     * `x-samchon-accessor` values and generate the
     * {@link IHttpMigrateRoute.accessor} by itself.
     */
    "x-samchon-accessor"?: string[];
 
    /**
     * Controller of the operation.
     *
     * If you configure this property, the assigned value would be utilized as
     * the controller name in the OpenAPI generator library like
     * [`@nestia/editor`](https://nestia.io/docs/editor/) and
     * [`@nestia/migrate`](https://nestia.io/docs/migrate/).
     *
     * Also, if {@link x-samchon-accessor} has been configured, its last element
     * would be used as the controller method (function) name. Of course, the
     * OpenAPI document generator `@nestia/sdk` fills both of them.
     */
    "x-samchon-controller"?: string;
  }
  export namespace IOperation {
    /** Parameter of the operation. */
    export interface IParameter {
      /**
       * Representative name of the parameter.
       *
       * In the most case, the `name` is equivalent to parameter variable name.
       * Therefore, the `name` must be filled with the significant variable name
       * of the parameter.
       *
       * By the way, only when the {@link in} property is `path`, the `name` can
       * be omitted. In that case, the `name` is automatically deduced from the
       * URL path's positional template argument analyzing.
       */
      name?: string;
 
      /**
       * Location of the parameter.
       *
       * The `in` property is a string that determines the location of the
       * parameter.
       *
       * - `path`: parameter is part of the path of the URL.
       * - `query`: parameter is part of the query string.
       * - `header`: parameter is part of the header.
       * - `cookie`: parameter is part of the cookie.
       */
      in: "path" | "query" | "header" | "cookie";
 
      /** Type info of the parameter. */
      schema: IJsonSchema;
 
      /**
       * Whether the parameter is required for execution or not.
       *
       * If the parameter is required, the value must be filled. Otherwise, it
       * is possible to skip the parameter when executing the APi operation.
       *
       * For reference, the `required` property must be always `true` when the
       * {@link in} property is `path`. Otherwise, the `required` property can be
       * anything of them; `true`, `false` and `undefined`.
       */
      required?: boolean;
 
      /** Short title of the parameter. */
      title?: string;
 
      /** Verbose explanation of the parameter. */
      description?: string;
 
      /** Example value of the parameter. */
      example?: any;
 
      /** Collection of example values of the parameter with keys. */
      examples?: Record<string, IExample>;
    }
 
    /** Request body of the operation. */
    export interface IRequestBody {
      content?: IContent;
      description?: string;
      required?: boolean;
      "x-nestia-encrypted"?: boolean;
    }
 
    /** Response of the operation. */
    export interface IResponse {
      headers?: Record<string, IOperation.IParameter>;
      content?: IContent;
      description?: string;
      "x-nestia-encrypted"?: boolean;
    }
 
    /** List of content types supported in request/response body. */
    export interface IContent
      extends Partial<Record<ContentType, IMediaType>> {}
 
    /** Media type of a request/response body. */
    export interface IMediaType {
      schema?: IJsonSchema;
      example?: any;
      examples?: Record<string, IExample>;
    }
 
    /** List of supported content media types. */
    export type ContentType =
      | "text/plain"
      | "application/json"
      | "application/x-www-form-url-encoded"
      | "multipart/form-data"
      | "*/*"
      | (string & {});
  }
 
  /** Example of the operation parameter or response. */
  export interface IExample {
    summary?: string;
    description?: string;
    value?: any;
    externalValue?: string;
  }
 
  /* -----------------------------------------------------------
    SCHEMA DEFINITIONS
  ----------------------------------------------------------- */
  /**
   * Reusable components in OpenAPI.
   *
   * A storage of reusable components in OpenAPI document.
   *
   * In other words, it is a storage of named DTO schemas and security schemes.
   */
  export interface IComponents {
    /**
     * An object to hold reusable DTO schemas.
     *
     * In other words, a collection of named JSON schemas.
     */
    schemas?: Record<string, IJsonSchema>;
 
    /**
     * An object to hold reusable security schemes.
     *
     * In other words, a collection of named security schemes.
     */
    securitySchemes?: Record<string, ISecurityScheme>;
  }
 
  /**
   * Type schema info.
   *
   * `OpenApi.IJsonSchema` is a type schema info of the OpenAPI.
   *
   * `OpenApi.IJsonSchema` basically follows the JSON schema definition of
   * OpenAPI v3.1, but a little bit shrunk to remove ambiguous and duplicated
   * expressions of OpenAPI v3.1 for the convenience and clarity.
   *
   * - Decompose mixed type: {@link OpenApiV3_1.IJsonSchema.IMixed}
   * - Resolve nullable property:
   *   {@link OpenApiV3_1.IJsonSchema.__ISignificant.nullable}
   * - Array type utilizes only single {@link OpenAPI.IJsonSchema.IArray.items}
   * - Tuple type utilizes only {@link OpenApi.IJsonSchema.ITuple.prefixItems}
   * - Merge {@link OpenApiV3_1.IJsonSchema.IAllOf} to
   *   {@link OpenApi.IJsonSchema.IObject}
   * - Merge {@link OpenApiV3_1.IJsonSchema.IAnyOf} to
   *   {@link OpenApi.IJsonSchema.IOneOf}
   * - Merge {@link OpenApiV3_1.IJsonSchema.IRecursiveReference} to
   *   {@link OpenApi.IJsonSchema.IReference}
   */
  export type IJsonSchema =
    | IJsonSchema.IConstant
    | IJsonSchema.IBoolean
    | IJsonSchema.IInteger
    | IJsonSchema.INumber
    | IJsonSchema.IString
    | IJsonSchema.IArray
    | IJsonSchema.ITuple
    | IJsonSchema.IObject
    | IJsonSchema.IReference
    | IJsonSchema.IOneOf
    | IJsonSchema.INull
    | IJsonSchema.IUnknown;
  export namespace IJsonSchema {
    /** Constant value type. */
    export interface IConstant extends IJsonSchemaAttribute {
      /** The constant value. */
      const: boolean | number | string;
    }
 
    /** Boolean type info. */
    export interface IBoolean extends IJsonSchemaAttribute.IBoolean {
      /** The default value of the boolean type. */
      default?: boolean;
    }
 
    /** Integer type info. */
    export interface IInteger extends IJsonSchemaAttribute.IInteger {
      /**
       * Default value of the integer type.
       *
       * @type int64
       */
      default?: number;
 
      /**
       * Minimum value restriction.
       *
       * @type int64
       */
      minimum?: number;
 
      /**
       * Maximum value restriction.
       *
       * @type int64
       */
      maximum?: number;
 
      /** Exclusive minimum value restriction. */
      exclusiveMinimum?: number;
 
      /** Exclusive maximum value restriction. */
      exclusiveMaximum?: number;
 
      /**
       * Multiple of value restriction.
       *
       * @type uint64
       * @exclusiveMinimum 0
       */
      multipleOf?: number;
    }
 
    /** Number (double) type info. */
    export interface INumber extends IJsonSchemaAttribute.INumber {
      /** Default value of the number type. */
      default?: number;
 
      /** Minimum value restriction. */
      minimum?: number;
 
      /** Maximum value restriction. */
      maximum?: number;
 
      /** Exclusive minimum value restriction. */
      exclusiveMinimum?: number;
 
      /** Exclusive maximum value restriction. */
      exclusiveMaximum?: number;
 
      /**
       * Multiple of value restriction.
       *
       * @exclusiveMinimum 0
       */
      multipleOf?: number;
    }
 
    /** String type info. */
    export interface IString extends IJsonSchemaAttribute.IString {
      /** Default value of the string type. */
      default?: string;
 
      /** Format restriction. */
      format?:
        | "binary"
        | "byte"
        | "password"
        | "regex"
        | "uuid"
        | "email"
        | "hostname"
        | "idn-email"
        | "idn-hostname"
        | "iri"
        | "iri-reference"
        | "ipv4"
        | "ipv6"
        | "uri"
        | "uri-reference"
        | "uri-template"
        | "url"
        | "date-time"
        | "date"
        | "time"
        | "duration"
        | "json-pointer"
        | "relative-json-pointer"
        | (string & {});
 
      /** Pattern restriction. */
      pattern?: string;
 
      /** Content media type restriction. */
      contentMediaType?: string;
 
      /**
       * Minimum length restriction.
       *
       * @type uint64
       */
      minLength?: number;
 
      /**
       * Maximum length restriction.
       *
       * @type uint64
       */
      maxLength?: number;
    }
 
    /** Array type info. */
    export interface IArray extends IJsonSchemaAttribute.IArray {
      /**
       * Items type info.
       *
       * The `items` means the type of the array elements. In other words, it is
       * the type schema info of the `T` in the TypeScript array type
       * `Array<T>`.
       */
      items: IJsonSchema;
 
      /**
       * Unique items restriction.
       *
       * If this property value is `true`, target array must have unique items.
       */
      uniqueItems?: boolean;
 
      /**
       * Minimum items restriction.
       *
       * Restriction of minimum number of items in the array.
       *
       * @type uint64
       */
      minItems?: number;
 
      /**
       * Maximum items restriction.
       *
       * Restriction of maximum number of items in the array.
       *
       * @type uint64
       */
      maxItems?: number;
    }
 
    /** Tuple type info. */
    export interface ITuple extends IJsonSchemaAttribute {
      /**
       * Discriminator value of the type.
       *
       * Note that, the tuple type cannot be distinguished with {@link IArray}
       * type just by this `discriminator` property.
       *
       * To check whether the type is tuple or array, you have to check the
       * existence of {@link IArray.items} or {@link ITuple.prefixItems}
       * properties.
       */
      type: "array";
 
      /**
       * Prefix items.
       *
       * The `prefixItems` means the type schema info of the prefix items in the
       * tuple type. In the TypeScript, it is expressed as `[T1, T2]`.
       *
       * If you want to express `[T1, T2, ...TO[]]` type, you can configure the
       * `...TO[]` through the {@link additionalItems} property.
       */
      prefixItems: IJsonSchema[];
 
      /**
       * Additional items.
       *
       * The `additionalItems` means the type schema info of the additional
       * items after the {@link prefixItems}. In the TypeScript, if there's a
       * type `[T1, T2, ...TO[]]`, the `...TO[]` is represented by the
       * `additionalItems`.
       *
       * By the way, if you configure the `additionalItems` as `true`, it means
       * the additional items are not restricted. They can be any type, so that
       * it is equivalent to the TypeScript type `[T1, T2, ...any[]]`.
       *
       * Otherwise configure the `additionalItems` as the {@link IJsonSchema}, it
       * means the additional items must follow the type schema info. Therefore,
       * it is equivalent to the TypeScript type `[T1, T2, ...TO[]]`.
       */
      additionalItems?: boolean | IJsonSchema;
 
      /**
       * Unique items restriction.
       *
       * If this property value is `true`, target tuple must have unique items.
       */
      uniqueItems?: boolean;
 
      /**
       * Minimum items restriction.
       *
       * Restriction of minimum number of items in the tuple.
       *
       * @type uint64
       */
      minItems?: number;
 
      /**
       * Maximum items restriction.
       *
       * Restriction of maximum number of items in the tuple.
       *
       * @type uint64
       */
      maxItems?: number;
    }
 
    /** Object type info. */
    export interface IObject extends IJsonSchemaAttribute.IObject {
      /**
       * Properties of the object.
       *
       * The `properties` means a list of key-value pairs of the object's
       * regular properties. The key is the name of the regular property, and
       * the value is the type schema info.
       *
       * If you need additional properties that is represented by dynamic key,
       * you can use the {@link additionalProperties} instead.
       */
      properties?: Record<string, IJsonSchema>;
 
      /**
       * Additional properties' info.
       *
       * The `additionalProperties` means the type schema info of the additional
       * properties that are not listed in the {@link properties}.
       *
       * If the value is `true`, it means that the additional properties are not
       * restricted. They can be any type. Otherwise, if the value is
       * {@link IJsonSchema} type, it means that the additional properties must
       * follow the type schema info.
       *
       * - `true`: `Record<string, any>`
       * - `IJsonSchema`: `Record<string, T>`
       */
      additionalProperties?: boolean | IJsonSchema;
 
      /**
       * List of key values of the required properties.
       *
       * The `required` means a list of the key values of the required
       * {@link properties}. If some property key is not listed in the `required`
       * list, it means that property is optional. Otherwise some property key
       * exists in the `required` list, it means that the property must be
       * filled.
       *
       * Below is an example of the {@link properties} and `required`.
       *
       * ```typescript
       * interface SomeObject {
       *   id: string;
       *   email: string;
       *   name?: string;
       * }
       * ```
       *
       * As you can see, `id` and `email` {@link properties} are {@link required},
       * so that they are listed in the `required` list.
       *
       * ```json
       * {
       *   "type": "object",
       *   "properties": {
       *     "id": { "type": "string" },
       *     "email": { "type": "string" },
       *     "name": { "type": "string" }
       *   },
       *   "required": ["id", "email"]
       * }
       * ```
       */
      required?: string[];
    }
 
    /** Reference type directing named schema. */
    export interface IReference<Key = string> extends IJsonSchemaAttribute {
      /**
       * Reference to the named schema.
       *
       * The `ref` is a reference to the named schema. Format of the `$ref` is
       * following the JSON Pointer specification. In the OpenAPI, the `$ref`
       * starts with `#/components/schemas/` which means the type is stored in
       * the {@link OpenApi.IComponents.schemas} object.
       *
       * - `#/components/schemas/SomeObject`
       * - `#/components/schemas/AnotherObject`
       */
      $ref: Key;
    }
 
    /**
     * Union type.
     *
     * `IOneOf` represents an union type of the TypeScript (`A | B | C`).
     *
     * For reference, even though your Swagger (or OpenAPI) document has defined
     * `anyOf` instead of the `oneOf`, {@link OpenApi} forcibly converts it to
     * `oneOf` type.
     */
    export interface IOneOf extends IJsonSchemaAttribute {
      /** List of the union types. */
      oneOf: Exclude<IJsonSchema, IJsonSchema.IOneOf>[];
 
      /** Discriminator info of the union type. */
      discriminator?: IOneOf.IDiscriminator;
    }
    export namespace IOneOf {
      /** Discriminator info of the union type. */
      export interface IDiscriminator {
        /** Property name for the discriminator. */
        propertyName: string;
 
        /**
         * Mapping of the discriminator value to the schema name.
         *
         * This property is valid only for {@link IReference} typed
         * {@link IOneOf.oneof} elements. Therefore, `key` of `mapping` is the
         * discriminator value, and `value` of `mapping` is the schema name like
         * `#/components/schemas/SomeObject`.
         */
        mapping?: Record<string, string>;
      }
    }
 
    /** Null type. */
    export interface INull extends IJsonSchemaAttribute.INull {
      /** Default value of the `null` type. */
      default?: null;
    }
 
    /** Unknown, the `any` type. */
    export interface IUnknown extends IJsonSchemaAttribute.IUnknown {
      /** Default value of the `any` type. */
      default?: any;
    }
 
    /**
     * Significant attributes that can be applied to the most types.
     *
     * @ignore
     * @deprecated
     */
    export interface __ISignificant<Type extends string>
      extends IJsonSchemaAttribute {
      /** Discriminator value of the type. */
      type: Type;
    }
 
    /**
     * Common attributes that can be applied to all types.
     *
     * @ignore
     * @deprecated
     */
    export type __IAttribute = IJsonSchemaAttribute;
  }
 
  /**
   * Security scheme of Swagger Documents.
   *
   * `OpenApi.ISecurityScheme` is a data structure representing content of
   * `securitySchemes` in `swagger.json` file. It is composed with 5 types of
   * security schemes as an union type like below.
   *
   * @reference https://swagger.io/specification/#security-scheme-object
   */
  export type ISecurityScheme =
    | ISecurityScheme.IApiKey
    | ISecurityScheme.IHttpBasic
    | ISecurityScheme.IHttpBearer
    | ISecurityScheme.IOAuth2
    | ISecurityScheme.IOpenId;
  export namespace ISecurityScheme {
    /** Normal API key type. */
    export interface IApiKey {
      type: "apiKey";
      in?: "header" | "query" | "cookie";
      name?: string;
      description?: string;
    }
 
    /** HTTP basic authentication type. */
    export interface IHttpBasic {
      type: "http";
      scheme: "basic";
      description?: string;
    }
 
    /** HTTP bearer authentication type. */
    export interface IHttpBearer {
      type: "http";
      scheme: "bearer";
      bearerFormat?: string;
      description?: string;
    }
 
    /** OAuth2 authentication type. */
    export interface IOAuth2 {
      type: "oauth2";
      flows: IOAuth2.IFlowSet;
      description?: string;
    }
    export interface IOpenId {
      type: "openIdConnect";
      openIdConnectUrl: string;
      description?: string;
    }
    export namespace IOAuth2 {
      export interface IFlowSet {
        authorizationCode?: IFlow;
        implicit?: Omit<IFlow, "tokenUrl">;
        password?: Omit<IFlow, "authorizationUrl">;
        clientCredentials?: Omit<IFlow, "authorizationUrl">;
      }
      export interface IFlow {
        authorizationUrl?: string;
        tokenUrl?: string;
        refreshUrl?: string;
        scopes?: Record<string, string>;
      }
    }
  }
}