Interface: ValidationRoot

Extended Joi root interface that includes custom schema types for additional validation scenarios.

This interface extends the standard Joi Root interface to include additional schema types

Example

import { validator } from "@nhtio/validation";

const schema = validator.object({
  id: validator.bigint().positive().required(),
  balance: validator.bigint().min(0n).optional(),
});

Extends

• Omit<Root, | "allow" | "alt" | "alternatives" | "any" | "array" | "binary" | "bool" | "boolean" | "date" | "disallow" | "equal" | "exist" | "forbidden" | "func" | "function" | "invalid" | "link" | "not" | "number" | "object" | "optional" | "preferences" | "prefs" | "required" | "string" | "symbol" | "types" | "valid" | "when" | "ref">

Properties

| Property | Type | Description | Inherited from | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | | $clearI18n | () => ValidationRoot | Clears the global internationalization callback. This method removes any previously set global i18n callback, causing the $i18n method to fall back to default English messages for validator instances that haven't had their own callback set via $setI18n. This is useful for testing scenarios, dynamic language switching, or memory cleanup when you no longer need global translations. Example // Set up global translations validator.$setGlobalI18n(spanishCallback) // Later, clear them to return to default English validator.$clearGlobalI18n() // Now all validators use default English messages again const schema = validator.string().min(5) // Uses English messages | - | | $i18n | I18nCallback | - | - | | $setI18n | SetI18nCallback<ValidationRoot> | Sets a global internationalization callback that applies to all validator instances. This method sets a fallback translation function that will be used by the $i18n method when no instance-specific callback has been set via $setI18n. Once $setI18n is called on an instance, that instance will use its own callback instead of the global one. The global callback provides a convenient way to set default translations across your entire application while still allowing individual validator instances to override with their own translations when needed. Param The I18nCallback function that will handle global message translation Example // Set up global Spanish translations validator.$setGlobalI18n((term: string) => { return spanishTranslations[term] | | term }) // All validators will now use Spanish by default const schema1 = validator.string().min(5) const schema2 = validator.number().positive() // But you can still override for specific instances const germanSchema = validator.string().$setI18n(germanCallback) | - | | cache | CacheConfiguration | - | Root.cache | | override | symbol | A special value used with any.allow(), any.invalid(), and any.valid() as the first value to reset any previously set values. | Root.override | | ValidationError | (message: string, details: ValidationErrorItem_2[], original: any) => ValidationError_2 | - | Root.ValidationError | | version | string | Current version of the joi package. | Root.version |

Methods

allow()

allow(...values: any[]): Schema;

Whitelists a value

Parameters

Parameter	Type
...values	any[]

Returns

Schema

---

alt()

Call Signature

alt<TSchema>(types: SchemaLike_2<any>[]): AlternativesSchema<TSchema>;

Alias for alternatives

Type Parameters

Type Parameter	Default type
TSchema	any

Parameters

Parameter	Type
types	SchemaLike_2<any>[]

Returns

AlternativesSchema<TSchema>

Call Signature

alt<TSchema>(...types: SchemaLike_2<any>[]): AlternativesSchema<TSchema>;

Type Parameters

Type Parameter	Default type
TSchema	any

Parameters

Parameter	Type
...types	SchemaLike_2<any>[]

Returns

AlternativesSchema<TSchema>

---

alternatives()

Call Signature

alternatives<TSchema>(types: SchemaLike_2<any>[]): AlternativesSchema<TSchema>;

Generates a type that will match one of the provided alternative schemas

Type Parameters

Type Parameter	Default type
TSchema	any

Parameters

Parameter	Type
types	SchemaLike_2<any>[]

Returns

AlternativesSchema<TSchema>

Call Signature

alternatives<TSchema>(...types: SchemaLike_2<any>[]): AlternativesSchema<TSchema>;

Type Parameters

Type Parameter	Default type
TSchema	any

Parameters

Parameter	Type
...types	SchemaLike_2<any>[]

Returns

AlternativesSchema<TSchema>

---

any()

any<TSchema>(): AnySchema<TSchema>;

Generates a schema object that matches any data type.

Type Parameters

Type Parameter	Default type
TSchema	any

Returns

AnySchema<TSchema>

---

array()

array<TSchema>(): ArraySchema<TSchema>;

Generates a schema object that matches an array data type.

Type Parameters

Type Parameter	Default type
TSchema	any[]

Returns

ArraySchema<TSchema>

---

assert()

Call Signature

assert(
   value: any,
   schema: Schema_2,
   options?: ValidationOptions): void;

Validates a value against a schema and throws if validation fails.

Parameters

Parameter	Type	Description
value	any	the value to validate.
schema	Schema_2	the schema object.
options?	ValidationOptions	optional validation options. An overload also accepts a message argument in third position — a message string prefix added in front of the error message, which may also be an Error object — followed by the optional options.

