@typia/interface 12.0.0-dev.20260225

package/src/tags/Constant.ts

@@ -0,0 +1,49 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Documentation metadata for literal/constant values.
+ *
+ * `Constant<Value, Content>` enhances literal type values with human-readable
+ * documentation that appears in generated JSON Schema output. This is useful
+ * for enum-like values where each literal needs individual documentation.
+ *
+ * Unlike TypeScript enums which lose their documentation in schema generation,
+ * `Constant` preserves title and description for each value. This helps API
+ * consumers understand the meaning of each allowed value.
+ *
+ * The tag itself doesn't perform validation - it only adds metadata. The
+ * literal type constraint is enforced by TypeScript's type system.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   type OrderStatus =
+ *     | Constant<
+ *         "pending",
+ *         { title: "Pending"; description: "Order placed" }
+ *       >
+ *     | Constant<"shipped", { title: "Shipped"; description: "In transit" }>
+ *     | Constant<
+ *         "delivered",
+ *         { title: "Delivered"; description: "Complete" }
+ *       >;
+ *
+ *   interface Order {
+ *     status: OrderStatus;
+ *   }
+ *
+ * @template Value The literal value (boolean, number, string, or bigint)
+ * @template Content Object with optional `title` and `description` properties
+ */
+export type Constant<
+  Value extends boolean | number | string | bigint,
+  Content extends {
+    title?: string | undefined;
+    description?: string | undefined;
+  },
+> = Value &
+  TagBase<{
+    target: "string" | "boolean" | "number" | "bigint";
+    kind: "constant";
+    value: undefined;
+    schema: Content;
+  }>;

package/src/tags/ContentMediaType.ts

@@ -0,0 +1,40 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * MIME type metadata for string content.
+ *
+ * `ContentMediaType<Type>` is a type tag that documents the media type of
+ * string content. This is metadata-only - no runtime validation is performed.
+ * The information appears in generated JSON Schema output.
+ *
+ * This is useful when a string property contains encoded binary data or
+ * structured content that should be interpreted according to a specific media
+ * type, such as base64-encoded images or embedded JSON.
+ *
+ * Common MIME types:
+ *
+ * - `"application/json"`: JSON data as string
+ * - `"application/xml"`: XML data as string
+ * - `"image/png"`: Base64-encoded PNG image
+ * - `"image/jpeg"`: Base64-encoded JPEG image
+ * - `"application/octet-stream"`: Generic binary data
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Document {
+ *     // Base64-encoded PNG image
+ *     thumbnail: string & ContentMediaType<"image/png">;
+ *     // JSON stored as string
+ *     metadata: string & ContentMediaType<"application/json">;
+ *   }
+ *
+ * @template Value MIME type string literal
+ */
+export type ContentMediaType<Value extends string> = TagBase<{
+  target: "string";
+  kind: "contentMediaType";
+  value: undefined;
+  schema: {
+    contentMediaType: Value;
+  };
+}>;

package/src/tags/Default.ts

@@ -0,0 +1,50 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Default value metadata for JSON Schema generation.
+ *
+ * `Default<Value>` is a type tag that specifies a default value for a property
+ * in the generated JSON Schema. This is metadata-only - typia does not
+ * automatically apply default values at runtime.
+ *
+ * The default value appears in the `default` field of the JSON Schema output,
+ * which API documentation tools and code generators can use to show default
+ * values or generate code that applies them.
+ *
+ * Only primitive literal types are supported: `boolean`, `bigint`, `number`,
+ * and `string`. For complex defaults, consider using optional properties with
+ * runtime default assignment.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Config {
+ *     // Default to 10 items per page
+ *     pageSize: (number & Default<10>) | undefined;
+ *     // Default to enabled
+ *     enabled: (boolean & Default<true>) | undefined;
+ *     // Default sort order
+ *     sortOrder: (string & Default<"asc">) | undefined;
+ *   }
+ *
+ * @template Value The default value literal (must be a primitive)
+ */
+export type Default<Value extends boolean | bigint | number | string> =
+  TagBase<{
+    target: Value extends boolean
+      ? "boolean"
+      : Value extends bigint
+        ? "bigint"
+        : Value extends number
+          ? "number"
+          : "string";
+    kind: "default";
+    value: Value;
+    exclusive: true;
+    schema: Value extends bigint
+      ? { default: Numeric<Value> }
+      : { default: Value };
+  }>;
+
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

