@typia/interface 12.0.0-dev.20260225

package/src/schema/IJsonSchemaApplication.ts

@@ -0,0 +1,274 @@
+import { OpenApi } from "../openapi/OpenApi";
+import { OpenApiV3 } from "../openapi/OpenApiV3";
+
+/**
+ * JSON Schema application representing TypeScript functions.
+ *
+ * `IJsonSchemaApplication` represents a collection of TypeScript class methods
+ * or functions converted to JSON Schema format. Generated at compile time by
+ * `typia.json.application<App>()`, this is primarily used for OpenAPI document
+ * generation and as an intermediate format for LLM function calling schemas.
+ *
+ * Unlike {@link ILlmApplication} which is optimized for LLM consumption, this
+ * interface preserves full JSON Schema expressiveness including features that
+ * some LLM providers don't support (tuples, additionalProperties, etc.).
+ *
+ * The application contains:
+ *
+ * - {@link functions}: Array of function metadata with parameter/return schemas
+ * - {@link components}: Shared schema definitions for `$ref` references
+ * - {@link __application}: Phantom property for type inference
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Version OpenAPI version ("3.0" or "3.1")
+ * @template App Source class/interface type for type preservation
+ */
+export interface IJsonSchemaApplication<
+  Version extends "3.0" | "3.1" = "3.1",
+  App extends any = object,
+> {
+  /**
+   * OpenAPI specification version.
+   *
+   * Determines the JSON Schema dialect used for type definitions. Use `"3.1"`
+   * for modern JSON Schema features, `"3.0"` for broader compatibility with
+   * older OpenAPI consumers.
+   */
+  version: Version;
+
+  /**
+   * Shared schema definitions for `$ref` references.
+   *
+   * Contains named schemas that can be referenced by functions to avoid
+   * duplication and enable recursive type definitions.
+   */
+  components: IJsonSchemaApplication.IComponents<
+    IJsonSchemaApplication.Schema<Version>
+  >;
+
+  /**
+   * Array of function schemas.
+   *
+   * Each function includes parameter schemas, return type schema, and metadata
+   * extracted from JSDoc comments. Functions are derived from public methods of
+   * the source class/interface.
+   */
+  functions: IJsonSchemaApplication.IFunction<
+    IJsonSchemaApplication.Schema<Version>
+  >[];
+
+  /**
+   * Phantom property for TypeScript generic type preservation.
+   *
+   * This property exists only in the type system to preserve the `App` generic
+   * parameter at compile time. It is always `undefined` at runtime and should
+   * not be accessed or used in application code.
+   *
+   * Enables type inference to recover the original application type from an
+   * `IJsonSchemaApplication` instance.
+   */
+  __application?: App | undefined;
+}
+export namespace IJsonSchemaApplication {
+  /**
+   * Schema type selector based on OpenAPI version.
+   *
+   * Returns the appropriate JSON schema type for the specified OpenAPI version.
+   *
+   * - `"3.1"` → {@link OpenApi.IJsonSchema} (emended OpenAPI v3.1)
+   * - `"3.0"` → {@link OpenApiV3.IJsonSchema} (OpenAPI v3.0)
+   */
+  export type Schema<Version extends "3.0" | "3.1"> = Version extends "3.1"
+    ? OpenApi.IJsonSchema
+    : OpenApiV3.IJsonSchema;
+
+  /**
+   * Shared schema component definitions.
+   *
+   * Contains named schema definitions that can be referenced via `$ref`
+   * throughout the application's function schemas. Reduces duplication and
+   * enables recursive type definitions.
+   *
+   * @template Schema JSON schema type based on OpenAPI version
+   */
+  export interface IComponents<
+    Schema extends OpenApi.IJsonSchema | OpenApiV3.IJsonSchema =
+      OpenApi.IJsonSchema,
+  > {
+    /**
+     * Named schema definitions for reference.
+     *
+     * Keys are type names, values are their JSON Schema definitions. Reference
+     * these using `$ref: "#/components/schemas/TypeName"`.
+     */
+    schemas?: Record<string, Schema>;
+  }
+
+  /**
+   * Complete metadata for a single function.
+   *
+   * Contains all information needed to describe a function in JSON Schema
+   * format, including parameters, return type, and documentation extracted from
+   * JSDoc comments.
+   *
+   * @template Schema JSON schema type based on OpenAPI version
+   */
+  export interface IFunction<
+    Schema extends OpenApi.IJsonSchema | OpenApiV3.IJsonSchema =
+      OpenApi.IJsonSchema,
+  > {
+    /**
+     * Whether the function is asynchronous.
+     *
+     * `true` if the function returns a Promise, `false` for synchronous
+     * functions. Useful for runtime execution handling.
+     */
+    async: boolean;
+
+    /**
+     * Function name identifier.
+     *
+     * The name used to call this function. Derived from the method name in the
+     * source class/interface.
+     */
+    name: string;
+
+    /**
+     * Array of function parameters.
+     *
+     * Ordered list of parameters with their names, types, and documentation.
+     * Parameters preserve their declaration order.
+     */
+    parameters: IParameter<Schema>[];
+
+    /**
+     * Return type information.
+     *
+     * Contains the return type schema and documentation. `undefined` when the
+     * function returns `void` or has no return type annotation.
+     */
+    output: IOutput<Schema> | undefined;
+
+    /**
+     * Brief summary of the function.
+     *
+     * Short one-line description extracted from the first line of JSDoc
+     * comment. Intended for quick reference in documentation.
+     */
+    summary?: string | undefined;
+
+    /**
+     * Full function description.
+     *
+     * Complete documentation extracted from JSDoc comment body. May include
+     * markdown formatting, examples, and detailed explanations.
+     */
+    description?: string | undefined;
+
+    /**
+     * Whether the function is deprecated.
+     *
+     * Set from the `@deprecated` JSDoc tag. Indicates the function should no
+     * longer be used and may be removed in future versions.
+     */
+    deprecated?: boolean;
+
+    /**
+     * Category tags for organization.
+     *
+     * Extracted from `@tag` JSDoc annotations. Useful for grouping related
+     * functions in documentation or filtering.
+     */
+    tags?: string[];
+  }
+
+  /**
+   * Metadata for a single function parameter.
+   *
+   * Describes a function parameter including its name, type schema, whether
+   * it's required, and any JSDoc documentation.
+   *
+   * @template Schema JSON schema type based on OpenAPI version
+   */
+  export interface IParameter<
+    Schema extends OpenApi.IJsonSchema | OpenApiV3.IJsonSchema =
+      OpenApi.IJsonSchema,
+  > {
+    /**
+     * Parameter name.
+     *
+     * The identifier used in the function signature. Must match the actual
+     * parameter name in the source code.
+     */
+    name: string;
+
+    /**
+     * Whether the parameter is required.
+     *
+     * `true` if the parameter must be provided, `false` if it has a default
+     * value or is explicitly optional.
+     */
+    required: boolean;
+
+    /**
+     * JSON Schema for the parameter type.
+     *
+     * Complete schema definition describing the expected parameter type,
+     * including constraints and nested structures.
+     */
+    schema: Schema;
+
+    /**
+     * Parameter title for documentation.
+     *
+     * Brief name for the parameter, typically extracted from `@param` tag title
+     * in JSDoc.
+     */
+    title?: string | undefined;
+
+    /**
+     * Parameter description from documentation.
+     *
+     * Full description of the parameter's purpose and usage, extracted from the
+     * `@param` JSDoc tag.
+     */
+    description?: string | undefined;
+  }
+
+  /**
+   * Metadata for function return type.
+   *
+   * Describes the return type of a function including its schema, whether a
+   * value is always returned, and documentation.
+   *
+   * @template Schema JSON schema type based on OpenAPI version
+   */
+  export interface IOutput<
+    Schema extends OpenApi.IJsonSchema | OpenApiV3.IJsonSchema =
+      OpenApi.IJsonSchema,
+  > {
+    /**
+     * JSON Schema for the return type.
+     *
+     * Complete schema definition describing the return value type, including
+     * constraints and nested structures.
+     */
+    schema: Schema;
+
+    /**
+     * Whether a value is always returned.
+     *
+     * `true` if the function always returns a value, `false` if it may return
+     * `undefined` or has a void return type.
+     */
+    required: boolean;
+
+    /**
+     * Return value description from documentation.
+     *
+     * Explanation of what the function returns, extracted from the `@returns`
+     * or `@return` JSDoc tag.
+     */
+    description?: string | undefined;
+  }
+}