Returns

void

Inherited from

Root.assert

Call Signature

assert(
   value: any,
   schema: Schema_2,
   message: string | Error,
   options?: ValidationOptions): void;

Parameters

Parameter	Type
value	any
schema	Schema_2
message	string | Error
options?	ValidationOptions

Returns

void

Inherited from

Root.assert

---

attempt()

Call Signature

attempt<TSchema>(
   value: any,
   schema: TSchema,
   options?: ValidationOptions): TSchema extends Schema_2<Value> ? Value : never;

Validates a value against a schema, returns valid object, and throws if validation fails.

Type Parameters

Type Parameter
TSchema extends Schema_2<any>

Parameters

Parameter	Type	Description
value	any	the value to validate.
schema	TSchema	the schema object.
options?	ValidationOptions	optional validation options. An overload also accepts a message argument in third position — a message string prefix added in front of the error message, which may also be an Error object — followed by the optional options.

Returns

TSchema extends Schema_2<Value> ? Value : never

Inherited from

Root.attempt

Call Signature

attempt<TSchema>(
   value: any,
   schema: TSchema,
   message: string | Error,
   options?: ValidationOptions): TSchema extends Schema_2<Value> ? Value : never;

Type Parameters

Type Parameter
TSchema extends Schema_2<any>

Parameters

Parameter	Type
value	any
schema	TSchema
message	string | Error
options?	ValidationOptions

Returns

TSchema extends Schema_2<Value> ? Value : never

Inherited from

Root.attempt

---

bigint()

bigint<TSchema>(): BigIntSchema<TSchema>;

Generates a schema object that matches a BigInt data type.

Type Parameters

Type Parameter	Default type
TSchema	bigint

Returns

BigIntSchema<TSchema>

---

binary()

binary<TSchema>(): BinarySchema<TSchema>;

Generates a schema object that matches a Buffer data type (as well as the strings which will be converted to Buffers).

Type Parameters

Type Parameter	Default type
TSchema	Buffer<ArrayBufferLike>

Returns

BinarySchema<TSchema>

---

bool()

bool<TSchema>(): BooleanSchema<TSchema>;

Generates a schema object that matches a boolean data type (as well as the strings 'true', 'false', 'yes', and 'no'). Can also be called via boolean().

Type Parameters

Type Parameter	Default type
TSchema	boolean

Returns

BooleanSchema<TSchema>

---

boolean()

boolean<TSchema>(): BooleanSchema<TSchema>;

Generates a schema object that matches a boolean data type (as well as the strings 'true', 'false', 'yes', and 'no'). Can also be called via bool().

Type Parameters

Type Parameter	Default type
TSchema	boolean

Returns

BooleanSchema<TSchema>

---

build()

build(...args: any[]): any;

Unsure, maybe alias for compile?

Parameters

Parameter	Type
...args	any[]

Returns

any

Inherited from

Root.build

---

checkPreferences()

checkPreferences(prefs: ValidationOptions): void;

Checks if the provided preferences are valid.

Throws an exception if the prefs object is invalid.

The method is provided to perform inputs validation for the any.validate() and any.validateAsync() methods. Validation is not performed automatically for performance reasons. Instead, manually validate the preferences passed once and reuse.

Parameters

Parameter	Type
prefs	ValidationOptions

Returns

void

Inherited from

Root.checkPreferences

---

compile()

compile(schema: SchemaLike_2, options?: CompileOptions): Schema_2;

Converts literal schema definition to joi schema object (or returns the same back if already a joi schema object).

Parameters

Parameter	Type
schema	SchemaLike_2
options?	CompileOptions

Returns

Schema_2

Inherited from

Root.compile

---

custom()

custom(fn: CustomValidator, description?: string): Schema_2;

Creates a custom validation schema.

Parameters

Parameter	Type
fn	CustomValidator
description?	string

Returns

Schema_2

Inherited from

Root.custom

---

date()

date<TSchema>(): DateSchema<TSchema>;

Generates a schema object that matches a date type (as well as a JavaScript date string or number of milliseconds).

Type Parameters

Type Parameter	Default type
TSchema	Date

Returns

DateSchema<TSchema>

---

datetime()

datetime<TSchema>(): DatetimeSchema<TSchema>;

Generates a schema object that matches a DateTime data type.

Type Parameters

Type Parameter	Default type
TSchema	DateTime<boolean>

Returns

DatetimeSchema<TSchema>

---

defaults()

defaults(fn: SchemaFunction_2): Root;

Creates a new Joi instance that will apply defaults onto newly created schemas through the use of the fn function that takes exactly one argument, the schema being created.

