joi

property args

args?: {
    [key: string]: any;
};

property name

name: string;

method conditional

conditional: {
    (ref: string | Reference, options: WhenOptions | WhenOptions[]): this;
    (ref: Schema<any>, options: WhenSchemaOptions): this;
};

• Adds a conditional alternative schema type, either based on another key value, or a schema peeking into the current value.

method match

match: (mode: 'any' | 'all' | 'one') => this;

• Requires the validated value to match a specific set of the provided alternative.try() schemas. Cannot be combined with alternatives.conditional().

method try

try: (...types: SchemaLikeWithoutArray[]) => this;

• Adds an alternative schema type for attempting to match against the validated value.

property $

$: this;

• Starts a ruleset in order to apply multiple rule options. The set ends when rule(), keep(), message(), or warn() is called.

property ruleset

ruleset: this;

• Starts a ruleset in order to apply multiple rule options. The set ends when rule(), keep(), message(), or warn() is called.

property type

type?: Types | string;

method allow

allow: (...values: any[]) => this;

• Whitelists a value

method alter

alter: (targets: Record<string, (schema: this) => Schema>) => this;

• Assign target alteration options to a schema that are applied when any.tailor() is called.

  Parameter targets

  an object where each key is a target name, and each value is a function that takes an schema and returns an schema.

method artifact

artifact: (id: any) => this;

• Assigns the schema an artifact id which is included in the validation result if the rule passed validation.

  Parameter id

  any value other than undefined which will be returned as-is in the result artifacts map.

method bind

bind: () => this;

• By default, some Joi methods to function properly need to rely on the Joi instance they are attached to because they use this internally. So Joi.string() works but if you extract the function from it and call string() it won't. bind() creates a new Joi instance where all the functions relying on this are bound to the Joi instance.

method cache

cache: (cache?: Cache) => this;

• Adds caching to the schema which will attempt to cache the validation results (success and failures) of incoming inputs. If no cache is passed, a default cache is provisioned by using cache.provision() internally.

method cast

cast: (to: 'map' | 'number' | 'set' | 'string') => this;

• Casts the validated value to the specified type.

method concat

concat: (schema: this) => this;

• Returns a new type that is the result of adding the rules of one type to another.

method custom

custom: (fn: CustomValidator, description?: string) => this;

• Adds a custom validation function.

method default

default: (
    value?:
        | BasicType
        | Reference
        | ((parent: any, helpers: CustomHelpers) => BasicType | Reference)
) => this;

