Skip to content

Interface: ObjectSchema<TSchema>

Schema type for object validation.

Extends

  • AnySchema<TSchema>

Type Parameters

Type ParameterDefault type
TSchemaany

Properties

PropertyModifierTypeDescriptionInherited from
_flagspublicRecord<string, any>Flags of current schema.AnySchema._flags
~standardreadonlyProps<TSchema, TSchema>The Standard Schema properties.AnySchema.~standard
$publicObjectSchema<TSchema>Starts a ruleset in order to apply multiple rule options. The set ends when rule(), keep(), message(), or warn() is called.AnySchema.$
$_knexpublicany-AnySchema.$_knex
$_superpublicSchemaParent schema object.AnySchema.$_super
$_termspublicRecord<string, any>Terms of current schema.AnySchema.$_terms
rulesetpublicObjectSchema<TSchema>Starts a ruleset in order to apply multiple rule options. The set ends when rule(), keep(), message(), or warn() is called.AnySchema.ruleset
type?publicstring-AnySchema.type

Methods

$_addRule()

ts
$_addRule(rule: string | AddRuleOptions): Schema;

Adds a rule to current validation schema.

Parameters

ParameterType
rulestring | AddRuleOptions

Returns

Schema

Inherited from

ts
AnySchema.$_addRule;

$_compile()

ts
$_compile(schema: SchemaLike, options?: CompileOptions): Schema;

Internally compiles schema.

Parameters

ParameterType
schemaSchemaLike
options?CompileOptions

Returns

Schema

Inherited from

ts
AnySchema.$_compile;

$_createError()

ts
$_createError(
   code: string,
   value: any,
   context: ValidationContext,
   state: State,
   prefs: ValidationOptions,
   options?: CreateErrorOptions): Err;

Creates a joi error object.

Parameters

ParameterType
codestring
valueany
contextValidationContext
stateState
prefsValidationOptions
options?CreateErrorOptions

Returns

Err

Inherited from

ts
AnySchema.$_createError;

$_getFlag()

ts
$_getFlag(name: string): any;

Get value from given flag.

Parameters

ParameterType
namestring

Returns

any

Inherited from

ts
AnySchema.$_getFlag;

$_getRule()

ts
$_getRule(name: string): GetRuleOptions | undefined;

Retrieve some rule configuration.

Parameters

ParameterType
namestring

Returns

GetRuleOptions | undefined

Inherited from

ts
AnySchema.$_getRule;

$_mapLabels()

ts
$_mapLabels(path: string | string[]): string;

Parameters

ParameterType
pathstring | string[]

Returns

string

Inherited from

ts
AnySchema.$_mapLabels;

$_match()

ts
$_match(
   value: any,
   state: State,
   prefs: ValidationOptions): boolean;

Returns true if validations runs fine on given value.

Parameters

ParameterType
valueany
stateState
prefsValidationOptions

Returns

boolean

Inherited from

ts
AnySchema.$_match;

$_modify()

ts
$_modify(options?: ModifyOptions): Schema;

Parameters

ParameterType
options?ModifyOptions

Returns

Schema

Inherited from

ts
AnySchema.$_modify;

$_mutateRebuild()

ts
$_mutateRebuild(): this;

Resets current schema.

Returns

this

Inherited from

ts
AnySchema.$_mutateRebuild;

$_mutateRegister()

ts
$_mutateRegister(schema: Schema_2, options?: MutateRegisterOptions): void;

Parameters

ParameterType
schemaSchema_2
options?MutateRegisterOptions

Returns

void

Inherited from

ts
AnySchema.$_mutateRegister;

$_property()

ts
$_property(name: string): any;

Get value from given property.

Parameters

ParameterType
namestring

Returns

any

Inherited from

ts
AnySchema.$_property;

$_reach()

ts
$_reach(path: string[]): Schema;

Get schema at given path.

Parameters

ParameterType
pathstring[]

Returns

Schema

Inherited from

ts
AnySchema.$_reach;

$_rootReferences()

ts
$_rootReferences(): any;

Get current schema root references.

Returns

any

Inherited from

ts
AnySchema.$_rootReferences;

$_setFlag()

ts
$_setFlag(
   flag: string,
   value: any,
   options?: SetFlagOptions): void;