Parameters

Parameter	Type	Description
fn	SchemaFunction_2	The function must always return a schema, even if untransformed.

Returns

Root

Inherited from

Root.defaults

---

disallow()

disallow(...values: any[]): Schema;

Parameters

Parameter	Type
...values	any[]

Returns

Schema

---

equal()

equal(...values: any[]): Schema;

Parameters

Parameter	Type
...values	any[]

Returns

Schema

---

exist()

exist(): Schema;

Alias of required.

Returns

Schema

---

expression()

expression(template: string, options?: ReferenceOptions): any;

Generates a dynamic expression using a template string.

Parameters

Parameter	Type
template	string
options?	ReferenceOptions

Returns

any

Inherited from

Root.expression

---

extend()

extend(...extensions: (
  | Extension
  | ExtensionFactory)[]): any;

Creates a new Joi instance customized with the extension(s) you provide included.

Parameters

Parameter	Type
...extensions	( | Extension | ExtensionFactory)[]

Returns

any

Inherited from

Root.extend

---

forbidden()

forbidden(): Schema;

Marks a key as forbidden which will not allow any value except undefined. Used to explicitly forbid keys.

Returns

Schema

---

func()

func<TSchema>(): FunctionSchema<TSchema>;

Generates a schema object that matches a function type.

Type Parameters

Type Parameter	Default type
TSchema	Function

Returns

FunctionSchema<TSchema>

---

function()

function<TSchema>(): FunctionSchema<TSchema>;

Generates a schema object that matches a function type.

Type Parameters

Type Parameter	Default type
TSchema	Function

Returns

FunctionSchema<TSchema>

---

in()

in(ref: string, options?: ReferenceOptions): Reference;

Creates a reference that when resolved, is used as an array of values to match against the rule.

Parameters

Parameter	Type
ref	string
options?	ReferenceOptions

Returns

Reference

Inherited from

Root.in

---

invalid()

invalid(...values: any[]): Schema;

Blacklists a value

Parameters

Parameter	Type
...values	any[]

Returns

Schema

---

isError()

isError(error: any): error is ValidationError_2;

Checks whether or not the provided argument is an instance of ValidationError

Parameters

Parameter	Type
error	any

Returns

error is ValidationError_2

Inherited from

Root.isError

---

isExpression()

isExpression(expression: any): boolean;

Checks whether or not the provided argument is an expression.

Parameters

Parameter	Type
expression	any

Returns

boolean

Inherited from

Root.isExpression

---

isRef()

isRef(ref: any): ref is Reference;

Checks whether or not the provided argument is a reference. It's especially useful if you want to post-process error messages.

Parameters

Parameter	Type
ref	any

Returns

ref is Reference

Inherited from

Root.isRef

---

isSchema()

isSchema(schema: any, options?: CompileOptions): schema is AnySchema_2<any>;

Checks whether or not the provided argument is a joi schema.

Parameters

Parameter	Type
schema	any
options?	CompileOptions

Returns

schema is AnySchema_2<any>

Inherited from

Root.isSchema

---

link()

link<TSchema>(ref?: string): LinkSchema<TSchema>;

Links to another schema node and reuses it for validation, typically for creative recursive schemas.

Type Parameters

Type Parameter	Default type
TSchema	any

Parameters

Parameter	Type	Description
ref?	string	the reference to the linked schema node. Cannot reference itself or its children as well as other links. Links can be expressed in relative terms like value references (Joi.link('...')), in absolute terms from the schema run-time root (Joi.link('/a')), or using schema ids implicitly using object keys or explicitly using any.id() (Joi.link('#a.b.c')).

Returns

LinkSchema<TSchema>

---

not()

not(...values: any[]): Schema;

Parameters

Parameter	Type
...values	any[]

Returns

Schema

---

number()

number<TSchema>(): NumberSchema<TSchema>;

Generates a schema object that matches a number data type (as well as strings that can be converted to numbers).

Type Parameters

Type Parameter	Default type
TSchema	number

Returns

NumberSchema<TSchema>

---

object()

object<TSchema, IsStrict, T>(schema?: SchemaMap_2<T, IsStrict>): ObjectSchema<TSchema>;

Generates a schema object that matches an object data type (as well as JSON strings that have been parsed into objects).

Type Parameters

Type Parameter	Default type
TSchema	any
IsStrict	false
T	TSchema

Parameters

Parameter	Type
schema?	SchemaMap_2<T, IsStrict>

Returns

ObjectSchema<TSchema>

---

optional()

optional(): Schema;

Marks a key as optional which will allow undefined as values. Used to annotate the schema for readability as all keys are optional by default.

Returns

Schema

---

options()

options(...args: any[]): any;

Unsure, maybe alias for preferences?