package/src/tags/Example.ts

@@ -0,0 +1,48 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Single example value for JSON Schema documentation.
+ *
+ * `Example<Value>` is a type tag that adds a representative example value to
+ * the generated JSON Schema. This is metadata-only - it appears in the
+ * `example` field of the schema and helps API consumers understand expected
+ * values.
+ *
+ * Examples are displayed in API documentation tools like Swagger UI and can be
+ * used by code generators to produce more helpful client code.
+ *
+ * Supports all JSON-compatible types: primitives, objects, arrays, and null.
+ * For multiple named examples, use {@link Examples} instead.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface User {
+ *     email: string & Format<"email"> & Example<"user@example.com">;
+ *     age: number & Minimum<0> & Example<25>;
+ *     tags: string[] & Example<["admin", "active"]>;
+ *   }
+ *
+ * @template Value The example value (any JSON-compatible type)
+ */
+export type Example<
+  Value extends
+    | boolean
+    | bigint
+    | number
+    | string
+    | object
+    | Array<unknown>
+    | null,
+> = TagBase<{
+  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
+  kind: "example";
+  value: Value;
+  exclusive: true;
+  schema: Value extends bigint
+    ? { example: Numeric<Value> }
+    : { example: Value };
+}>;
+
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

package/src/tags/Examples.ts

@@ -0,0 +1,50 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Multiple named examples for JSON Schema documentation.
+ *
+ * `Examples<Record>` is a type tag that adds multiple labeled example values to
+ * the generated JSON Schema. Each example has a name and a value, providing
+ * rich documentation for different use cases or scenarios.
+ *
+ * This is useful when a property can have various valid values and you want to
+ * illustrate multiple possibilities, such as different user types, edge cases,
+ * or common configurations.
+ *
+ * The examples appear in the `examples` field of the JSON Schema and are
+ * displayed by API documentation tools. For a single unnamed example, use
+ * {@link Example} instead.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Product {
+ *     price: number &
+ *       Examples<{
+ *         budget: 9.99;
+ *         premium: 99.99;
+ *         enterprise: 999.99;
+ *       }>;
+ *     status: string &
+ *       Examples<{
+ *         active: "active";
+ *         discontinued: "discontinued";
+ *         preorder: "preorder";
+ *       }>;
+ *   }
+ *
+ * @template Value Record mapping example names to their values
+ */
+export type Examples<
+  Value extends Record<
+    string,
+    boolean | bigint | number | string | object | Array<unknown> | null
+  >,
+> = TagBase<{
+  target: "boolean" | "bigint" | "number" | "string" | "array" | "object";
+  kind: "examples";
+  value: Value;
+  exclusive: true;
+  schema: {
+    examples: Value;
+  };
+}>;

package/src/tags/ExclusiveMaximum.ts

@@ -0,0 +1,46 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Exclusive maximum value constraint (value < max).
+ *
+ * `ExclusiveMaximum<N>` is a type tag that validates numeric values are
+ * strictly less than the specified bound (not equal). Apply it to `number` or
+ * `bigint` properties using TypeScript intersection types.
+ *
+ * This constraint is **mutually exclusive** with {@link Maximum} - you cannot
+ * use both on the same property. Use `ExclusiveMaximum` for exclusive bounds
+ * (<) and `Maximum` for inclusive bounds (<=).
+ *
+ * The constraint is enforced at runtime by `typia.is()`, `typia.assert()`, and
+ * `typia.validate()`. It also generates `exclusiveMaximum` in JSON Schema.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Temperature {
+ *     // Must be less than 100 (boiling point), not equal
+ *     celsius: number & ExclusiveMaximum<100>;
+ *   }
+ *
+ * @template Value The maximum bound (exclusive - value must be less)
+ */
+export type ExclusiveMaximum<Value extends number | bigint> = TagBase<{
+  target: Value extends bigint ? "bigint" : "number";
+  kind: "exclusiveMaximum";
+  value: Value;
+  validate: `$input < ${Cast<Value>}`;
+  exclusive: ["exclusiveMaximum", "maximum"];
+  schema: Value extends bigint
+    ? {
+        exclusiveMaximum: Numeric<Value>;
+      }
+    : {
+        exclusiveMaximum: Value;
+      };
+}>;
+
+type Cast<Value extends number | bigint> = Value extends number
+  ? Value
+  : `BigInt(${Value})`;
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