• Sets a default value if the original value is undefined where:

  Parameter value

  the default value. One of: - a literal value (string, number, object, etc.) - a [references](#refkey-options) - a function which returns the default value using the signature function(parent, helpers) where: - parent - a clone of the object containing the value being validated. Note that since specifying a parent argument performs cloning, do not declare format arguments if you are not using them. - helpers - same as those described in [any.custom()](anycustomermethod_description)

  When called without any value on an object schema type, a default value will be automatically generated based on the default values of the object keys.

  Note that if value is an object, any changes to the object after default() is called will change the reference and any future assignment.

method describe

describe: () => Description;

• Returns a plain object representing the schema's rules and properties

method description

description: (desc: string) => this;

• Annotates the key

method disallow

disallow: (...values: any[]) => this;

• Disallows values.

method empty

empty: (schema?: SchemaLike) => this;

• Considers anything that matches the schema to be empty (undefined).

  Parameter schema

  any object or joi schema to match. An undefined schema unsets that rule.

method equal

equal: (...values: any[]) => this;

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

method error

error: (err: Error | ValidationErrorFunction) => this;

• Overrides the default joi error with a custom error if the rule fails where:

  Parameter err

  can be: an instance of Error - the override error. a function(errors), taking an array of errors as argument, where it must either: return a string - substitutes the error message with this text return a single object or an Array of it, where: type - optional parameter providing the type of the error (eg. number.min). message - optional parameter if template is provided, containing the text of the error. template - optional parameter if message is provided, containing a template string, using the same format as usual joi language errors. context - optional parameter, to provide context to your error if you are using the template. return an Error - same as when you directly provide an Error, but you can customize the error message based on the errors.

  Note that if you provide an Error, it will be returned as-is, unmodified and undecorated with any of the normal joi error properties. If validation fails and another error is found before the error override, that error will be returned and the override will be ignored (unless the abortEarly option has been set to false).

method example

example: (value: any, options?: { override: boolean }) => this;

• Annotates the key with an example value, must be valid.

method exist

exist: () => this;

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

method external

external: (method: ExternalValidationFunction, description?: string) => this;

• Adds an external validation rule.

  Note that external validation rules are only called after the all other validation rules for the entire schema (from the value root) are checked. This means that any changes made to the value by the external rules are not available to any other validation rules during the non-external validation phase. If schema validation failed, no external validation rules are called.

method extract

extract: (path: string | string[]) => Schema;

• Returns a sub-schema based on a path of object keys or schema ids.

  Parameter path

  a dot . separated path string or a pre-split array of path keys. The keys must match the sub-schema id or object key (if no id was explicitly set).

method failover

failover: (value: any) => this;

• Sets a failover value if the original value fails passing validation.

  Parameter value

  the failover value. value supports references. value may be assigned a function which returns the default value.

  If value is specified as a function that accepts a single parameter, that parameter will be a context object that can be used to derive the resulting value. Note that if value is an object, any changes to the object after failover() is called will change the reference and any future assignment. Use a function when setting a dynamic value (e.g. the current time). Using a function with a single argument performs some internal cloning which has a performance impact. If you do not need access to the context, define the function without any arguments.

method forbidden

forbidden: () => this;

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

method fork

fork: (key: string | string[] | string[][], adjuster: SchemaFunction) => this;

• Returns a new schema where each of the path keys listed have been modified.

  Parameter key

  an array of key strings, a single key string, or an array of arrays of pre-split key strings.

  Parameter adjuster

  a function which must return a modified schema.

method id

id: (name?: string) => this;

• Sets a schema id for reaching into the schema via any.extract(). If no id is set, the schema id defaults to the object key it is associated with. If the schema is used in an array or alternatives type and no id is set, the schema in unreachable.

method invalid

invalid: (...values: any[]) => this;

• Disallows values.

method keep

keep: () => this;

• Same as rule({ keep: true }).

  Note that keep() will terminate the current ruleset and cannot be followed by another rule option. Use rule() to apply multiple rule options.

method label

label: (name: string) => this;

• Overrides the key name in error messages.

method message

message: (message: string) => this;

• Same as rule({ message }).

  Note that message() will terminate the current ruleset and cannot be followed by another rule option. Use rule() to apply multiple rule options.

method messages

messages: (messages: LanguageMessages) => this;

• Same as any.prefs({ messages }). Note that while any.message() applies only to the last rule or ruleset, any.messages() applies to the entire schema.

method meta

meta: (meta: object) => this;

• Attaches metadata to the key.

method not

not: (...values: any[]) => this;

• Disallows values.

method note

note: (...notes: string[]) => this;

• Annotates the key

method only

only: () => this;

• Requires the validated value to match of the provided any.allow() values. It has not effect when called together with any.valid() since it already sets the requirements. When used with any.allow() it converts it to an any.valid().

method optional

optional: () => this;

• 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.

method options

options: (options: ValidationOptions) => this;

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

method preferences

preferences: (options: ValidationOptions) => this;

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

method prefs

prefs: (options: ValidationOptions) => this;

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

method presence

presence: (mode: PresenceMode) => this;

• Sets the presence mode for the schema.

method raw

raw: (enabled?: boolean) => this;

• Outputs the original untouched value instead of the casted value.

method required

required: () => this;

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

method rule

rule: (options: RuleOptions) => this;

• Applies a set of rule options to the current ruleset or last rule added.

  When applying rule options, the last rule (e.g. min()) is used unless there is an active ruleset defined (e.g. $.min().max()) in which case the options are applied to all the provided rules. Once rule() is called, the previous rules can no longer be modified and any active ruleset is terminated.

  Rule modifications can only be applied to supported rules. Most of the any methods do not support rule modifications because they are implemented using schema flags (e.g. required()) or special internal implementation (e.g. valid()). In those cases, use the any.messages() method to override the error codes for the errors you want to customize.

method shared

shared: (ref: Schema) => this;

• Registers a schema to be used by descendants of the current schema in named link references.

method strict

strict: (isStrict?: boolean) => this;

• Sets the options.convert options to false which prevent type casting for the current key and any child keys.

method strip

strip: (enabled?: boolean) => this;

• Marks a key to be removed from a resulting object or array after validation. Used to sanitize output.

  Parameter enabled

  if true, the value is stripped, otherwise the validated value is retained. Defaults to true.

method tag

tag: (...tags: string[]) => this;

• Annotates the key

method tailor

tailor: (targets: string | string[]) => Schema;

• Applies any assigned target alterations to a copy of the schema that were applied via any.alter().

method unit

unit: (name: string) => this;

• Annotates the key with an unit name.

method valid

valid: (...values: any[]) => this;

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

method validate

validate: (value: any, options?: ValidationOptions) => ValidationResult<TSchema>;

• Validates a value using the schema and options.

method validateAsync

validateAsync: <TOpts extends AsyncValidationOptions>(
    value: any,
    options?: TOpts
) => Promise<
    TOpts extends { artifacts: true } | { warnings: true }
        ? { value: TSchema } & (TOpts extends { artifacts: true }
              ? { artifacts: Map<any, string[][]> }
              : {}) &
              (TOpts extends { warnings: true }
                  ? { warning: ValidationWarning }
                  : {})
        : TSchema
>;

• Validates a value using the schema and options.

method warn

warn: () => this;

• Same as rule({ warn: true }). Note that warn() will terminate the current ruleset and cannot be followed by another rule option. Use rule() to apply multiple rule options.

method warning

warning: (code: string, context: Context) => this;

• Generates a warning. When calling any.validateAsync(), set the warning option to true to enable warnings. Warnings are reported separately from errors alongside the result value via the warning key (i.e. { value, warning }). Warning are always included when calling any.validate().

method when

when: {
    (ref: string | Reference, options: WhenOptions | WhenOptions[]): this;
    (ref: Schema<any>, options: WhenSchemaOptions): this;
};

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

method has

has: (schema: SchemaLike) => this;

• Verifies that an assertion passes for at least one item in the array, where: schema - the validation rules required to satisfy the assertion. If the schema includes references, they are resolved against the array item being tested, not the value of the ref target.

method items

items: (...types: SchemaLikeWithoutArray[]) => this;

• List the types allowed for the array values. If a given type is .required() then there must be a matching item in the array. If a type is .forbidden() then it cannot appear in the array. Required items can be added multiple times to signify that multiple items must be found. Errors will contain the number of items that didn't match. Any unmatched item having a label will be mentioned explicitly.

  Parameter type

  a joi schema object to validate each array item against.

method length

length: (limit: number | Reference) => this;

• Specifies the exact number of items in the array.

method max

max: (limit: number | Reference) => this;

• Specifies the maximum number of items in the array.

method min

min: (limit: number | Reference) => this;

• Specifies the minimum number of items in the array.

method ordered

ordered: (...types: SchemaLikeWithoutArray[]) => this;

• Lists the types in sequence order for the array values where:

  Parameter type

  a joi schema object to validate against each array item in sequence order. type can be multiple values passed as individual arguments. If a given type is .required() then there must be a matching item with the same index position in the array. Errors will contain the number of items that didn't match. Any unmatched item having a label will be mentioned explicitly.

method single

single: (enabled?: any) => this;

• Allow single values to be checked against rules as if it were provided as an array. enabled can be used with a falsy value to go back to the default behavior.

method sort

sort: (options?: ArraySortOptions) => this;

• Sorts the array by given order.

method sparse

sparse: (enabled?: any) => this;

• Allow this array to be sparse. enabled can be used with a falsy value to go back to the default behavior.

method unique

unique: (
    comparator?: string | ComparatorFunction,
    options?: ArrayUniqueOptions
) => this;

• Requires the array values to be unique. Remember that if you provide a custom comparator function, different types can be passed as parameter depending on the rules you set on items. Be aware that a deep equality is performed on elements of the array having a type of object, a performance penalty is to be expected for this kind of operation.

property by

by?: string | Reference;

property order

order?: 'ascending' | 'descending';

• 'ascending'

property ignoreUndefined

ignoreUndefined?: boolean;

• if true, undefined values for the dot notation string comparator will not cause the array to fail on uniqueness.

  false

property artifacts

artifacts?: boolean;

• when true, artifacts are returned alongside the value (i.e. { value, artifacts })

  false

property warnings

warnings?: boolean;

• when true, warnings are returned alongside the value (i.e. { value, warning }).

  false

property urlSafe

urlSafe?: boolean;

• if true, uses the URI-safe base64 format which replaces + with - and \ with _.

  false

property abortEarly

abortEarly?: boolean;

• when true, stops validation on the first error, otherwise returns all the errors found.

  true

property allowUnknown

allowUnknown?: boolean;

• when true, allows object to contain unknown keys which are ignored.

  false

property artifacts

artifacts?: boolean;

• when true, return artifacts alongside the value.

  false

property cache

cache?: boolean;

• when true, schema caching is enabled (for schemas with explicit caching rules).

  false

property context

context?: Context;

• provides an external data set to be used in references

property convert

convert?: boolean;

• when true, attempts to cast values to the required types (e.g. a string to a number).

  true

property dateFormat

dateFormat?: 'date' | 'iso' | 'string' | 'time' | 'utc';

• sets the string format used when converting dates to strings in error messages and casting.

  'iso'

property debug

debug?: boolean;

• when true, valid results and throw errors are decorated with a debug property which includes an array of the validation steps used to generate the returned result.

  false

property errors

errors?: ErrorFormattingOptions;

• error formatting settings.

property externals

externals?: boolean;

• if false, the external rules set with any.external() are ignored, which is required to ignore any external validations in synchronous mode (or an exception is thrown).

  true

property noDefaults

noDefaults?: boolean;

• when true, do not apply default values.

  false

property nonEnumerables

nonEnumerables?: boolean;

• when true, inputs are shallow cloned to include non-enumerable properties.

  false

property presence

presence?: PresenceMode;

• sets the default presence requirements. Supported modes: 'optional', 'required', and 'forbidden'.

  'optional'

property skipFunctions

skipFunctions?: boolean;

• when true, ignores unknown keys with a function value.

  false

property stripUnknown

stripUnknown?: boolean | { arrays?: boolean; objects?: boolean };

• remove unknown elements from objects and arrays. - when true, all unknown elements will be removed - when an object: - objects - set to true to remove unknown keys from objects

  false

method encoding

encoding: (encoding: string) => this;

• Sets the string encoding format if a string input is converted to a buffer.

method length

length: (limit: number | Reference) => this;

• Specifies the exact length of the buffer:

method max

max: (limit: number | Reference) => this;

• Specifies the maximum length of the buffer.

method min

min: (limit: number | Reference) => this;

• Specifies the minimum length of the buffer.

method falsy

falsy: (...values: Array<string | number | null>) => this;

• Allows for additional values to be considered valid booleans by converting them to false during validation. String comparisons are by default case insensitive, see boolean.sensitive() to change this behavior.

  Parameter values

  strings, numbers or arrays of them

method sensitive

sensitive: (enabled?: boolean) => this;

• Allows the values provided to truthy and falsy as well as the "true" and "false" default conversion (when not in strict() mode) to be matched in a case insensitive manner.

method truthy

truthy: (...values: Array<string | number | null>) => this;

• Allows for additional values to be considered valid booleans by converting them to true during validation. String comparisons are by default case insensitive, see boolean.sensitive() to change this behavior.

  Parameter values

  strings, numbers or arrays of them

method get

get: (key: any) => any;

• Retrieve an item from the cache.

  Note that key and value can be anything including objects, array, etc.

method set

set: (key: any, value: any) => void;

• Add an item to the cache.

  Note that key and value can be anything including objects, array, etc.

method provision

provision: (options?: CacheProvisionOptions) => void;

• Provisions a simple LRU cache for caching simple inputs (undefined, null, strings, numbers, and booleans).

property max

max: number;

• number of items to store in the cache before the least used items are dropped.

  1000

property from

from?: string | string[];

property method

method: CoerceFunction;

property errors

errors?: ErrorReport[];

property value

value?: any;

property legacy

legacy: boolean;

• If true and the provided schema is (or contains parts) using an older version of joi, will return a compiled schema that is compatible with the older version. If false, the schema is always compiled using the current version and if older schema components are found, an error is thrown.

property key

key?: string;

property label

label?: string;

property value

value?: any;

index signature

[key: string]: any;

property flags

flags?: boolean;

property messages

messages?: LanguageMessages;

property error

error: (code: string, local?: Context, localState?: State) => ErrorReport;

property message

message: (messages: LanguageMessages, local?: Context) => ErrorReport;

property original

original: V;

property prefs

prefs: ValidationOptions;

property schema

schema: ExtensionBoundSchema;

property state

state: State;

property warn

warn: (code: string, local?: Context) => void;

property paddingRequired

paddingRequired?: boolean;

• optional parameter defaulting to true which will require = padding if true or make padding optional if false

  true

method greater

greater: (date: 'now' | Date | number | string | Reference) => this;

• Specifies that the value must be greater than date. Notes: 'now' can be passed in lieu of date so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future. It can also be a reference to another field.

method iso

iso: () => this;

• Requires the string value to be in valid ISO 8601 date format.

method less

less: (date: 'now' | Date | number | string | Reference) => this;

• Specifies that the value must be less than date. Notes: 'now' can be passed in lieu of date so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future. It can also be a reference to another field.

method max

max: (date: 'now' | Date | number | string | Reference) => this;

• Specifies the latest date allowed. Notes: 'now' can be passed in lieu of date so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future. It can also be a reference to another field.

method min

min: (date: 'now' | Date | number | string | Reference) => this;

• Specifies the oldest date allowed. Notes: 'now' can be passed in lieu of date so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future. It can also be a reference to another field.

method timestamp

timestamp: (type?: 'javascript' | 'unix') => this;

• Requires the value to be a timestamp interval from Unix Time.

  Parameter type

  the type of timestamp (allowed values are unix or javascript [default])

property isPresent

isPresent?: (resolved: any) => boolean;

• overrides the default check for a present value.

  (resolved) => resolved !== undefined

property description

description?: string;

property example

example?: any[];

property flags

flags?: object;

property invalids

invalids?: any[];

property label

label?: string;

property metas

metas?: any[];

property notes

notes?: string[];

property options

options?: ValidationOptions;

property tags

tags?: string[];

property type

type?: Types | string;

property unit

unit?: string;

property valids

valids?: any[];

index signature

[key: string]: any;

property allowFullyQualified

allowFullyQualified?: boolean;

• if true, domains ending with a . character are permitted

  false

property allowUnicode

allowUnicode?: boolean;

• If true, Unicode characters are permitted

  true

property maxDomainSegments

maxDomainSegments?: number;

• The maximum number of domain segments (e.g. x.y.z has 3 segments) allowed. Defaults to no limit.

  Infinity

property minDomainSegments

minDomainSegments?: number;

• Number of segments required for the domain.

  2

property tlds

tlds?: TopLevelDomainOptions | false;

• Options for TLD (top level domain) validation. By default, the TLD must be a valid name listed on the [IANA registry](http://data.iana.org/TLD/tlds-alpha-by-domain.txt)

  { allow: true }

property allowFullyQualified

allowFullyQualified?: boolean;

• if true, domains ending with a . character are permitted

  false

property allowUnicode

allowUnicode?: boolean;

• If true, Unicode characters are permitted

  true

property ignoreLength

ignoreLength?: boolean;

• if true, ignore invalid email length errors.

  false

property maxDomainSegments

maxDomainSegments?: number;

• The maximum number of domain segments (e.g. x.y.z has 3 segments) allowed. Defaults to no limit.

  Infinity

property minDomainSegments

minDomainSegments?: number;

• Number of segments required for the domain. Be careful since some domains, such as io, directly allow email.

  2

property multiple

multiple?: boolean;

• if true, allows multiple email addresses in a single string, separated by , or the separator characters.

  false

property separator

separator?: string | string[];

• when multiple is true, overrides the default , separator. String can be a single character or multiple separator characters.

  ','

property tlds

tlds?: TopLevelDomainOptions | false;

• Options for TLD (top level domain) validation. By default, the TLD must be a valid name listed on the [IANA registry](http://data.iana.org/TLD/tlds-alpha-by-domain.txt)

  { allow: true }

method toString

toString: () => string;

property escapeHtml

escapeHtml?: boolean;

• when true, error message templates will escape special characters to HTML entities, for security purposes.

  false

property label

label?: 'path' | 'key' | false;

• defines the value used to set the label context variable.

property language

language?: keyof LanguageMessages;

• The preferred language code for error messages. The value is matched against keys at the root of the messages object, and then the error code as a child key of that. Can be a reference to the value, global context, or local context which is the root value passed to the validation function.

  Note that references to the value are usually not what you want as they move around the value structure relative to where the error happens. Instead, either use the global context, or the absolute value (e.g. Joi.ref('/variable'))

property render

render?: boolean;

• when false, skips rendering error templates. Useful when error messages are generated elsewhere to save processing time.

  true

property stack

stack?: boolean;

• when true, the main error will possess a stack trace, otherwise it will be disabled. Defaults to false for performances reasons. Has no effect on platforms other than V8/node.js as it uses the Stack trace API.

  false

property wrap

wrap?: {
    /**
     * the characters used around `{#label}` references. Defaults to `'"'`.
     *
     * @default '"'
     */
    label?: string | false;

    /**
     * the characters used around array values. Defaults to `'[]'`
     *
     * @default '[]'
     */
    array?: string | false;

    /**
     * the characters used around array string values. Defaults to no wrapping.
     *
     * @default false
     */
    string?: string | false;
};

• overrides the way values are wrapped (e.g. [] around arrays, "" around labels). Each key can be set to a string with one (same character before and after the value) or two characters (first character before and second character after), or false to disable wrapping.

property code

code: string;

property flags

flags: Record<string, ExtensionFlag>;

property local

local: any;

property messages

messages: LanguageMessages;

property path

path: string[];

property prefs

prefs: ErrorValidationOptions;

property state

state: State;

property value

value: any;

property messages

messages?: Record<string, LanguageMessageTemplate>;

property base

base?: Schema;

property cast

cast?: Record<
    string,
    { from(value: any): any; to(value: any, helpers: CustomHelpers): any }
>;

• undocumented options

property coerce

coerce?: CoerceFunction | CoerceObject;

property flags

flags?: Record<string, ExtensionFlag>;

property manifest

manifest?: {
    build?(obj: ExtensionBoundSchema, desc: Record<string, any>): any;
};

property messages

messages?: LanguageMessages | string;

property modifiers

modifiers?: Record<string, (rule: any, enabled?: boolean) => any>;

property overrides

overrides?: Record<string, (value: any) => Schema>;

property properties

properties?: Record<string, any>;

property rules

rules?: Record<string, ExtensionRule & ThisType<SchemaInternals>>;

property terms

terms?: Record<string, ExtensionTerm>;

property type

type: string | RegExp;

method args

args: (...args: SchemaLike[]) => Schema;

method prepare

prepare: (value: any, helpers: CustomHelpers) => any;

method rebuild

rebuild: (schema: ExtensionBoundSchema) => void;

method validate

validate: (value: any, helpers: CustomHelpers) => any;

property default

default?: any;

property setter

setter?: string;

property alias

alias?: string;

• alternative name for this rule.

property args