validate()
function
undefined
export function validate<T>(input: T): IValidation<T>;
export function validate<T>(input: unknown): IValidation<T>;
Validates a value type.
typia.validate<T>()
function validates input
value type, and archives every type errors detaily into IValidation.IFailure.errors
array, when the input
value is not following the promised type T
. Of course, if the parametric input
value is following the type T
, IValidation.ISuccess
instance would be returned.
In the below example case, as id
and age
values are different with its definition of IMember
, such errors would be archived into the IValidation.IFailure.errors
array.
errors[0]
path
:input.id
expected
:string & Format<"uuid">
value
: 5
errors[1]
path
:input.age
expected
:number & Format<"uint32">
value
: 20.75
TypeScript Source Code
import typia, { tags } from "typia";
const res: typia.IValidation<IMember> = typia.validate<IMember>({
id: 5, // wrong, must be string (uuid)
age: 20.75, // wrong, not integer
email: "samchon.github@gmail.com",
});
if (res.success === false) console.log(res.errors);
interface IMember {
id: string & tags.Format<"uuid">;
email: string & tags.Format<"email">;
age: number &
tags.Type<"uint32"> &
tags.ExclusiveMinimum<19> &
tags.Maximum<100>;
}
validateEquals()
function
undefined
export function validateEquals<T>(input: T): IValidation<T>;
export function validateEquals<T>(input: unknown): IValidation<T>;
More strict validate function prohibiting superfluous properties.
typia.validate<T>
function detects every type errors of input
value, however, it can’t detect superfluous properties. If you want to prohibit those superfluous properties, so that archive them into IValidation.IFailure.errors
array, use typia.validateEquals<T>()
function instead.
In the below example case, as id
property is different with its type definition and sex
property is not defined in the IMember
type, such errors would be archived into the IValidation.IFailure.errors
array:
errors[0]
path
:input.id
expected
:string (@format uuid)
value
:something
errors[1]
path
:input.sex
expected
:undefined
value
:1
TypeScript Source Code
import typia, { tags } from "typia";
const res: typia.IValidation<IMember> = typia.validateEquals<IMember>({
age: 30,
email: "samchon.github@gmail.com",
id: "something", // wrong, must be string (uuid)
sex: 1, // extra property
});
if (res.success === false) console.log(res.errors);
interface IMember {
id: string & tags.Format<"uuid">;
email: string & tags.Format<"email">;
age: number &
tags.Type<"uint32"> &
tags.ExclusiveMinimum<19> &
tags.Maximum<100>;
}
Reusable functions
undefined
export function createValidate<T> = (input: unknown) => IValidation<T> & StandardSchemaV1<unknown, T>;
export function createValidateEquals<T> = (input: unknown) => IValidation<T> & StandardSchemaV1<unknown, T>;
Reusable typia.validate<T>()
function generators.
If you repeat to call typia.validate<T>()
function on the same type, size of JavaScript files would be larger because of duplicated AOT compilation. To prevent it, you can generate reusable function through typia.createValidate<T>()
function.
Just look at the code below, then you may understand how to use it.
TypeScript Source Code
import typia, { tags } from "typia";
export const validateMember = typia.createValidate<IMember>();
interface IMember {
id: string & tags.Format<"uuid">;
email: string & tags.Format<"email">;
age: number &
tags.Type<"uint32"> &
tags.ExclusiveMinimum<19> &
tags.Maximum<100>;
}
This reusable function implements Standard Schema  interface. Therefore, you can use this function with a library which accepts Standard Schema interface , such as upfetch :
import typia from "typia";
import { up } from "up-fetch";
const upfetch = up(fetch);
const schema = typia.createValidate<ISmallTodo>();
// passes
await upfetch("https://jsonplaceholder.typicode.com/todos/1", {
schema,
});
// fails
await upfetch("https://jsonplaceholder.typicode.com/todos/10", {
schema,
})
interface ISmallTodo {
userId: number;
/** @maximum 5 */
id: number;
title: string;
completed: boolean;
}
Restrictions
typia.validate<T>()
function does not check function
and user-defined class
types.
It validates only the primitive properties. Therefore, typia.validate<T>()
function does not perform the instanceof ClassName
for user-defined classes. If you want to validate the user-defined class type in addition to the property types, do it by yourself. Also, typia.validate<T>()
function does not validate the function type either, unless configuring functional
property of plugin
option in the tsconfig.json
file.
{
"compilerOptions": {
"plugins": [
{
"transform": "typia/lib/transform",
"functional": true
}
]
}
}
By the way, there’re some exception cases.
If JS native class type like Date
, Uint8Array
, or Map<Key, T>
being utilized, typia.validate<T>()
function validates them. Especially about the Set<T>
, and Map<Key, T>
class cases, typia.validate<T>()
function validates all of their contained element types, too.
Therefore, the instanceof
statement does not be used only for the user-defined classes.
TypeScript Source Code
import typia from "typia";
typia.createIs<Map<string, boolean | number | string>>();
Discriminated Union
undefined
/**
* Union type representing the result of type validation
*
* This is the return type of {@link typia.validate} functions, returning
* {@link IValidation.ISuccess} on validation success and
* {@link IValidation.IFailure} on validation failure. When validation fails, it
* provides detailed, granular error information that precisely describes what
* went wrong, where it went wrong, and what was expected.
*
* This comprehensive error reporting makes `IValidation` particularly valuable
* for AI function calling scenarios, where Large Language Models (LLMs) need
* specific feedback to correct their parameter generation. The detailed error
* information is used by ILlmFunction.validate() to provide validation feedback
* to AI agents, enabling iterative correction and improvement of function
* calling accuracy.
*
* This type uses the Discriminated Union pattern, allowing type specification
* through the success property:
*
* ```typescript
* const result = typia.validate<string>(input);
* if (result.success) {
* // IValidation.ISuccess<string> type
* console.log(result.data); // validated data accessible
* } else {
* // IValidation.IFailure type
* console.log(result.errors); // detailed error information accessible
* }
* ```
*
* @author Jeongho Nam - https://github.com/samchon
* @template T The type to validate
*/
export type IValidation<T = unknown> =
| IValidation.ISuccess<T>
| IValidation.IFailure;
export namespace IValidation {
/**
* Interface returned when type validation succeeds
*
* Returned when the input value perfectly conforms to the specified type T.
* Since success is true, TypeScript's type guard allows safe access to the
* validated data through the data property.
*
* @template T The validated type
*/
export interface ISuccess<T = unknown> {
/** Indicates validation success */
success: true;
/** The validated data of type T */
data: T;
}
/**
* Interface returned when type validation fails
*
* Returned when the input value does not conform to the expected type.
* Contains comprehensive error information designed to be easily understood
* by both humans and AI systems. Each error in the errors array provides
* precise details about validation failures, including the exact path to the
* problematic property, what type was expected, and what value was actually
* provided.
*
* This detailed error structure is specifically optimized for AI function
* calling validation feedback. When LLMs make type errors during function
* calling, these granular error reports enable the AI to understand exactly
* what went wrong and how to fix it, improving success rates in subsequent
* attempts.
*
* Example error scenarios:
*
* - Type mismatch: expected "string" but got number 5
* - Format violation: expected "string & Format<'uuid'>" but got
* "invalid-format"
* - Missing properties: expected "required property 'name'" but got undefined
* - Array type errors: expected "Array<string>" but got single string value
*
* The errors are used by ILlmFunction.validate() to provide structured
* feedback to AI agents, enabling them to correct their parameter generation
* and achieve improved function calling accuracy.
*/
export interface IFailure {
/** Indicates validation failure */
success: false;
/** The original input data that failed validation */
data: unknown;
/** Array of detailed validation errors */
errors: IError[];
}
/**
* Detailed information about a specific validation error
*
* Each error provides granular, actionable information about validation
* failures, designed to be immediately useful for both human developers and
* AI systems. The error structure follows a consistent format that enables
* precise identification and correction of type mismatches.
*
* This error format is particularly valuable for AI function calling
* scenarios, where LLMs need to understand exactly what went wrong to
* generate correct parameters. The combination of path, expected type name,
* actual value, and optional human-readable description provides the AI with
* comprehensive context to make accurate corrections, which is why
* ILlmFunction.validate() can achieve such high success rates in validation
* feedback loops.
*
* The value field can contain any type of data, including `undefined` when
* dealing with missing required properties or null/undefined validation
* scenarios. This allows for precise error reporting in cases where the AI
* agent omits required fields or provides null/undefined values
* inappropriately.
*
* Real-world examples from AI function calling:
*
* {
* path: "$input.member.age",
* expected: "number",
* value: "25" // AI provided string instead of number
* }
*
* {
* path: "$input.count",
* expected: "number & Type<'uint32'>",
* value: 20.75 // AI provided float instead of uint32
* }
*
* {
* path: "$input.categories",
* expected: "Array<string>",
* value: "technology" // AI provided string instead of array
* }
*
* {
* path: "$input.id",
* expected: "string & Format<'uuid'>",
* value: "invalid-uuid-format" // AI provided malformed UUID
* }
*
* {
* path: "$input.user.name",
* expected: "string",
* value: undefined // AI omitted required property
* }
*/
export interface IError {
/**
* The path to the property that failed validation
*
* Dot-notation path using $input prefix indicating the exact location of
* the validation failure within the input object structure. Examples
* include "$input.member.age", "$input.categories[0]",
* "$input.user.profile.email"
*/
path: string;
/**
* The expected type name or type expression
*
* Technical type specification that describes what type was expected at
* this path. This follows TypeScript-like syntax with embedded constraint
* information, such as "string", "number & Type<'uint32'>",
* "Array<string>", "string & Format<'uuid'> & MinLength<8>", etc.
*/
expected: string;
/**
* The actual value that caused the validation failure
*
* This field contains the actual value that was provided but failed
* validation. Note that this value can be `undefined` in cases where a
* required property is missing or when validating against undefined
* values.
*/
value: unknown;
/**
* Optional human-readable description of the validation error
*
* This field is rarely populated in standard typia validation and is
* primarily intended for specialized AI agent libraries or custom
* validation scenarios that require additional context beyond the technical
* type information. Most validation errors rely solely on the path,
* expected, and value fields for comprehensive error reporting.
*/
description?: string;
}
}
Specify type through if condition.
typia.IValidation<T>
is an union type of typia.IValidation.ISuccess<T>
and typia.IValidation.IFailure
. Also, they have a common property success
of boolean type, but different literal values. In that case, if you write a if condition
about the success
property, you can specify the union type like below.
In TypeScript, such union type specification through common property (of different literal value() is called “Discriminated Union”. Therefore, when using typia.validate<T>()
function, let’s utilize such discriminated union specification for convenience.
import typia from "typia";
const something: unknown = ...;
const result: typia.IValidation<string> = typia.validate<string>(something);
if (results.success) {
// become typia.IValidation.Success<string> type
result.data; // accessible
} else {
// become typia.IValidation.Failure type
result.errors; //accessible
}
Customization
You can enhance validation logic by special tags.
Also, with those tags, you can add your custom validation logic, too.
If you want to know about such special tags detaily, read below article:
TypeScript Source Code
import typia, { tags } from "typia";
export const validateSomething = typia.createValidate<Something>();
//----
// DEFINE CUSTOM TYPE TAGS
//----
type Dollar = tags.TagBase<{
kind: "dollar";
target: "string";
value: undefined;
validate: `$input[0] === "$" && !isNaN(Number($input.substring(1).split(",").join("")))`;
}>;
type Postfix<Value extends string> = tags.TagBase<{
kind: "postfix";
target: "string";
value: Value;
validate: `$input.endsWith("${Value}")`;
}>;
type IsEven<Value extends number | bigint> = tags.TagBase<{
kind: "isEven";
target: Value extends number ? "number" : "bigint";
value: undefined;
validate: `$input % ${Numeric<2>} === ${Numeric<0>}`;
}>;
type Numeric<Value extends number | bigint> = Value extends number
? Value
: `BigInt(${Value})`;
//----
// VALIDATION
//----
interface Something {
dollar: string & Dollar;
postfix: string & Postfix<"!!!">;
isEven: number & IsEven<number>;
}
Performance
Super-fast and super-safe.
Comparing typia.validate<T>()
function with other competitive libraries, maximum 20,000x faster.
Furthermore, only typia
can validate complicate union types.
Measured on AMD Ryzen 9 7940HS, Rog Flow x13 
Components | typia | TypeBox | ajv | io-ts | zod | C.V. |
---|---|---|---|---|---|---|
Easy to use | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Object (simple)  | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
Object (hierarchical)  | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
Object (recursive)  | ✔ | ❌ | ✔ | ✔ | ✔ | ✔ |
Object (union, implicit)  | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Object (union, explicit)  | ✔ | ✔ | ✔ | ✔ | ✔ | ❌ |
Object (additional tags)  | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
Object (template literal types)  | ✔ | ✔ | ✔ | ❌ | ❌ | ❌ |
Object (dynamic properties)  | ✔ | ✔ | ✔ | ❌ | ❌ | ❌ |
Array (rest tuple)  | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Array (hierarchical)  | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
Array (recursive)  | ✔ | ✔ | ✔ | ✔ | ✔ | ❌ |
Array (recursive, union)  | ✔ | ✔ | ❌ | ✔ | ✔ | ❌ |
Array (R+U, implicit)  | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Array (repeated)  | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Array (repeated, union)  | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Ultimate Union Type | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
C.V.
meansclass-validator