Set flag to given value.

Parameters

ParameterType
flagstring
valueany
options?SetFlagOptions

Returns

void

Inherited from

ts
AnySchema.$_setFlag;

$_validate()

ts
$_validate(
   value: any,
   state: State,
   prefs: ValidationOptions): ValidationResult;

Runs internal validations against given value.

Parameters

ParameterType
valueany
stateState
prefsValidationOptions

Returns

ValidationResult

Inherited from

ts
AnySchema.$_validate;

allow()

ts
allow(...values: any[]): this;

Parameters

ParameterType
...valuesany[]

Returns

this

Inherited from

ts
AnySchema.allow;

alter()

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

Parameters

ParameterType
targetsRecord<string, (schema: this) => Schema>

Returns

this

Inherited from

ts
AnySchema.alter;

and()

ts
and(...peers: (string | DependencyOptions)[]): this;

Defines an all-or-nothing relationship between keys where if one of the peers is present, all of them are required as well.

Optional settings must be the last argument.

Parameters

ParameterType
...peers(string | DependencyOptions)[]

Returns

this


append()

Call Signature

ts
append(schema?: PartialSchemaMap<TSchema>): this;

Appends the allowed object keys. If schema is null, undefined, or {}, no changes will be applied.

Parameters
ParameterType
schema?PartialSchemaMap<TSchema>
Returns

this

Call Signature

ts
append<TSchemaExtended, T>(schema?: PartialSchemaMap<T>): ObjectSchema<T>;
Type Parameters
Type ParameterDefault type
TSchemaExtendedany
TTSchemaExtended
Parameters
ParameterType
schema?PartialSchemaMap<T>
Returns

ObjectSchema<T>


artifact()

ts
artifact(id: any): this;

Parameters

ParameterType
idany

Returns

this

Inherited from

ts
AnySchema.artifact;

assert()

ts
assert(
   ref: string | Reference,
   schema: SchemaLike,
   message?: string): this;

Verifies an assertion where.

Parameters

ParameterType
refstring | Reference
schemaSchemaLike
message?string

Returns

this


bind()

ts
bind(): this;

Returns

this

Inherited from

ts
AnySchema.bind;

cache()

ts
cache(cache?: Cache): this;

Parameters

ParameterType
cache?Cache

Returns

this

Inherited from

ts
AnySchema.cache;

cast()

ts
cast(to: "string" | "number" | "object" | "set" | "map"): this;

Parameters

ParameterType
to"string" | "number" | "object" | "set" | "map"

Returns

this

Inherited from

ts
AnySchema.cast;

concat()

ts
concat(schema: this): this;

Parameters

ParameterType
schemathis

Returns

this

Inherited from

ts
AnySchema.concat;

custom()

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

Parameters

ParameterType
fnCustomValidator
description?string

Returns

this

Inherited from

ts
AnySchema.custom;

db()

ts
db(connection: any): this;

Alias for .knex(). Sets the database connection for database validation rules.

Parameters

ParameterTypeDescription
connectionanyA Knex instance, transaction, or connection configuration

Returns

this

Inherited from

ts
AnySchema.db;

default()

ts
default(value?: DefaultableValue): this;

Sets a default value if the original value is undefined.

Parameters

ParameterTypeDescription
value?DefaultableValueThe default value. Can be: - A literal object value - A reference to another schema value - A function that returns the default value with signature (parent, helpers) => value - parent - A clone of the object containing the value being validated - helpers - Validation helper functions for custom validation logic 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.

Returns

this

Overrides

ts
AnySchema.default;

describe()

ts
describe(): Description;

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

Returns

Description

Inherited from

ts
AnySchema.describe;

description()

ts
description(desc: string): this;

Parameters

ParameterType
descstring

Returns

this

Inherited from

ts
AnySchema.description;

disallow()

ts
disallow(...values: any[]): this;

Parameters

ParameterType
...valuesany[]

Returns

this

Inherited from

ts
AnySchema.disallow;

empty()

ts
empty(schema?: SchemaLike): this;

Parameters

ParameterType
schema?SchemaLike

Returns

this

Inherited from

ts
AnySchema.empty;

equal()

ts
equal(...values: any[]): this;

Parameters

ParameterType
...valuesany[]