package/src/tags/ExclusiveMinimum.ts

@@ -0,0 +1,46 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Exclusive minimum value constraint (value > min).
+ *
+ * `ExclusiveMinimum<N>` is a type tag that validates numeric values are
+ * strictly greater than the specified bound (not equal). Apply it to `number`
+ * or `bigint` properties using TypeScript intersection types.
+ *
+ * This constraint is **mutually exclusive** with {@link Minimum} - you cannot
+ * use both on the same property. Use `ExclusiveMinimum` for exclusive bounds
+ * (>) and `Minimum` for inclusive bounds (>=).
+ *
+ * The constraint is enforced at runtime by `typia.is()`, `typia.assert()`, and
+ * `typia.validate()`. It also generates `exclusiveMinimum` in JSON Schema.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface PositiveNumber {
+ *     // Must be greater than 0, not equal to 0
+ *     value: number & ExclusiveMinimum<0>;
+ *   }
+ *
+ * @template Value The minimum bound (exclusive - value must be greater)
+ */
+export type ExclusiveMinimum<Value extends number | bigint> = TagBase<{
+  target: Value extends bigint ? "bigint" : "number";
+  kind: "exclusiveMinimum";
+  value: Value;
+  validate: `${Cast<Value>} < $input`;
+  exclusive: ["exclusiveMinimum", "minimum"];
+  schema: Value extends bigint
+    ? {
+        exclusiveMinimum: Numeric<Value>;
+      }
+    : {
+        exclusiveMinimum: Value;
+      };
+}>;
+
+type Cast<Value extends number | bigint> = Value extends number
+  ? Value
+  : `BigInt(${Value})`;
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

package/src/tags/Format.ts

@@ -0,0 +1,76 @@
+import type { TagBase } from "./TagBase";
+
+/**
+ * String format validation constraint.
+ *
+ * `Format<Value>` validates strings against predefined formats (email, uuid,
+ * url, date-time, etc.). Mutually exclusive with {@link Pattern}.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Value Format identifier (see {@link Format.Value} for options)
+ */
+export type Format<Value extends Format.Value> = TagBase<{
+  target: "string";
+  kind: "format";
+  value: Value;
+  validate: `$importInternal("isFormat${PascalizeString<Value>}")($input)`;
+  exclusive: ["format", "pattern"];
+  schema: {
+    format: Value;
+  };
+}>;
+export namespace Format {
+  /**
+   * Supported format identifiers.
+   *
+   * Standard JSON Schema formats:
+   *
+   * - `email`, `idn-email`: Email addresses
+   * - `hostname`, `idn-hostname`: Hostnames
+   * - `uri`, `uri-reference`, `uri-template`, `url`: URLs
+   * - `iri`, `iri-reference`: Internationalized URLs
+   * - `uuid`: UUID strings
+   * - `ipv4`, `ipv6`: IP addresses
+   * - `date-time`, `date`, `time`, `duration`: Date/time formats
+   * - `json-pointer`, `relative-json-pointer`: JSON pointers
+   * - `regex`: Regular expression patterns
+   * - `byte`: Base64-encoded data
+   * - `password`: Password fields (for documentation only)
+   */
+  export type Value =
+    | "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";
+}
+
+type PascalizeString<Key extends string> = Key extends `-${infer R}`
+  ? `${PascalizeString<R>}`
+  : Key extends `${infer _F}-${infer _R}`
+    ? PascalizeSnakeString<Key>
+    : Capitalize<Key>;
+type PascalizeSnakeString<Key extends string> = Key extends `-${infer R}`
+  ? PascalizeSnakeString<R>
+  : Key extends `${infer F}${infer M}-${infer R}`
+    ? `${Uppercase<F>}${Lowercase<M>}${PascalizeSnakeString<R>}`
+    : Key extends `${infer F}${infer R}`
+      ? `${Uppercase<F>}${Lowercase<R>}`
+      : Key;

