@typia/interface 12.0.0-dev.20260225

package/lib/schema/IJsonSchemaApplication.d.ts

@@ -0,0 +1,232 @@
+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 declare 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)
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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/lib/schema/IJsonSchemaApplication.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IJsonSchemaApplication.js.map

package/lib/schema/IJsonSchemaApplication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IJsonSchemaApplication.js","sourceRoot":"","sources":["../../src/schema/IJsonSchemaApplication.ts"],"names":[],"mappings":""}

package/lib/schema/IJsonSchemaAttribute.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 declare 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;
+    }
+    export {};
+}

package/lib/schema/IJsonSchemaAttribute.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IJsonSchemaAttribute.js.map

package/lib/schema/IJsonSchemaAttribute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IJsonSchemaAttribute.js","sourceRoot":"","sources":["../../src/schema/IJsonSchemaAttribute.ts"],"names":[],"mappings":""}

package/lib/schema/IJsonSchemaCollection.d.ts

@@ -0,0 +1,109 @@
+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 declare 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
+     */
+    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
+     */
+    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/lib/schema/IJsonSchemaCollection.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IJsonSchemaCollection.js.map

package/lib/schema/IJsonSchemaCollection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IJsonSchemaCollection.js","sourceRoot":"","sources":["../../src/schema/IJsonSchemaCollection.ts"],"names":[],"mappings":""}

package/lib/schema/IJsonSchemaTransformError.d.ts

@@ -0,0 +1,81 @@
+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 declare 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.
+     */
+    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;
+    }
+}

package/lib/schema/IJsonSchemaTransformError.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IJsonSchemaTransformError.js.map

package/lib/schema/IJsonSchemaTransformError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IJsonSchemaTransformError.js","sourceRoot":"","sources":["../../src/schema/IJsonSchemaTransformError.ts"],"names":[],"mappings":""}