Returns

this

Inherited from

ts
AnySchema.equal;

error()

ts
error(err: Error | ValidationErrorFunction): this;

Parameters

ParameterType
errError | ValidationErrorFunction

Returns

this

Inherited from

ts
AnySchema.error;

example()

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

Parameters

ParameterType
valueany
options?{ override: boolean; }
options.override?boolean

Returns

this

Inherited from

ts
AnySchema.example;

exist()

ts
exist(): this;

Returns

this

Inherited from

ts
AnySchema.exist;

existsInDb()

ts
existsInDb(
   table: string | Reference,
   column: string | Reference,
   options?: DbValidationOptions): this;

Validates that the value exists in the specified database table and column. Requires .knex() or .db() to be called first to set the database connection.

Parameters

ParameterTypeDescription
tablestring | ReferenceThe database table name (can be a Joi reference)
columnstring | ReferenceThe column name to check (can be a Joi reference)
options?DbValidationOptionsOptional configuration: - caseInsensitive: Perform case-insensitive comparison (default: false) - filter: Async function to add additional WHERE clauses to the query

Returns

this

Example

typescript
const schema = joi.object({
  country_id: joi.number().knex(db).existsInDb("countries", "id"),
  category: joi.string().knex(db).existsInDb("categories", "name", {
    caseInsensitive: true,
  }),
});

Inherited from

ts
AnySchema.existsInDb;

external()

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

Parameters

ParameterType
methodExternalValidationFunction
description?string

Returns

this

Inherited from

ts
AnySchema.external;

extract()

ts
extract(path: string | string[]): Schema;

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

Parameters

ParameterTypeDescription
pathstring | string[]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).

Returns

Schema

Inherited from

ts
AnySchema.extract;

failover()

ts
failover(value: any): this;

Parameters

ParameterType
valueany

Returns

this

Inherited from

ts
AnySchema.failover;

forbidden()

ts
forbidden(): this;

Returns

this

Inherited from

ts
AnySchema.forbidden;

fork()

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

Parameters

ParameterType
keystring | string[] | string[][]
adjusterSchemaFunction

Returns

this

Inherited from

ts
AnySchema.fork;

id()

ts
id(name?: string): this;

Parameters

ParameterType
name?string

Returns

this

Inherited from

ts
AnySchema.id;

instance()

ts
instance(constructor: Function, name?: string): this;

Requires the object to be an instance of a given constructor.

Parameters

ParameterTypeDescription
constructorFunctionthe constructor function that the object must be an instance of.
name?stringan alternate name to use in validation errors. This is useful when the constructor function does not have a name.

Returns

this


invalid()

ts
invalid(...values: any[]): this;

Parameters

ParameterType
...valuesany[]

Returns

this

Inherited from

ts
AnySchema.invalid;

isAsync()

ts
isAsync(): boolean;

Returns a boolean indicating whether this schema contains a rule that requires asynchronous validation.

Returns

boolean

Inherited from

ts
AnySchema.isAsync;

keep()

ts
keep(): this;

Returns

this

Inherited from

ts
AnySchema.keep;

keys()

ts
keys(schema?: PartialSchemaMap<TSchema>): this;

Sets or extends the allowed object keys.

Parameters

ParameterType
schema?PartialSchemaMap<TSchema>

Returns

this


knex()

ts
knex(connection: any): this;

Sets the database connection for database validation rules. This must be called before using .uniqueInDb() or .existsInDb().

Parameters

ParameterTypeDescription
connectionanyA Knex instance, transaction, or connection configuration

Returns

this

Example

typescript
import knex from 'knex'
const db = knex({ client: 'pg', connection: {...} })
const schema = joi.string().knex(db).uniqueInDb('users', 'email')

Inherited from

ts
AnySchema.knex;

label()

ts
label(name: string): this;

Parameters

ParameterType
namestring

Returns

this

Inherited from

ts
AnySchema.label;

length()

ts
length(limit: number): this;

Specifies the exact number of keys in the object.

Parameters

ParameterType
limitnumber

Returns

this


max()

ts
max(limit: number | Reference): this;

Specifies the maximum number of keys in the object.

Parameters

ParameterType
limitnumber | Reference

Returns

this


message()

ts
message(message: string): this;

