Validation Library for TypeScript and JavaScript

🔌 Integrates seamlessly into your projects — whether front-end or back-end — allowing you to define schemas intuitively while promoting reusability.

💡 Designed to combine simplicity and power, it offers advanced features like type inference and built-in validators such as isEmail, isUuid, and isIp.

Table of Contents

• Schema
  • Instances
  • Formats
  • Examples
• Testers
  • Object
  • String
• Helpers
  • Object
  • String

Installation

> npm install valia

import { Schema } from 'valia';

const userSchema = new Schema({ 
  type: "object",
  shape: {
    name: { type: "string" },
    role: {
      type: "string",
      literal: ["WORKER", "CUSTOMER"]
    }
  }
});

let data = {
  name: "Alice",
  role: "WORKER"
};

if (userSchema.validate(data)) {
  console.log(data.name, data.role);
}

import type { SchemaInfer } from 'valia';

type User = SchemaInfer<typeof userSchema>;

Schema

Instances

Schema

• criteria
  Property representing the root of the criteria nodes.
• validate(data)
  Method that validates the provided data according to the criteria and returns a boolean.
  This method uses TypeScript type predicates ↗.
• evaluate(data)
  Method that validates the provided data according to the criteria and returns an object with the following properties:
  • success: A boolean indicating whether validation succeeded.
  • rejection: Instance of SchemaDataRejection if the data was rejected, otherwise null.
  • admission: Instance of SchemaDataAdmission if the data was accepted, otherwise null.

SchemaException

• message
  Message describing the encountered issue.

SchemaNodeException

• code
  The exception code.
• message
  Message describing the encountered issue.
• node
  Node related to the exception.
• nodePath Path of the node related to the exception.
  • explicit: Array representing the path to the node in the criteria tree.
  • implicit: Array representing the virtual path to the data represented by the node.

SchemaDataRejection

• rootData
  Root of the data to be validated.
• rootNode
  Root node used for validation.
• rootLabel
  Label of the root node used for validation, or undefined if none was defined.
• data
  The rejected data.
• code
  Code associated with the rejection.
• node
  Node related to the rejection.
• nodePath
  Path of the node related to the rejection.
  • explicit: Array representing the path to the node in the criteria tree.
  • implicit: Array representing the virtual path to the data represented by the node.
• label
  Label defined on the node related to the rejection, or undefined if none was defined.
• message
  Message defined on the node related to the rejection, or undefined if none was defined.

SchemaDataAdmission

• data
  Root of the validated data.
• node
  Root node used for validation.
• label
  Label of the root node used for validation, or undefined if none was defined.

Formats

Number • String • Boolean • Object • Array • Function • Symbol • Union • Null • Undefined

Formats represent the criteria nodes that can be used within schemas.

The order of properties described for each format follows the order of validation.

Global

Properties:

• label?
  A string identifying the node. It will be returned in instances of SchemaDataRejection and SchemaNodeException.


• message?
  
  • string: A string that will be available in the SchemaDataRejection instance.
  • function: A function returning a string that will be available in the SchemaDataRejection instance.

Number

Properties:

• type: "number"


• min?
  Minimum value.


• max?
  Maximum value.


• literal?
  
  • number: Restricts the value to a single valid number.
  • array: Restricts the value to a list of valid numbers.
  • object: Restricts the value to an object whose values represent valid numbers.


• custom(value)?
  Custom validation function that receives the value as a parameter and must return a boolean indicating whether it is valid.

Examples:

Validate any number

const schema = new Schema({
  type: "number"
});

✅ schema.validate(0);
✅ schema.validate(10);
✅ schema.validate(-10);

Validate numbers within a specific range

const schema = new Schema({
  type: "number",
  min: 0,
  max: 10
});

✅ schema.validate(0);
✅ schema.validate(10);

❌ schema.validate(-1);
❌ schema.validate(11);

Validate a specific number

const schema = new Schema({
  type: "number",
  literal: 141
});

✅ schema.validate(141);

❌ schema.validate(-1);
❌ schema.validate(10);

Validate specific numbers using an array

const schema = new Schema({
  type: "number",
  literal: [141, 282]
});

✅ schema.validate(141);
✅ schema.validate(282);

❌ schema.validate(0);
❌ schema.validate(100);
❌ schema.validate(200);

String

Properties:

• type: "string"


• min?
  Minimum string length.


• max?
  Maximum string length.


• regex?
  A regular expression provided as a RegExp object.


• literal?
  
  • string: Restricts the value to a single valid string.
  • array: Restricts the value to a list of valid strings.
  • object: Restricts the value to an object whose values represent valid strings.