package/src/schema/IJsonSchemaAttribute.ts

@@ -0,0 +1,158 @@
+/**
+ * Common attributes shared by all JSON schema types.
+ *
+ * `IJsonSchemaAttribute` defines the base set of metadata properties that can
+ * be attached to any JSON schema type. These attributes provide documentation,
+ * deprecation status, examples, and access control information.
+ *
+ * This interface serves as the foundation for all schema types in typia's JSON
+ * Schema generation. The namespace contains type-specific variants (e.g.,
+ * {@link IBoolean}, {@link IString}) that add a `type` discriminator while
+ * inheriting all base attributes.
+ *
+ * These attributes are populated from JSDoc comments during schema generation:
+ *
+ * - `@title` tag → {@link title}
+ * - Main comment body → {@link description}
+ * - `@deprecated` tag → {@link deprecated}
+ * - `@example` tag → {@link example}
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IJsonSchemaAttribute {
+  /**
+   * Short title for the schema.
+   *
+   * A brief, human-readable name for the type. Typically extracted from the
+   * first line of a JSDoc comment or the `@title` tag.
+   */
+  title?: string;
+
+  /**
+   * Detailed description of the schema.
+   *
+   * Full documentation for the type, explaining its purpose, constraints, and
+   * usage. Extracted from JSDoc comment body. Supports markdown formatting in
+   * many JSON Schema consumers.
+   */
+  description?: string;
+
+  /**
+   * Whether this type is deprecated.
+   *
+   * When `true`, indicates the type should no longer be used and may be removed
+   * in future versions. Set via the `@deprecated` JSDoc tag.
+   */
+  deprecated?: boolean;
+
+  /**
+   * Single example value for the schema.
+   *
+   * A representative value that conforms to the schema, useful for
+   * documentation and testing. Set via the `@example` JSDoc tag.
+   */
+  example?: any;
+
+  /**
+   * Named example values for the schema.
+   *
+   * Multiple examples as key-value pairs, where keys are example names and
+   * values are conforming data. Useful for showing different valid states or
+   * edge cases.
+   */
+  examples?: Record<string, any>;
+
+  /**
+   * Whether the property is read-only.
+   *
+   * When `true`, the property should not be modified by clients and is
+   * typically set by the server. Useful for generated IDs, timestamps, etc.
+   */
+  readOnly?: boolean;
+
+  /**
+   * Whether the property is write-only.
+   *
+   * When `true`, the property is accepted on input but never returned in
+   * responses. Common for sensitive data like passwords.
+   */
+  writeOnly?: boolean;
+}
+export namespace IJsonSchemaAttribute {
+  /**
+   * Attribute interface for boolean schema types.
+   *
+   * Extends base attributes with `type: "boolean"` discriminator.
+   */
+  export interface IBoolean extends ISignificant<"boolean"> {}
+
+  /**
+   * Attribute interface for integer schema types.
+   *
+   * Extends base attributes with `type: "integer"` discriminator. Note: JSON
+   * Schema uses "integer" for whole numbers, distinct from "number".
+   */
+  export interface IInteger extends ISignificant<"integer"> {}
+
+  /**
+   * Attribute interface for number schema types.
+   *
+   * Extends base attributes with `type: "number"` discriminator. Represents
+   * floating-point numbers in JSON Schema.
+   */
+  export interface INumber extends ISignificant<"number"> {}
+
+  /**
+   * Attribute interface for string schema types.
+   *
+   * Extends base attributes with `type: "string"` discriminator.
+   */
+  export interface IString extends ISignificant<"string"> {}
+
+  /**
+   * Attribute interface for object schema types.
+   *
+   * Extends base attributes with `type: "object"` discriminator. Used for
+   * structured data with named properties.
+   */
+  export interface IObject extends ISignificant<"object"> {}
+
+  /**
+   * Attribute interface for array schema types.
+   *
+   * Extends base attributes with `type: "array"` discriminator. Represents
+   * ordered collections of items.
+   */
+  export interface IArray extends ISignificant<"array"> {}
+
+  /**
+   * Attribute interface for null schema types.
+   *
+   * Extends base attributes with `type: "null"` discriminator. Represents the
+   * JSON null value.
+   */
+  export interface INull extends ISignificant<"null"> {}
+
+  /**
+   * Attribute interface for unknown/untyped schemas.
+   *
+   * Used when the schema type is not specified or cannot be determined. The
+   * `type` property is explicitly undefined to indicate no type constraint.
+   */
+  export interface IUnknown extends IJsonSchemaAttribute {
+    type?: undefined;
+  }
+
+  /**
+   * Base interface for type-discriminated schema attributes.
+   *
+   * Internal helper that combines base attributes with a type discriminator.
+   * Each specific type interface (IBoolean, IString, etc.) extends this with
+   * its corresponding type literal.
+   *
+   * @template Type - The JSON Schema type string literal
+   */
+  interface ISignificant<Type extends string> extends IJsonSchemaAttribute {
+    type: Type;
+  }
+}