package/src/tags/JsonSchemaPlugin.ts

@@ -0,0 +1,45 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Injects custom properties into generated JSON Schema.
+ *
+ * `JsonSchemaPlugin<Schema>` is a type tag that merges custom properties into
+ * the generated JSON Schema output. This enables vendor extensions (typically
+ * prefixed with `x-`) and custom metadata that tools in your ecosystem may
+ * require.
+ *
+ * This is metadata-only - it does not affect runtime validation. The properties
+ * are simply merged into the schema for the annotated type.
+ *
+ * Common use cases:
+ *
+ * - OpenAPI vendor extensions (`x-*` properties)
+ * - Custom UI hints for form generators
+ * - Tool-specific metadata
+ * - Integration with third-party schema consumers
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface FormField {
+ *     // Add custom UI hints for form generation
+ *     email: string &
+ *       Format<"email"> &
+ *       JsonSchemaPlugin<{
+ *         "x-ui-widget": "email-input";
+ *         "x-ui-placeholder": "Enter your email";
+ *       }>;
+ *     // Add custom sorting metadata
+ *     priority: number &
+ *       JsonSchemaPlugin<{
+ *         "x-sort-order": "descending";
+ *       }>;
+ *   }
+ *
+ * @template Schema Object type containing the custom properties to merge
+ */
+export type JsonSchemaPlugin<Schema extends object> = TagBase<{
+  target: "string" | "boolean" | "bigint" | "number" | "array" | "object";
+  kind: "jsonPlugin";
+  value: undefined;
+  schema: Schema;
+}>;

package/src/tags/MaxItems.ts

@@ -0,0 +1,39 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Array maximum items constraint.
+ *
+ * `MaxItems<N>` is a type tag that validates array values have at most the
+ * specified number of elements. Apply it to array properties using TypeScript
+ * intersection types.
+ *
+ * This constraint is commonly combined with {@link MinItems} to define a valid
+ * size range. It can also be combined with {@link UniqueItems} to require unique
+ * elements.
+ *
+ * The constraint is enforced at runtime by `typia.is()`, `typia.assert()`, and
+ * `typia.validate()`. It generates `maxItems` in JSON Schema output.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Upload {
+ *     // Maximum 5 files per upload
+ *     files: (File & MaxItems<5>)[];
+ *   }
+ *   interface Config {
+ *     // Between 1-3 backup servers allowed
+ *     backupServers: (Server & MinItems<1> & MaxItems<3>)[];
+ *   }
+ *
+ * @template Value Maximum number of elements allowed
+ */
+export type MaxItems<Value extends number> = TagBase<{
+  target: "array";
+  kind: "maxItems";
+  value: Value;
+  validate: `$input.length <= ${Value}`;
+  exclusive: true;
+  schema: {
+    maxItems: Value;
+  };
+}>;

package/src/tags/MaxLength.ts

@@ -0,0 +1,37 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * String maximum length constraint.
+ *
+ * `MaxLength<N>` is a type tag that validates string values have at most the
+ * specified number of characters. Apply it to `string` properties using
+ * TypeScript intersection types.
+ *
+ * This constraint is commonly combined with {@link MinLength} to define a valid
+ * length range. Multiple length constraints can be applied to the same property
+ * (all must pass).
+ *
+ * The constraint is enforced at runtime by `typia.is()`, `typia.assert()`, and
+ * `typia.validate()`. It generates `maxLength` in JSON Schema output.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Article {
+ *     // Title limited to 100 characters
+ *     title: string & MaxLength<100>;
+ *     // Description between 10-500 characters
+ *     description: string & MinLength<10> & MaxLength<500>;
+ *   }
+ *
+ * @template Value Maximum number of characters allowed
+ */
+export type MaxLength<Value extends number> = TagBase<{
+  target: "string";
+  kind: "maxLength";
+  value: Value;
+  validate: `$input.length <= ${Value}`;
+  exclusive: true;
+  schema: {
+    maxLength: Value;
+  };
+}>;