Parameters

Parameter	Type
...args	any[]

Returns

any

Inherited from

Root.options

---

phone()

phone<TSchema>(country?:
  | CountryOrUnknown
  | Reference_2
| null): PhoneSchema<TSchema>;

Generates a schema object that matches a phone number data type.

Type Parameters

Type Parameter	Default type
TSchema	string

Parameters

Parameter	Type	Description
country?	| CountryOrUnknown | Reference_2 | null	Optional country code or reference for phone validation

Returns

PhoneSchema<TSchema>

---

preferences()

preferences(options: ValidationOptions): Schema;

Overrides the global validate() options for the current key and any sub-key.

Parameters

Parameter	Type
options	ValidationOptions

Returns

Schema

---

prefs()

prefs(options: ValidationOptions): Schema;

Overrides the global validate() options for the current key and any sub-key.

Parameters

Parameter	Type
options	ValidationOptions

Returns

Schema

---

ref()

ref(key: string, options?: ReferenceOptions): Reference_2;

Creates a reference to another schema key.

Parameters

Parameter	Type
key	string
options?	ReferenceOptions

Returns

Reference_2

---

required()

required(): Schema;

Marks a key as required which will not allow undefined as value. All keys are optional by default.

Returns

Schema

---

string()

string<TSchema>(): StringSchema<TSchema>;

Generates a schema object that matches a string data type. Note that empty strings are not allowed by default and must be enabled with allow('').

Type Parameters

Type Parameter	Default type
TSchema	string

Returns

StringSchema<TSchema>

---

symbol()

symbol<TSchema>(): SymbolSchema<TSchema>;

Generates a schema object that matches any symbol.

Type Parameters

Type Parameter	Default type
TSchema	Symbol

Returns

SymbolSchema<TSchema>

---

trace()

trace(...args: any[]): any;

Unsure, maybe leaked from @hapi/lab/coverage/initialize

Parameters

Parameter	Type
...args	any[]

Returns

any

Inherited from

Root.trace

---

types()

types(): {
  alternatives: AlternativesSchema;
  any: AnySchema;
  array: ArraySchema;
  bigint: BigIntSchema;
  binary: BinarySchema;
  boolean: BooleanSchema;
  date: DateSchema;
  datetime: DatetimeSchema;
  function: FunctionSchema;
  link: LinkSchema;
  number: NumberSchema;
  object: ObjectSchema;
  phone: PhoneSchema;
  string: StringSchema;
  symbol: SymbolSchema;
};

Returns an object where each key is a plain joi schema type. Useful for creating type shortcuts using deconstruction. Note that the types are already formed and do not need to be called as functions (e.g. string, not string()).

Returns

{
  alternatives: AlternativesSchema;
  any: AnySchema;
  array: ArraySchema;
  bigint: BigIntSchema;
  binary: BinarySchema;
  boolean: BooleanSchema;
  date: DateSchema;
  datetime: DatetimeSchema;
  function: FunctionSchema;
  link: LinkSchema;
  number: NumberSchema;
  object: ObjectSchema;
  phone: PhoneSchema;
  string: StringSchema;
  symbol: SymbolSchema;
}

Name	Type
alternatives	AlternativesSchema
any	AnySchema
array	ArraySchema
bigint	BigIntSchema
binary	BinarySchema
boolean	BooleanSchema
date	DateSchema
datetime	DatetimeSchema
function	FunctionSchema
link	LinkSchema
number	NumberSchema
object	ObjectSchema
phone	PhoneSchema
string	StringSchema
symbol	SymbolSchema

---

untrace()

untrace(...args: any[]): any;

Parameters

Parameter	Type
...args	any[]

Returns

any

Inherited from

Root.untrace

---

valid()

valid(...values: any[]): Schema;

Adds the provided values into the allowed whitelist and marks them as the only valid values allowed.

Parameters

Parameter	Type
...values	any[]

Returns

Schema

---

when()

Call Signature

when(ref: string | Reference_2, options:
  | WhenOptions<any, any>
  | WhenOptions<any, any>[]): AlternativesSchema;

Converts the type into an alternatives type where the conditions are merged into the type definition where:

Parameters

Parameter	Type
ref	string | Reference_2
options	| WhenOptions<any, any> | WhenOptions<any, any>[]

Returns

AlternativesSchema

Call Signature

when(ref: Schema, options: WhenSchemaOptions): AlternativesSchema;

Parameters

Parameter	Type
ref	Schema
options	WhenSchemaOptions

Returns

AlternativesSchema

---

x()

x(template: string, options?: ReferenceOptions): any;

Generates a dynamic expression using a template string.

Parameters

Parameter	Type
template	string
options?	ReferenceOptions

Returns

any

Inherited from

Root.x