package/src/schema/IJsonSchemaCollection.ts

@@ -0,0 +1,123 @@
+import { OpenApi } from "../openapi/OpenApi";
+import { OpenApiV3 } from "../openapi/OpenApiV3";
+
+/**
+ * Collection of JSON schemas generated from multiple TypeScript types.
+ *
+ * `IJsonSchemaCollection` holds JSON schemas for multiple TypeScript types
+ * generated at compile time by `typia.json.schemas<[T1, T2, ...]>()`. The
+ * schemas share a common components pool to avoid duplication when types
+ * reference each other.
+ *
+ * This is useful when you need schemas for multiple related types and want to
+ * share component definitions between them. For single types, use
+ * {@link IJsonSchemaUnit} instead. For function schemas, see
+ * {@link IJsonSchemaApplication}.
+ *
+ * The collection contains:
+ *
+ * - {@link IV3_1.schemas | schemas}: Array of schemas, one per input type
+ * - {@link IV3_1.components | components}: Shared `$ref` definitions
+ * - {@link IV3_1.__types | __types}: Phantom property for type inference
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Version OpenAPI version ("3.0" or "3.1")
+ * @template Types Tuple of original TypeScript types
+ */
+export type IJsonSchemaCollection<
+  Version extends "3.0" | "3.1" = "3.1",
+  Types = unknown[],
+> = Version extends "3.0"
+  ? IJsonSchemaCollection.IV3_0<Types>
+  : IJsonSchemaCollection.IV3_1<Types>;
+
+export namespace IJsonSchemaCollection {
+  /**
+   * JSON Schema collection for OpenAPI v3.0 specification.
+   *
+   * Uses OpenAPI v3.0 compatible JSON Schema format. In v3.0, nullable types
+   * are expressed with `nullable: true` rather than v3.1's `type` arrays.
+   *
+   * @template Types Tuple of original TypeScript types for phantom type
+   *   preservation
+   */
+  export interface IV3_0<Types = unknown[]> {
+    /**
+     * OpenAPI specification version.
+     *
+     * Always `"3.0"` for this variant. Use this discriminator to determine
+     * which schema format is in use.
+     */
+    version: "3.0";
+
+    /**
+     * Generated JSON schemas, one per input type.
+     *
+     * Array of schemas in the same order as the input type tuple. Each schema
+     * may reference definitions in {@link components}.
+     */
+    schemas: OpenApiV3.IJsonSchema[];
+
+    /**
+     * Shared schema definitions for `$ref` references.
+     *
+     * Contains named schemas used across multiple types in the collection.
+     * Reduces duplication when types share common structures.
+     */
+    components: OpenApiV3.IComponents;
+
+    /**
+     * Phantom property for TypeScript generic type preservation.
+     *
+     * This property exists only in the type system to preserve the `Types`
+     * generic parameter. It is always `undefined` at runtime and should not be
+     * accessed or used in application code.
+     */
+    __types?: Types | undefined;
+  }
+
+  /**
+   * JSON Schema collection for OpenAPI v3.1 specification.
+   *
+   * Uses OpenAPI v3.1 compatible JSON Schema format. v3.1 aligns more closely
+   * with JSON Schema draft 2020-12, supporting features like `type` arrays for
+   * nullable types and `const` values.
+   *
+   * @template Types Tuple of original TypeScript types for phantom type
+   *   preservation
+   */
+  export interface IV3_1<Types = unknown[]> {
+    /**
+     * OpenAPI specification version.
+     *
+     * Always `"3.1"` for this variant. Use this discriminator to determine
+     * which schema format is in use.
+     */
+    version: "3.1";
+
+    /**
+     * Shared schema definitions for `$ref` references.
+     *
+     * Contains named schemas used across multiple types in the collection.
+     * Reduces duplication when types share common structures.
+     */
+    components: OpenApi.IComponents;
+
+    /**
+     * Generated JSON schemas, one per input type.
+     *
+     * Array of schemas in the same order as the input type tuple. Each schema
+     * may reference definitions in {@link components}.
+     */
+    schemas: OpenApi.IJsonSchema[];
+
+    /**
+     * Phantom property for TypeScript generic type preservation.
+     *
+     * This property exists only in the type system to preserve the `Types`
+     * generic parameter. It is always `undefined` at runtime and should not be
+     * accessed or used in application code.
+     */
+    __types?: Types | undefined;
+  }
+}

