@typia/interface 12.0.0-dev.20260309 → 12.0.0-dev.20260311

package/src/schema/ILlmSchema.ts

@@ -1,484 +1,473 @@
-import { tags } from "../index";
-import { IJsonSchemaAttribute } from "./IJsonSchemaAttribute";
-
-/**
- * Type schema for LLM function calling.
- *
- * `ILlmSchema` is a JSON Schema subset designed for LLM function calling
- * compatibility. Most LLMs (OpenAI GPT, Anthropic Claude, Google Gemini, etc.)
- * do not fully support JSON Schema, so this simplified schema omits unsupported
- * features like tuples, `const`, and mixed union types.
- *
- * Generated by `typia.llm.schema<T>()` for single types or included in
- * {@link ILlmApplication} via `typia.llm.application<Class>()`. Shared type
- * definitions use `$defs` with `$ref` references to reduce duplication and
- * handle recursive structures.
- *
- * Set {@link ILlmSchema.IConfig.strict} to `true` for OpenAI's structured output
- * mode, which requires all properties to be `required` and
- * `additionalProperties: false`.
- *
- * @author Jeongho Nam - https://github.com/samchon
- */
-export type ILlmSchema =
-  | ILlmSchema.IBoolean
-  | ILlmSchema.IInteger
-  | ILlmSchema.INumber
-  | ILlmSchema.IString
-  | ILlmSchema.IArray
-  | ILlmSchema.IObject
-  | ILlmSchema.IReference
-  | ILlmSchema.IAnyOf
-  | ILlmSchema.INull
-  | ILlmSchema.IUnknown;
-export namespace ILlmSchema {
-  /**
-   * Configuration options for LLM schema generation.
-   *
-   * Controls how TypeScript types are converted to LLM-compatible JSON schemas.
-   * These settings affect reference handling and OpenAI structured output
-   * compatibility.
-   */
-  export interface IConfig {
-    /**
-     * Whether to allow `$ref` references everywhere.
-     *
-     * When `false`, references are inlined except for recursive types.
-     * References reduce token cost but may cause hallucination.
-     *
-     * @default true
-     */
-    reference: boolean;
-
-    /**
-     * Whether to enable strict mode (OpenAI structured output).
-     *
-     * When `true`, all properties become required and `additionalProperties` is
-     * forced to `false`.
-     *
-     * @default false
-     */
-    strict: boolean;
-  }
-
-  /**
-   * Function parameters schema with shared type definitions.
-   *
-   * Extends the object schema to include a `$defs` map for named type
-   * definitions that can be referenced via `$ref`. This structure allows
-   * recursive types and reduces schema duplication.
-   *
-   * The `additionalProperties` is always `false` for parameters to ensure
-   * strict argument validation and prevent unexpected properties.
-   */
-  export interface IParameters extends Omit<IObject, "additionalProperties"> {
-    /**
-     * Named schema definitions for reference.
-     *
-     * Contains type definitions that can be referenced throughout the schema
-     * using `$ref: "#/$defs/TypeName"`. Essential for recursive types and
-     * shared structures.
-     */
-    $defs: Record<string, ILlmSchema>;
-
-    /**
-     * Whether additional properties are allowed.
-     *
-     * Always `false` for function parameters to ensure strict type checking.
-     * This prevents LLMs from hallucinating extra properties.
-     */
-    additionalProperties: false;
-  }
-
-  /**
-   * Boolean type schema.
-   *
-   * Represents a JSON Schema boolean type with optional enum constraints and
-   * default value. Used for true/false parameters and flags.
-   */
-  export interface IBoolean extends IJsonSchemaAttribute.IBoolean {
-    /**
-     * Allowed boolean values.
-     *
-     * Restricts the value to specific boolean literals. Typically unused since
-     * booleans only have two possible values, but supported for consistency
-     * with other types.
-     */
-    enum?: Array<boolean>;
-
-    /**
-     * Default value when not provided.
-     *
-     * The boolean value to use when the LLM omits this parameter.
-     */
-    default?: boolean;
-  }
-
-  /**
-   * Integer type schema.
-   *
-   * Represents a JSON Schema integer type with numeric constraints. Maps to
-   * TypeScript `number` with integer validation. Supports range constraints,
-   * enum restrictions, and divisibility checks.
-   */
-  export interface IInteger extends IJsonSchemaAttribute.IInteger {
-    /**
-     * Allowed integer values.
-     *
-     * Restricts the value to specific integer literals. Useful for representing
-     * enum-like integer codes or limited value sets.
-     */
-    enum?: Array<number & tags.Type<"int64">>;
-
-    /**
-     * Default value when not provided.
-     *
-     * The integer value to use when the LLM omits this parameter.
-     */
-    default?: number & tags.Type<"int64">;
-
-    /**
-     * Minimum value (inclusive).
-     *
-     * The value must be greater than or equal to this number.
-     */
-    minimum?: number & tags.Type<"int64">;
-
-    /**
-     * Maximum value (inclusive).
-     *
-     * The value must be less than or equal to this number.
-     */
-    maximum?: number & tags.Type<"int64">;
-
-    /**
-     * Exclusive minimum value.
-     *
-     * The value must be strictly greater than this number.
-     */
-    exclusiveMinimum?: number & tags.Type<"int64">;
-
-    /**
-     * Exclusive maximum value.
-     *
-     * The value must be strictly less than this number.
-     */
-    exclusiveMaximum?: number & tags.Type<"int64">;
-
-    /**
-     * Value must be divisible by this number.
-     *
-     * Used for constraints like "must be even" (multipleOf: 2) or "must be a
-     * multiple of 100" (multipleOf: 100).
-     */
-    multipleOf?: number & tags.Type<"uint64"> & tags.ExclusiveMinimum<0>;
-  }
-
-  /**
-   * Number (floating-point) type schema.
-   *
-   * Represents a JSON Schema number type for floating-point values. Maps to
-   * TypeScript `number` type. Supports range constraints, enum restrictions,
-   * and precision checks via multipleOf.
-   */
-  export interface INumber extends IJsonSchemaAttribute.INumber {
-    /**
-     * Allowed numeric values.
-     *
-     * Restricts the value to specific number literals. Useful for representing
-     * specific valid values like percentages or rates.
-     */
-    enum?: Array<number>;
-
-    /**
-     * Default value when not provided.
-     *
-     * The number to use when the LLM omits this parameter.
-     */
-    default?: number;
-
-    /**
-     * Minimum value (inclusive).
-     *
-     * The value must be greater than or equal to this number.
-     */
-    minimum?: number;
-
-    /**
-     * Maximum value (inclusive).
-     *
-     * The value must be less than or equal to this number.
-     */
-    maximum?: number;
-
-    /**
-     * Exclusive minimum value.
-     *
-     * The value must be strictly greater than this number.
-     */
-    exclusiveMinimum?: number;
-
-    /**
-     * Exclusive maximum value.
-     *
-     * The value must be strictly less than this number.
-     */
-    exclusiveMaximum?: number;
-
-    /**
-     * Value must be divisible by this number.
-     *
-     * Useful for decimal precision constraints like "two decimal places"
-     * (multipleOf: 0.01) or currency amounts (multipleOf: 0.01).
-     */
-    multipleOf?: number & tags.ExclusiveMinimum<0>;
-  }
-
-  /**
-   * String type schema.
-   *
-   * Represents a JSON Schema string type with format validation, pattern
-   * matching, and length constraints. Maps to TypeScript `string` type with
-   * optional semantic format annotations.
-   */
-  export interface IString extends IJsonSchemaAttribute.IString {
-    /**
-     * Allowed string values.
-     *
-     * Restricts the value to specific string literals. Maps directly to
-     * TypeScript string literal union types.
-     */
-    enum?: Array<string>;
-
-    /**
-     * Default value when not provided.
-     *
-     * The string to use when the LLM omits this parameter.
-     */
-    default?: string;
-
-    /**
-     * Semantic format specifier.
-     *
-     * Indicates the string represents a specific format like email, UUID, or
-     * date-time. LLMs may use this to generate appropriate values. Common
-     * formats include "email", "uri", "uuid", "date-time".
-     */
-    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 & {});
-
-    /**
-     * Regular expression pattern for validation.
-     *
-     * The string must match this regex pattern. Note that LLMs may struggle
-     * with complex regex patterns; simple patterns work best.
-     */
-    pattern?: string;
-
-    /**
-     * MIME type of the string content.
-     *
-     * Indicates the content type when the string contains encoded binary data,
-     * such as "application/json" or "image/png".
-     */
-    contentMediaType?: string;
-
-    /**
-     * Minimum string length.
-     *
-     * The string must have at least this many characters.
-     */
-    minLength?: number & tags.Type<"uint64">;
-
-    /**
-     * Maximum string length.
-     *
-     * The string must have at most this many characters.
-     */
-    maxLength?: number & tags.Type<"uint64">;
-  }
-
-  /**
-   * Array type schema.
-   *
-   * Represents a JSON Schema array type with item type validation and size
-   * constraints. Maps to TypeScript `T[]` or `Array<T>` types. Note: Tuple
-   * types are not supported by LLM schemas.
-   */
-  export interface IArray extends IJsonSchemaAttribute.IArray {
-    /**
-     * Schema for array elements.
-     *
-     * All elements in the array must conform to this schema. For heterogeneous
-     * arrays, use an `anyOf` schema.
-     */
-    items: ILlmSchema;
-
-    /**
-     * Whether elements must be unique.
-     *
-     * When `true`, no two elements may be equal. Maps to TypeScript `Set<T>`
-     * semantics but represented as an array.
-     */
-    uniqueItems?: boolean;
-
-    /**
-     * Minimum number of elements.
-     *
-     * The array must contain at least this many items.
-     */
-    minItems?: number & tags.Type<"uint64">;
-
-    /**
-     * Maximum number of elements.
-     *
-     * The array must contain at most this many items.
-     */
-    maxItems?: number & tags.Type<"uint64">;
-  }
-
-  /**
-   * Object type schema.
-   *
-   * Represents a JSON Schema object type with named properties. Maps to
-   * TypeScript interface or object type. Supports required property
-   * declarations and dynamic additional properties.
-   */
-  export interface IObject extends IJsonSchemaAttribute.IObject {
-    /**
-     * Property name to schema mapping.
-     *
-     * Defines the type of each named property on the object. All properties are
-     * defined here regardless of whether they are required or optional.
-     */
-    properties: Record<string, ILlmSchema>;
-
-    /**
-     * Schema for dynamic/additional properties.
-     *
-     * - `false` (default): No additional properties allowed
-     * - `true`: Any additional properties allowed
-     * - Schema: Additional properties must match this schema
-     *
-     * Note: ChatGPT and Gemini do not support `additionalProperties`. Use
-     * {@link ILlmSchema.IConfig.strict} mode for OpenAI compatibility.
-     */
-    additionalProperties?: ILlmSchema | boolean;
-
-    /**
-     * List of required property names.
-     *
-     * Properties in this array must be present in the object. In strict mode,
-     * all properties become required automatically.
-     */
-    required: string[];
-  }
-
-  /**
-   * Reference to a named schema definition.
-   *
-   * Points to a schema defined in the `$defs` map using a JSON pointer. Used to
-   * avoid schema duplication and enable recursive type definitions. The
-   * reference path format is `#/$defs/TypeName`.
-   */
-  export interface IReference extends IJsonSchemaAttribute {
-    /**
-     * JSON pointer to the referenced schema.
-     *
-     * Must be in the format `#/$defs/TypeName` where TypeName is a key in the
-     * parent schema's `$defs` map.
-     */
-    $ref: string;
-  }
-
-  /**
-   * Union type schema (A | B | C).
-   *
-   * Represents a TypeScript union type where the value can match any one of the
-   * member schemas. Note: Gemini does not support `anyOf`/`oneOf` schemas. Use
-   * discriminated unions with `x-discriminator` when possible for better LLM
-   * comprehension.
-   */
-  export interface IAnyOf extends IJsonSchemaAttribute {
-    /**
-     * Array of possible schemas.
-     *
-     * The value must match at least one of these schemas. Nested `anyOf`
-     * schemas are flattened to avoid deep nesting.
-     */
-    anyOf: Exclude<ILlmSchema, ILlmSchema.IAnyOf>[];
-
-    /**
-     * Discriminator for tagged/discriminated unions.
-     *
-     * Helps LLMs understand which variant to select based on a discriminating
-     * property value. Improves type inference accuracy.
-     */
-    "x-discriminator"?: IAnyOf.IDiscriminator;
-  }
-  export namespace IAnyOf {
-    /**
-     * Discriminator configuration for tagged unions.
-     *
-     * Specifies which property distinguishes between union variants and maps
-     * discriminator values to their corresponding schemas.
-     */
-    export interface IDiscriminator {
-      /**
-       * Name of the discriminating property.
-       *
-       * This property must exist on all union member object schemas and contain
-       * unique literal values that identify each variant.
-       */
-      propertyName: string;
-
-      /**
-       * Mapping from discriminator values to schema references.
-       *
-       * Keys are the literal values of the discriminator property, values are
-       * `$ref` paths to the corresponding schemas.
-       */
-      mapping?: Record<string, string>;
-    }
-  }
-
-  /**
-   * Null type schema.
-   *
-   * Represents the JSON null value. In TypeScript union types like `T | null`,
-   * this schema appears in an `anyOf` alongside the T schema.
-   */
-  export interface INull extends IJsonSchemaAttribute.INull {}
-
-  /**
-   * Unknown/any type schema.
-   *
-   * Represents TypeScript `any` or `unknown` types where no specific type
-   * constraint is defined. Use sparingly as LLMs may generate unexpected values
-   * for unconstrained types.
-   */
-  export interface IUnknown extends IJsonSchemaAttribute.IUnknown {}
-}
+import { tags } from "../index";
+import { IJsonSchemaAttribute } from "./IJsonSchemaAttribute";
+
+/**
+ * Type schema for LLM function calling.
+ *
+ * `ILlmSchema` is a JSON Schema subset designed for LLM function calling
+ * compatibility. Most LLMs (OpenAI GPT, Anthropic Claude, Google Gemini, etc.)
+ * do not fully support JSON Schema, so this simplified schema omits unsupported
+ * features like tuples, `const`, and mixed union types.
+ *
+ * Generated by `typia.llm.schema<T>()` for single types or included in
+ * {@link ILlmApplication} via `typia.llm.application<Class>()`. Shared type
+ * definitions use `$defs` with `$ref` references to reduce duplication and
+ * handle recursive structures.
+ *
+ * Set {@link ILlmSchema.IConfig.strict} to `true` for OpenAI's structured output
+ * mode, which requires all properties to be `required` and
+ * `additionalProperties: false`.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type ILlmSchema =
+  | ILlmSchema.IBoolean
+  | ILlmSchema.IInteger
+  | ILlmSchema.INumber
+  | ILlmSchema.IString
+  | ILlmSchema.IArray
+  | ILlmSchema.IObject
+  | ILlmSchema.IReference
+  | ILlmSchema.IAnyOf
+  | ILlmSchema.INull
+  | ILlmSchema.IUnknown;
+export namespace ILlmSchema {
+  /**
+   * Configuration options for LLM schema generation.
+   *
+   * Controls how TypeScript types are converted to LLM-compatible JSON schemas.
+   * These settings affect OpenAI structured output compatibility.
+   */
+  export interface IConfig {
+    /**
+     * Whether to enable strict mode (OpenAI structured output).
+     *
+     * When `true`, all properties become required and `additionalProperties` is
+     * forced to `false`.
+     *
+     * @default false
+     */
+    strict: boolean;
+  }
+
+  /**
+   * Function parameters schema with shared type definitions.
+   *
+   * Extends the object schema to include a `$defs` map for named type
+   * definitions that can be referenced via `$ref`. This structure allows
+   * recursive types and reduces schema duplication.
+   *
+   * The `additionalProperties` is always `false` for parameters to ensure
+   * strict argument validation and prevent unexpected properties.
+   */
+  export interface IParameters extends Omit<IObject, "additionalProperties"> {
+    /**
+     * Named schema definitions for reference.
+     *
+     * Contains type definitions that can be referenced throughout the schema
+     * using `$ref: "#/$defs/TypeName"`. Essential for recursive types and
+     * shared structures.
+     */
+    $defs: Record<string, ILlmSchema>;
+
+    /**
+     * Whether additional properties are allowed.
+     *
+     * Always `false` for function parameters to ensure strict type checking.
+     * This prevents LLMs from hallucinating extra properties.
+     */
+    additionalProperties: false;
+  }
+
+  /**
+   * Boolean type schema.
+   *
+   * Represents a JSON Schema boolean type with optional enum constraints and
+   * default value. Used for true/false parameters and flags.
+   */
+  export interface IBoolean extends IJsonSchemaAttribute.IBoolean {
+    /**
+     * Allowed boolean values.
+     *
+     * Restricts the value to specific boolean literals. Typically unused since
+     * booleans only have two possible values, but supported for consistency
+     * with other types.
+     */
+    enum?: Array<boolean>;
+
+    /**
+     * Default value when not provided.
+     *
+     * The boolean value to use when the LLM omits this parameter.
+     */
+    default?: boolean;
+  }
+
+  /**
+   * Integer type schema.
+   *
+   * Represents a JSON Schema integer type with numeric constraints. Maps to
+   * TypeScript `number` with integer validation. Supports range constraints,
+   * enum restrictions, and divisibility checks.
+   */
+  export interface IInteger extends IJsonSchemaAttribute.IInteger {
+    /**
+     * Allowed integer values.
+     *
+     * Restricts the value to specific integer literals. Useful for representing
+     * enum-like integer codes or limited value sets.
+     */
+    enum?: Array<number & tags.Type<"int64">>;
+
+    /**
+     * Default value when not provided.
+     *
+     * The integer value to use when the LLM omits this parameter.
+     */
+    default?: number & tags.Type<"int64">;
+
+    /**
+     * Minimum value (inclusive).
+     *
+     * The value must be greater than or equal to this number.
+     */
+    minimum?: number & tags.Type<"int64">;
+
+    /**
+     * Maximum value (inclusive).
+     *
+     * The value must be less than or equal to this number.
+     */
+    maximum?: number & tags.Type<"int64">;
+
+    /**
+     * Exclusive minimum value.
+     *
+     * The value must be strictly greater than this number.
+     */
+    exclusiveMinimum?: number & tags.Type<"int64">;
+
+    /**
+     * Exclusive maximum value.
+     *
+     * The value must be strictly less than this number.
+     */
+    exclusiveMaximum?: number & tags.Type<"int64">;
+
+    /**
+     * Value must be divisible by this number.
+     *
+     * Used for constraints like "must be even" (multipleOf: 2) or "must be a
+     * multiple of 100" (multipleOf: 100).
+     */
+    multipleOf?: number & tags.Type<"uint64"> & tags.ExclusiveMinimum<0>;
+  }
+
+  /**
+   * Number (floating-point) type schema.
+   *
+   * Represents a JSON Schema number type for floating-point values. Maps to
+   * TypeScript `number` type. Supports range constraints, enum restrictions,
+   * and precision checks via multipleOf.
+   */
+  export interface INumber extends IJsonSchemaAttribute.INumber {
+    /**
+     * Allowed numeric values.
+     *
+     * Restricts the value to specific number literals. Useful for representing
+     * specific valid values like percentages or rates.
+     */
+    enum?: Array<number>;
+
+    /**
+     * Default value when not provided.
+     *
+     * The number to use when the LLM omits this parameter.
+     */
+    default?: number;
+
+    /**
+     * Minimum value (inclusive).
+     *
+     * The value must be greater than or equal to this number.
+     */
+    minimum?: number;
+
+    /**
+     * Maximum value (inclusive).
+     *
+     * The value must be less than or equal to this number.
+     */
+    maximum?: number;
+
+    /**
+     * Exclusive minimum value.
+     *
+     * The value must be strictly greater than this number.
+     */
+    exclusiveMinimum?: number;
+
+    /**
+     * Exclusive maximum value.
+     *
+     * The value must be strictly less than this number.
+     */
+    exclusiveMaximum?: number;
+
+    /**
+     * Value must be divisible by this number.
+     *
+     * Useful for decimal precision constraints like "two decimal places"
+     * (multipleOf: 0.01) or currency amounts (multipleOf: 0.01).
+     */
+    multipleOf?: number & tags.ExclusiveMinimum<0>;
+  }
+
+  /**
+   * String type schema.
+   *
+   * Represents a JSON Schema string type with format validation, pattern
+   * matching, and length constraints. Maps to TypeScript `string` type with
+   * optional semantic format annotations.
+   */
+  export interface IString extends IJsonSchemaAttribute.IString {
+    /**
+     * Allowed string values.
+     *
+     * Restricts the value to specific string literals. Maps directly to
+     * TypeScript string literal union types.
+     */
+    enum?: Array<string>;
+
+    /**
+     * Default value when not provided.
+     *
+     * The string to use when the LLM omits this parameter.
+     */
+    default?: string;
+
+    /**
+     * Semantic format specifier.
+     *
+     * Indicates the string represents a specific format like email, UUID, or
+     * date-time. LLMs may use this to generate appropriate values. Common
+     * formats include "email", "uri", "uuid", "date-time".
+     */
+    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 & {});
+
+    /**
+     * Regular expression pattern for validation.
+     *
+     * The string must match this regex pattern. Note that LLMs may struggle
+     * with complex regex patterns; simple patterns work best.
+     */
+    pattern?: string;
+
+    /**
+     * MIME type of the string content.
+     *
+     * Indicates the content type when the string contains encoded binary data,
+     * such as "application/json" or "image/png".
+     */
+    contentMediaType?: string;
+
+    /**
+     * Minimum string length.
+     *
+     * The string must have at least this many characters.
+     */
+    minLength?: number & tags.Type<"uint64">;
+
+    /**
+     * Maximum string length.
+     *
+     * The string must have at most this many characters.
+     */
+    maxLength?: number & tags.Type<"uint64">;
+  }
+
+  /**
+   * Array type schema.
+   *
+   * Represents a JSON Schema array type with item type validation and size
+   * constraints. Maps to TypeScript `T[]` or `Array<T>` types. Note: Tuple
+   * types are not supported by LLM schemas.
+   */
+  export interface IArray extends IJsonSchemaAttribute.IArray {
+    /**
+     * Schema for array elements.
+     *
+     * All elements in the array must conform to this schema. For heterogeneous
+     * arrays, use an `anyOf` schema.
+     */
+    items: ILlmSchema;
+
+    /**
+     * Whether elements must be unique.
+     *
+     * When `true`, no two elements may be equal. Maps to TypeScript `Set<T>`
+     * semantics but represented as an array.
+     */
+    uniqueItems?: boolean;
+
+    /**
+     * Minimum number of elements.
+     *
+     * The array must contain at least this many items.
+     */
+    minItems?: number & tags.Type<"uint64">;
+
+    /**
+     * Maximum number of elements.
+     *
+     * The array must contain at most this many items.
+     */
+    maxItems?: number & tags.Type<"uint64">;
+  }
+
+  /**
+   * Object type schema.
+   *
+   * Represents a JSON Schema object type with named properties. Maps to
+   * TypeScript interface or object type. Supports required property
+   * declarations and dynamic additional properties.
+   */
+  export interface IObject extends IJsonSchemaAttribute.IObject {
+    /**
+     * Property name to schema mapping.
+     *
+     * Defines the type of each named property on the object. All properties are
+     * defined here regardless of whether they are required or optional.
+     */
+    properties: Record<string, ILlmSchema>;
+
+    /**
+     * Schema for dynamic/additional properties.
+     *
+     * - `false` (default): No additional properties allowed
+     * - `true`: Any additional properties allowed
+     * - Schema: Additional properties must match this schema
+     *
+     * Note: ChatGPT and Gemini do not support `additionalProperties`. Use
+     * {@link ILlmSchema.IConfig.strict} mode for OpenAI compatibility.
+     */
+    additionalProperties?: ILlmSchema | boolean;
+
+    /**
+     * List of required property names.
+     *
+     * Properties in this array must be present in the object. In strict mode,
+     * all properties become required automatically.
+     */
+    required: string[];
+  }
+
+  /**
+   * Reference to a named schema definition.
+   *
+   * Points to a schema defined in the `$defs` map using a JSON pointer. Used to
+   * avoid schema duplication and enable recursive type definitions. The
+   * reference path format is `#/$defs/TypeName`.
+   */
+  export interface IReference extends IJsonSchemaAttribute {
+    /**
+     * JSON pointer to the referenced schema.
+     *
+     * Must be in the format `#/$defs/TypeName` where TypeName is a key in the
+     * parent schema's `$defs` map.
+     */
+    $ref: string;
+  }
+
+  /**
+   * Union type schema (A | B | C).
+   *
+   * Represents a TypeScript union type where the value can match any one of the
+   * member schemas. Note: Gemini does not support `anyOf`/`oneOf` schemas. Use
+   * discriminated unions with `x-discriminator` when possible for better LLM
+   * comprehension.
+   */
+  export interface IAnyOf extends IJsonSchemaAttribute {
+    /**
+     * Array of possible schemas.
+     *
+     * The value must match at least one of these schemas. Nested `anyOf`
+     * schemas are flattened to avoid deep nesting.
+     */
+    anyOf: Exclude<ILlmSchema, ILlmSchema.IAnyOf>[];
+
+    /**
+     * Discriminator for tagged/discriminated unions.
+     *
+     * Helps LLMs understand which variant to select based on a discriminating
+     * property value. Improves type inference accuracy.
+     */
+    "x-discriminator"?: IAnyOf.IDiscriminator;
+  }
+  export namespace IAnyOf {
+    /**
+     * Discriminator configuration for tagged unions.
+     *
+     * Specifies which property distinguishes between union variants and maps
+     * discriminator values to their corresponding schemas.
+     */
+    export interface IDiscriminator {
+      /**
+       * Name of the discriminating property.
+       *
+       * This property must exist on all union member object schemas and contain
+       * unique literal values that identify each variant.
+       */
+      propertyName: string;
+
+      /**
+       * Mapping from discriminator values to schema references.
+       *
+       * Keys are the literal values of the discriminator property, values are
+       * `$ref` paths to the corresponding schemas.
+       */
+      mapping?: Record<string, string>;
+    }
+  }
+
+  /**
+   * Null type schema.
+   *
+   * Represents the JSON null value. In TypeScript union types like `T | null`,
+   * this schema appears in an `anyOf` alongside the T schema.
+   */
+  export interface INull extends IJsonSchemaAttribute.INull {}
+
+  /**
+   * Unknown/any type schema.
+   *
+   * Represents TypeScript `any` or `unknown` types where no specific type
+   * constraint is defined. Use sparingly as LLMs may generate unexpected values
+   * for unconstrained types.
+   */
+  export interface IUnknown extends IJsonSchemaAttribute.IUnknown {}
+}