package/src/tags/Maximum.ts

@@ -0,0 +1,44 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Inclusive maximum value constraint (value <= max).
+ *
+ * `Maximum<N>` is a type tag that validates numeric values are less than or
+ * equal to the specified bound. Apply it to `number` or `bigint` properties
+ * using TypeScript intersection types.
+ *
+ * This constraint is **mutually exclusive** with {@link ExclusiveMaximum} - you
+ * cannot use both on the same property. Use `Maximum` for inclusive bounds (<=)
+ * and `ExclusiveMaximum` for exclusive bounds (<).
+ *
+ * The constraint is enforced at runtime by `typia.is()`, `typia.assert()`, and
+ * `typia.validate()`. It also generates `maximum` in JSON Schema output.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Rating {
+ *     // Score from 0-100
+ *     score: number & Minimum<0> & Maximum<100>;
+ *     // Percentage cannot exceed 1.0
+ *     ratio: number & Maximum<1.0>;
+ *   }
+ *
+ * @template Value The maximum allowed value (inclusive)
+ */
+export type Maximum<Value extends number | bigint> = TagBase<{
+  target: Value extends bigint ? "bigint" : "number";
+  kind: "maximum";
+  value: Value;
+  validate: `$input <= ${Cast<Value>}`;
+  exclusive: ["maximum", "exclusiveMaximum"];
+  schema: Value extends bigint
+    ? { maximum: Numeric<Value> }
+    : { maximum: Value };
+}>;
+
+type Cast<Value extends number | bigint> = Value extends number
+  ? Value
+  : `BigInt(${Value})`;
+type Numeric<T extends bigint> = `${T}` extends `${infer N extends number}`
+  ? N
+  : never;

package/src/tags/MinItems.ts

@@ -0,0 +1,39 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * Array minimum items constraint.
+ *
+ * `MinItems<N>` is a type tag that validates array values have at least the
+ * specified number of elements. Apply it to array properties using TypeScript
+ * intersection types.
+ *
+ * This constraint is commonly combined with {@link MaxItems} to define a valid
+ * size range. It can also be combined with {@link UniqueItems} to require unique
+ * elements.
+ *
+ * The constraint is enforced at runtime by `typia.is()`, `typia.assert()`, and
+ * `typia.validate()`. It generates `minItems` in JSON Schema output.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface Order {
+ *     // Must have at least 1 item
+ *     items: (Product & MinItems<1>)[];
+ *   }
+ *   interface Team {
+ *     // Team must have 2-10 members
+ *     members: (User & MinItems<2> & MaxItems<10>)[];
+ *   }
+ *
+ * @template Value Minimum number of elements required
+ */
+export type MinItems<Value extends number> = TagBase<{
+  target: "array";
+  kind: "minItems";
+  value: Value;
+  validate: `${Value} <= $input.length`;
+  exclusive: true;
+  schema: {
+    minItems: Value;
+  };
+}>;

package/src/tags/MinLength.ts

@@ -0,0 +1,37 @@
+import { TagBase } from "./TagBase";
+
+/**
+ * String minimum length constraint.
+ *
+ * `MinLength<N>` is a type tag that validates string values have at least the
+ * specified number of characters. Apply it to `string` properties using
+ * TypeScript intersection types.
+ *
+ * This constraint is commonly combined with {@link MaxLength} to define a valid
+ * length range. Multiple length constraints can be applied to the same property
+ * (all must pass).
+ *
+ * The constraint is enforced at runtime by `typia.is()`, `typia.assert()`, and
+ * `typia.validate()`. It generates `minLength` in JSON Schema output.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   interface User {
+ *     // Username must be at least 3 characters
+ *     username: string & MinLength<3> & MaxLength<20>;
+ *     // Password must be at least 8 characters
+ *     password: string & MinLength<8>;
+ *   }
+ *
+ * @template Value Minimum number of characters required
+ */
+export type MinLength<Value extends number> = TagBase<{
+  target: "string";
+  kind: "minLength";
+  value: Value;
+  validate: `${Value} <= $input.length`;
+  exclusive: true;
+  schema: {
+    minLength: Value;
+  };
+}>;