package/src/schema/IJsonSchemaTransformError.ts

@@ -0,0 +1,86 @@
+import { OpenApi } from "../openapi";
+
+/**
+ * Error information from JSON schema transformation.
+ *
+ * `IJsonSchemaTransformError` represents an error that occurred during
+ * transformation or iteration of {@link OpenApi.IJsonSchema} types. This error
+ * type is primarily generated when converting OpenAPI schemas to LLM-compatible
+ * formats via {@link ILlmSchema}.
+ *
+ * Common transformation failures include:
+ *
+ * - **Missing references**: `$ref` pointing to non-existent schema definitions
+ * - **Unsupported tuple types**: All LLM providers reject tuple schemas
+ * - **Unsupported union types**: Gemini does not support `oneOf` schemas
+ * - **Unsupported dynamic objects**: ChatGPT and Gemini reject
+ *   `additionalProperties`
+ *
+ * The {@link reasons} array provides detailed information about each failure,
+ * including the problematic schema, its location path, and a human-readable
+ * error message. Use this information to diagnose and fix schema compatibility
+ * issues.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IJsonSchemaTransformError {
+  /**
+   * Name of the method that caused the error.
+   *
+   * Identifies which transformation function failed, such as
+   * `"HttpLlm.application"` or `"LlmSchemaConverter.schema"`.
+   */
+  method: string;
+
+  /**
+   * Summary error message.
+   *
+   * A human-readable description of the overall error. For detailed information
+   * about specific failures, examine the {@link reasons} array.
+   */
+  message: string;
+
+  /**
+   * Detailed list of transformation failures.
+   *
+   * Each entry describes a specific schema that failed transformation,
+   * including its location and the reason for failure. Multiple failures can
+   * occur in a single transformation when processing complex schemas.
+   */
+  reasons: IJsonSchemaTransformError.IReason[];
+}
+export namespace IJsonSchemaTransformError {
+  /**
+   * Detailed information about a single transformation failure.
+   *
+   * Provides the specific schema that failed, its accessor path for locating it
+   * within the document, and a message explaining why the transformation
+   * failed.
+   */
+  export interface IReason {
+    /**
+     * The schema that caused the transformation failure.
+     *
+     * The actual JSON schema object that could not be transformed. Inspect this
+     * to understand the problematic schema structure.
+     */
+    schema: OpenApi.IJsonSchema;
+
+    /**
+     * Path to the failing schema within the document.
+     *
+     * A dot-notation path (e.g., `"components.schemas.User.properties.tags"`)
+     * that identifies where the problematic schema is located. Use this to
+     * locate and fix the issue in the source OpenAPI document.
+     */
+    accessor: string;
+
+    /**
+     * Human-readable explanation of the failure.
+     *
+     * Describes why the schema could not be transformed, such as "Tuple type is
+     * not supported" or "Cannot resolve $ref reference".
+     */
+    message: string;
+  }
+}