Parameters

ParameterType
messagestring

Returns

this

Inherited from

ts
AnySchema.message;

messages()

ts
messages(messages: LanguageMessages): this;

Parameters

ParameterType
messagesLanguageMessages

Returns

this

Inherited from

ts
AnySchema.messages;

meta()

ts
meta(meta: object): this;

Parameters

ParameterType
metaobject

Returns

this

Inherited from

ts
AnySchema.meta;

min()

ts
min(limit: number | Reference): this;

Specifies the minimum number of keys in the object.

Parameters

ParameterType
limitnumber | Reference

Returns

this


nand()

ts
nand(...peers: (string | DependencyOptions)[]): this;

Defines a relationship between keys where not all peers can be present at the same time.

Optional settings must be the last argument.

Parameters

ParameterType
...peers(string | DependencyOptions)[]

Returns

this


not()

ts
not(...values: any[]): this;

Parameters

ParameterType
...valuesany[]

Returns

this

Inherited from

ts
AnySchema.not;

note()

ts
note(...notes: string[]): this;

Parameters

ParameterType
...notesstring[]

Returns

this

Inherited from

ts
AnySchema.note;

only()

ts
only(): this;

Returns

this

Inherited from

ts
AnySchema.only;

optional()

ts
optional(): this;

Returns

this

Inherited from

ts
AnySchema.optional;

options()

ts
options(options: ValidationOptions): this;

Parameters

ParameterType
optionsValidationOptions

Returns

this

Inherited from

ts
AnySchema.options;

or()

ts
or(...peers: (string | DependencyOptions)[]): this;

Defines a relationship between keys where one of the peers is required (and more than one is allowed).

Optional settings must be the last argument.

Parameters

ParameterType
...peers(string | DependencyOptions)[]

Returns

this


oxor()

ts
oxor(...peers: (string | DependencyOptions)[]): this;

Defines an exclusive relationship between a set of keys where only one is allowed but none are required.

Optional settings must be the last argument.

Parameters

ParameterType
...peers(string | DependencyOptions)[]

Returns

this


pattern()

ts
pattern(
   pattern: RegExp | SchemaLike,
   schema: SchemaLike,
   options?: ObjectPatternOptions): this;

Specify validation rules for unknown keys matching a pattern.

Parameters

ParameterTypeDescription
patternRegExp | SchemaLikea pattern that can be either a regular expression or a joi schema that will be tested against the unknown key names
schemaSchemaLikethe schema object matching keys must validate against
options?ObjectPatternOptions-

Returns

this


preferences()

ts
preferences(options: ValidationOptions): this;

Parameters

ParameterType
optionsValidationOptions

Returns

this

Inherited from

ts
AnySchema.preferences;

prefs()

ts
prefs(options: ValidationOptions): this;

Parameters

ParameterType
optionsValidationOptions

Returns

this

Inherited from

ts
AnySchema.prefs;

presence()

ts
presence(mode: PresenceMode): this;

Parameters

ParameterType
modePresenceMode

Returns

this

Inherited from

ts
AnySchema.presence;

raw()

ts
raw(enabled?: boolean): this;

Parameters

ParameterType
enabled?boolean

Returns

this

Inherited from

ts
AnySchema.raw;

ref()

ts
ref(): this;

Requires the object to be a Joi reference.

Returns

this


regex()

ts
regex(): this;

Requires the object to be a RegExp object.

Returns

this


rename()

ts
rename(
   from: string | RegExp,
   to: string,
   options?: RenameOptions): this;

Renames a key to another name (deletes the renamed key).

Parameters

ParameterType
fromstring | RegExp
tostring
options?RenameOptions

Returns

this


required()

ts
required(): this;

Returns

this

Inherited from

ts
AnySchema.required;

rule()

ts
rule(options: RuleOptions): this;

Parameters

ParameterType
optionsRuleOptions

Returns

this

Inherited from

ts
AnySchema.rule;

schema()

ts
schema(type?: SchemaLike): this;

Requires the object to be a Joi schema instance.

Parameters

ParameterType
type?SchemaLike

Returns

this


shared()

ts
shared(ref: Schema): this;

Parameters

ParameterType
refSchema

Returns

this

Inherited from

ts
AnySchema.shared;

strict()