• constraint?
  An object whose keys correspond to string tester names and whose values can be:
  • boolean: Enables or disables the tester.
  • object: Enables the tester with the provided options.
  The value is considered valid if at least one tester returns a positive result.


• custom(value)?
  Custom validation function that receives the value as a parameter and must return a boolean indicating whether it is valid.

Examples:

Validate any string

const schema = new Schema({
  type: "string"
});

✅ schema.validate("");
✅ schema.validate("abc");

Validate strings with specific length

const schema = new Schema({
  type: "string",
  min: 3,
  max: 3
});

✅ schema.validate("abc");

❌ schema.validate("");
❌ schema.validate("a");
❌ schema.validate("abcd");

Validate strings using a regular expression

const schema = new Schema({
  type: "string",
  regex: /^#[a-fA-F0-9]{6}$/
});

✅ schema.validate("#000000");
✅ schema.validate("#FFFFFF");

❌ schema.validate("");
❌ schema.validate("#000");
❌ schema.validate("#FFF");

Validate a specific string

const schema = new Schema({
  type: "string",
  literal: "ABC"
});

✅ schema.validate("ABC");

❌ schema.validate("");
❌ schema.validate("a");
❌ schema.validate("abc");

Validate specific strings using an array

const schema = new Schema({
  type: "string",
  literal: ["ABC", "XYZ"]
});

✅ schema.validate("ABC");
✅ schema.validate("XYZ");

❌ schema.validate("");
❌ schema.validate("a");
❌ schema.validate("abc");

Validate strings using a string tester

const schema = new Schema({
  type: "string",
  constraint: {
    isIp: { cidr: true }
  }
});

✅ schema.validate("127.0.0.1/24");

❌ schema.validate("");
❌ schema.validate("127.0.0.1");

Validate strings using multiple testers

const schema = new Schema({
  type: "string",
  constraint: {
    isEmail: true,
    isIp: { cidr: true }
  }
});

✅ schema.validate("[email protected]");
✅ schema.validate("127.0.0.1/24");

❌ schema.validate("");
❌ schema.validate("foo@");
❌ schema.validate("127.0.0.1");

Boolean

Properties:

• type: "boolean"


• literal?
  Restricts the value to a single valid boolean state.


• custom(value)?
  Custom validation function that receives the value as a parameter and must return a boolean indicating whether it is valid.

Examples:

Validate any boolean

const schema = new Schema({
  type: "boolean"
});

✅ schema.validate(true);
✅ schema.validate(false);

❌ schema.validate("");
❌ schema.validate({});

Validate a specific boolean

const schema = new Schema({
  type: "boolean",
  literal: true
});

✅ schema.validate(true);

❌ schema.validate("");
❌ schema.validate({});
❌ schema.validate(false);

Object

Properties:

• type: "object"


• nature? — (Default: "STANDARD")
  • "STANDARD": Accepts any value of type object, that is, any value for which typeof value === "object".
  • "PLAIN": Accepts only plain objects whose prototype is either Object.prototype (e.g. created via {}) or null (created via Object.create(null)).


• min?
  Minimum number of properties.


• max?
  Maximum number of properties.


• shape?
  An object whose keys are of type string or symbol, and whose values are criteria nodes. Represents fixed properties that the object must satisfy.


• optional? — (Default: false | Only usable if shape is defined)
  • boolean
    • true: All properties defined in the shape object are optional.
    • false: All properties defined in the shape object are required.
  • array
    An array whose elements are keys of the shape object that should be optional.


• keys?
  Criteria node that object keys must satisfy.
  Keys defined in the shape object are not affected.


• values?
  Criteria node that object values must satisfy.
  Values defined in the shape object are not affected.

Examples:

Validate any object

const schema = new Schema({
  type: "object"
});

✅ schema.validate({});
✅ schema.validate([]);
✅ schema.validate(new Date());
✅ schema.validate(Object.create(null));

❌ schema.validate("");

Validate a plain object

const schema = new Schema({
  type: "object",
  nature: "PLAIN"
});

✅ schema.validate({});
✅ schema.validate(Object.create(null));

❌ schema.validate("");
❌ schema.validate([]);
❌ schema.validate(new Date());

Validate an object with fixed properties

const schema = new Schema({
  type: "object",
  shape: {
    foo: { type: "string" },
    bar: { type: "string" }
  }
});

✅ schema.validate({ foo: "x", bar: "x" });

❌ schema.validate({});
❌ schema.validate({ foo: "x" });
❌ schema.validate({ bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", a: "" });

Validate an object with nested fixed properties

const schema = new Schema({
  type: "object",
  shape: {
    foo: { type: "string" },
    bar: { type: "string" },
    baz: {
      foo: { type: "number" },
      bar: { type: "number" }
    }
  }
});

✅ schema.validate({ foo: "x", bar: "x", baz: { foo: 0, bar: 0 } });

❌ schema.validate({});
❌ schema.validate({ foo: "x" });
❌ schema.validate({ foo: "x", bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", baz: {} });
❌ schema.validate({ foo: "x", bar: "x", baz: { foo: 0 } });

Validate an object with optional properties

const schema = new Schema({
  type: "object",
  shape: {
    foo: { type: "string" },
    bar: { type: "string" }
  },
  optional: true
});

✅ schema.validate({});
✅ schema.validate({ foo: "x" });
✅ schema.validate({ bar: "x" });
✅ schema.validate({ foo: "x", bar: "x" });

❌ schema.validate({ foo: "x", bar: "x", a: "x" });

Validate an object with one fixed and one optional property

const schema = new Schema({
  type: "object",
  shape: {
    foo: { type: "string" },
    bar: { type: "string" }
  },
  optional: ["bar"]
});

✅ schema.validate({ foo: "x" });
✅ schema.validate({ foo: "x", bar: "x" });

❌ schema.validate({});
❌ schema.validate({ bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", a: "x" });

Validate an object with fixed and dynamic free properties

const schema = new Schema({
  type: "object",
  shape: {
    foo: { type: "string" },
    bar: { type: "string" }
  },
  values: { type: "unknown" }
});

✅ schema.validate({ foo: "x", bar: "x" });
✅ schema.validate({ foo: "x", bar: "x", a: "x", b: 0 });

❌ schema.validate({});
❌ schema.validate({ bar: "x" });
❌ schema.validate({ foo: "x" });

Validate an object with fixed and constrained dynamic properties

const schema = new Schema({
  type: "object",
  shape: {
    foo: { type: "string" },
    bar: { type: "string" }
  },
  keys: { type: "string" },
  values: { type: "number" }
});

✅ schema.validate({ foo: "x", bar: "x" });
✅ schema.validate({ foo: "x", bar: "x", a: 0 });
✅ schema.validate({ foo: "x", bar: "x", a: 0, b: 0 });

❌ schema.validate({});
❌ schema.validate({ foo: "x" });
❌ schema.validate({ bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", a: "x", b: 0 });

Validate an object with constrained dynamic properties

const schema = new Schema({
  type: "object",
  keys: { type: "string" },
  values: { type: "string" }
});

✅ schema.validate({});
✅ schema.validate({ a: "x" });
✅ schema.validate({ a: "x", b: "x" });

❌ schema.validate({ a: 0 });
❌ schema.validate({ a: "x", b: 0 });

Array

Properties:

• type: "array"


• min?
  Minimum number of elements.


• max?
  Maximum number of elements.


• tuple?
  An array whose elements are criteria nodes. Represents fixed elements the array must satisfy.


• items?
  Criteria node that array elements must satisfy.
  Elements defined in the tuple array are not affected.

Examples:

Validate any array

const schema = new Schema({
  type: "array"
});

✅ schema.validate([]);
✅ schema.validate(["x"]);

❌ schema.validate({});
❌ schema.validate("x");

Validate an array with fixed elements

const schema = new Schema({
  type: "array",
  tuple: [
    { type: "string" },
    { type: "string" }
  ]
});

✅ schema.validate(["x", "x"]);

❌ schema.validate([]);
❌ schema.validate(["x"]);
❌ schema.validate(["x", "x", "x"]);

Validate a nested array with fixed elements

const schema = new Schema({
  type: "array",
  tuple: [
    { type: "string" },
    { type: "string" },
    [
      { type: "number" },
      { type: "number" }
    ]
  ]
});

✅ schema.validate(["x", "x", [0, 0]]);

❌ schema.validate([]);
❌ schema.validate(["x"]);
❌ schema.validate(["x", "x", []]);
❌ schema.validate(["x", "x", [0]]);

Validate an array with fixed and free dynamic elements

const schema = new Schema({
  type: "array",
  tuple: [
    { type: "string" },
    { type: "string" }
  ],
  items: { type: "unknown" }
});

✅ schema.validate(["x", "x"]);
✅ schema.validate(["x", "x", 0]);
✅ schema.validate(["x", "x", ""]);
✅ schema.validate(["x", "x", {}]);

❌ schema.validate([]);
❌ schema.validate(["x"]);
❌ schema.validate([0, "x"]);

Validate an array with fixed and constrained dynamic elements

const schema = new Schema({
  type: "array",
  tuple: [
    { type: "string" },
    { type: "string" }
  ],
  items: { type: "number" }
});

✅ schema.validate(["x", "x"]);
✅ schema.validate(["x", "x", 0]);
✅ schema.validate(["x", "x", 0, 0]);

❌ schema.validate([]);
❌ schema.validate(["x"]);
❌ schema.validate(["x", "x", "x"]);

Validate an array with constrained dynamic elements

const schema = new Schema({
  type: "array",
  items: { type: "string" }
});

✅ schema.validate([]);
✅ schema.validate(["x"]);
✅ schema.validate(["x", "x"]);

❌ schema.validate([0]);
❌ schema.validate(["x", 0]);
❌ schema.validate(["x", "x", 0]);

Symbol

Properties:

• type: "symbol"


• literal?
  
  • symbol: Restricts the value to a single valid symbol.
  • array: Restricts the value to an array of valid symbols.
  • object: Restricts the value to an object whose values represent valid symbols.


• custom(value)?
  Custom validation function that receives the value as a parameter and must return a boolean indicating whether it is valid.

Examples:

Validate any symbol

const xSymbol = Symbol("x");
const ySymbol = Symbol("y");

const schema = new Schema({
  type: "symbol"
});

✅ schema.validate(xSymbol);
✅ schema.validate(ySymbol);

Validate a specific symbol

const xSymbol = Symbol("x");
const ySymbol = Symbol("y");

const schema = new Schema({
  type: "symbol",
  literal: xSymbol
});

✅ schema.validate(xSymbol);

❌ schema.validate(ySymbol);

Validate specific symbols using an array

const xSymbol = Symbol("x");
const ySymbol = Symbol("y");
const zSymbol = Symbol("z");

const schema = new Schema({
  type: "symbol",
  literal: [xSymbol, ySymbol]
});

✅ schema.validate(xSymbol);
✅ schema.validate(ySymbol);

❌ schema.validate(zSymbol);

Validate specific symbols using an enum

enum mySymbol {
  X = Symbol("x"),
  Y = Symbol("y")
};

enum otherSymbol {
  Z = Symbol("z")
};

const schema = new Schema({
  type: "symbol",
  literal: mySymbol
});

✅ schema.validate(mySymbol.X);
✅ schema.validate(mySymbol.Y);

❌ schema.validate(otherSymbol.Z);

Union

Properties:

• union
  An array of criteria nodes, where each node defines an acceptable value.
  A value is considered valid if it matches at least one of the provided nodes.

Examples:

const schema = new Schema({
  type: "union",
  union: [
    { type: "string" },
    { type: "number" }
  ]
});

✅ schema.validate(0);
✅ schema.validate("");

❌ schema.validate({});

Null

Properties:

• type: "null"

Examples:

const schema = new Schema({
  type: "null"
});

✅ schema.validate(null);

❌ schema.validate(0);
❌ schema.validate("");
❌ schema.validate({});

Undefined

Properties:

• type: "undefined"

Examples:

const schema = new Schema({
  type: "undefined"
});

✅ schema.validate(undefined);

❌ schema.validate(0);
❌ schema.validate("");
❌ schema.validate({});

Examples

Simple schema

const user = new Schema({ 
  type: "object",
  shape: {
    name: {
      type: "string",
      min: 3,
      max: 32
    },
    role: {
      type: "string",
      literal: ["WORKER", "CUSTOMER"]
    }
  }
});

✅ user.validate({
  name: "Alice",
  role: "WORKER"
});

❌ user.validate({
  name: "Alice",
  role: "MANAGER"
});

Composite schema

const name = new Schema({
  type: "string",
  min: 3,
  max: 32
});

const role = new Schema({
  type: "string",
  literal: ["WORKER", "CUSTOMER"]
});

const user = new Schema({ 
  type: "object",
  shape: {
    name: name.criteria,
    role: role.criteria
  }
});

✅ user.validate({
  name: "Bob",
  role: "CUSTOMER"
});

❌ user.validate({
  name: "Bob",
  role: "MANAGER"
});

Deep composite schema

const name = new Schema({
  type: "string",
  min: 3,
  max: 32
});

const setting = new Schema({
  type: "object",
  shape: {
    theme: {
      type: "string",
      literal: ["DARK", "LIGHT"]
    },
    notification: { type: "boolean" }
  }
});

const user = new Schema({ 
  type: "object",
  object: {
    name: name.criteria,
    theme: setting.criteria.shape.theme
  }
});

✅ user.validate({
  name: "Alice",
  theme: "DARK"
});

❌ user.validate({
  name: "Alice",
  theme: "DEFAULT"
});

Testers

Object

isObject(value): boolean

Checks if the provided value is of type object.

isPlainObject(value): boolean

Checks if the provided value is an object whose prototype is either Object.prototype or null. For example, values created using the literal {} or Object.create(null) are accepted.

isArray(value): boolean

Checks if the provided value is an array.

isTypedArray(value): boolean

Checks if the provided value is a typed array, i.e., a view on an ArrayBuffer, except for DataView.

isFunction(value): boolean

Checks if the provided value is a function.

isBasicFunction(value): boolean

Checks if the provided value is a function that is not async, generator, or async generator.

isAsyncFunction(value): boolean

Checks if the provided value is an async function.

isGeneratorFunction(value): boolean

Checks if the provided value is a generator function.

isAsyncGeneratorFunction(value): boolean

Checks if the provided value is an async generator function.

String

isAscii(str): boolean

Checks if the provided string contains only ASCII characters.

isIpV4(str [, options]): boolean

Checks if the provided string is a valid IPv4 address.

isIpV6(str [, options]): boolean

Checks if the provided string is a valid IPv6 address.

isIp(str [, options]): boolean

Checks if the provided string is a valid IPv4 or IPv6 address.

Options:

• cidr? — (Default: false)
  If true, requires a CIDR suffix. If false, CIDR suffixes are not allowed.

isEmail(str [, options]): boolean

Checks if the provided string is a valid email address.

Options:

• allowLocalQuotes?: boolean — (Default: false)
  Specifies whether the local part of the email can use quotes. For example, "John Doe"@example.com would be considered valid.
• allowIpAddress?: boolean — (Default: false)
  Specifies whether the domain part of the email can be an IP address. For example, [email protected] would be valid.
• allowGeneralAddress?: boolean — (Default: false)
  Specifies whether the domain part of the email can be a general address. For example, foo@server would be valid.

Standard: RFC 5321

isDomain(str): boolean

Checks if the provided string is a valid domain name.

Standard: RFC 1035

isDataURL(str [, options]): boolean

Checks if the provided string is a valid DataURL.

Options:

• type?: string[]
  Specifies one or more allowed MIME types. List of IANA-registered MIME types ↗
• subtype?: string[]
  Specifies one or more allowed MIME subtypes. List of IANA-registered MIME types ↗

Standard: RFC 2397

isUuid(str [, options]): boolean

Checks if the provided string is a valid UUID.

Options:

• version?: number
  Specifies the allowed version number, between 1 and 7.

Standard: RFC 9562

isBase16(str): boolean

Checks if the provided string is a valid base16 encoding.

Standard: RFC 4648

isBase32(str): boolean

Checks if the provided string is a valid base32 encoding.

Standard: RFC 4648

isBase32Hex(str): boolean

Checks if the provided string is a valid base32Hex encoding.

Standard: RFC 4648

isBase64(str): boolean

Checks if the provided string is a valid base64 encoding.

Standard: RFC 4648

isBase64Url(str): boolean

Checks if the provided string is a valid base64Url encoding.

Standard: RFC 4648

Helpers

String

base16ToBase32(str [, to, padding]): string

Converts a base16 string into a base32 or base32Hex string.

Arguments:

• to?: "B32" | "B32HEX" — (Default: "B32")
  Specifies the target encoding format.


• padding?: boolean — (Default: true)
  Specifies whether padding should be added if required.

Standard: RFC 4648

base16ToBase64(str [, to, padding]): string

Converts a base16 string into a base64 or base64Url string.

Arguments:

• to?: "B64" | "B64URL" — (Default: "B64")
  Specifies the target encoding format.


• padding?: boolean — (Default: true)
  Specifies whether padding should be added if required.

Standard: RFC 4648

base32ToBase16(str [, from]): string

Converts a base32 or base32Hex string into a base16 string.

Arguments:

• from?: "B32" | "B32HEX" — (Default: "B32")
  Specifies the source encoding format.

Standard: RFC 4648

base64ToBase16(str [, from]): string

Converts a base64 or base64Url string into a base16 string.

Arguments:

• from?: "B64" | "B64URL" — (Default: "B64")
  Specifies the source encoding format.

Object

getInternalTag(target): string

Returns the internal tag of the target. For example, for async () => {}, the returned tag would be "AsyncFunction".