ts
strict(isStrict?: boolean): this;

Parameters

ParameterType
isStrict?boolean

Returns

this

Inherited from

ts
AnySchema.strict;

strip()

ts
strip(enabled?: boolean): this;

Parameters

ParameterType
enabled?boolean

Returns

this

Inherited from

ts
AnySchema.strip;

tag()

ts
tag(...tags: string[]): this;

Parameters

ParameterType
...tagsstring[]

Returns

this

Inherited from

ts
AnySchema.tag;

tailor()

ts
tailor(targets: string | string[]): Schema;

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

Parameters

ParameterType
targetsstring | string[]

Returns

Schema

Inherited from

ts
AnySchema.tailor;

uniqueInDb()

ts
uniqueInDb(
   table: string | Reference,
   column: string | Reference,
   options?: DbValidationOptions): this;

Validates that the value is unique in the specified database table and column. Requires .knex() or .db() to be called first to set the database connection.

Parameters

ParameterTypeDescription
tablestring | ReferenceThe database table name (can be a Joi reference)
columnstring | ReferenceThe column name to check (can be a Joi reference)
options?DbValidationOptionsOptional configuration: - caseInsensitive: Perform case-insensitive comparison (default: false) - filter: Async function to add additional WHERE clauses to the query

Returns

this

Example

typescript
const schema = joi.object({
  email: joi.string().email().knex(db).uniqueInDb("users", "email"),
  username: joi
    .string()
    .knex(db)
    .uniqueInDb("users", "username", {
      caseInsensitive: true,
      filter: async (query) => query.where("tenant_id", tenantId),
    }),
});

Inherited from

ts
AnySchema.uniqueInDb;

unit()

ts
unit(name: string): this;

Parameters

ParameterType
namestring

Returns

this

Inherited from

ts
AnySchema.unit;

unknown()

ts
unknown(allow?: boolean): this;

Overrides the handling of unknown keys for the scope of the current object only (does not apply to children).

Parameters

ParameterType
allow?boolean

Returns

this


valid()

ts
valid(...values: any[]): this;

Parameters

ParameterType
...valuesany[]

Returns

this

Inherited from

ts
AnySchema.valid;

validate()

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

Validates a value using the schema and options.

Parameters

ParameterType
valueany
options?ValidationOptions

Returns

ValidationResult<TSchema>

Inherited from

ts
AnySchema.validate;

validateAsync()

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

Validates a value using the schema and options.

Type Parameters

Type Parameter
TOpts extends AsyncValidationOptions

Parameters

ParameterType
valueany
options?TOpts

Returns

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

Inherited from

ts
AnySchema.validateAsync;

warn()

ts
warn(): this;

Returns

this

Inherited from

ts
AnySchema.warn;

warning()

ts
warning(code: string, context: ValidationContext): this;

Parameters

ParameterType
codestring
contextValidationContext

Returns

this

Inherited from

ts
AnySchema.warning;

when()

Call Signature

ts
when(ref: string | Reference, options: WhenOptions<any, any> | WhenOptions<any, any>[]): this;
Parameters
ParameterType
refstring | Reference
optionsWhenOptions<any, any> | WhenOptions<any, any>[]
Returns

this

Inherited from
ts
AnySchema.when;

Call Signature

ts
when(ref: Schema, options: WhenSchemaOptions): this;
Parameters
ParameterType
refSchema
optionsWhenSchemaOptions
Returns

this

Inherited from
ts
AnySchema.when;

with()

ts
with(
   key: string,
   peers: string | string[],
   options?: DependencyOptions): this;

Requires the presence of other keys whenever the specified key is present.

Parameters

ParameterType
keystring
peersstring | string[]
options?DependencyOptions

Returns

this


without()

ts
without(
   key: string,
   peers: string | string[],
   options?: DependencyOptions): this;

Forbids the presence of other keys whenever the specified is present.

Parameters

ParameterType
keystring
peersstring | string[]
options?DependencyOptions

Returns

this


xor()

ts
xor(...peers: (string | DependencyOptions)[]): this;

Defines an exclusive relationship between a set of keys. one of them is required but not at the same time.

Optional settings must be the last argument.

Parameters

ParameterType
...peers(string | DependencyOptions)[]

Returns

this