Common Methods (any)

All schemas inherit these methods from Joi.any().

Value constraints

Special values for .allow(), .valid(), .invalid():

Joi.any().valid(null)            // Allow null
Joi.any().valid(Joi.ref('x'))    // Dynamic valid value
Joi.any().valid(Joi.override, 'a', 'b')  // Replace parent valid list

Joi.override as the first argument replaces inherited values instead of appending.

.valid() calls .allow() then sets the only flag. .invalid() removes from valids if present.

Defaults & coercion

.empty() compiles its argument as a schema. When both schemas in a .concat() have .empty(), they are concatenated together.

Joi.string().empty('').default('N/A');  // '' → undefined → 'N/A'
Joi.string().default(() => uuid());     // Lazy default
Joi.string().default(fn, { literal: true });  // fn IS the default, not called

Cast options per type:

Conditionals

Metadata

Note: The method names are .note() and .tag() (not .notes() and .tags()).

Error customization

.message(message) is a shortcut for .rule({ message }). .warning() is a rule (multi: true) that adds a warning code.

Behavior modifiers

.custom(fn, [description])

The function signature is fn(value, helpers). Return a value to replace, return undefined to keep, or throw to fail. The helpers object provides error(code, local), state, prefs, schema, and original.

Joi.string().custom((value, helpers) => {
    if (value === 'bad') {
        return helpers.error('any.invalid');
    }

    return value.toUpperCase();
}, 'uppercase validation');

Custom is a rule with multi: true, so multiple .custom() calls stack (they do not replace each other).

.external(fn, [description])

External validations run after all other validations succeed. They are async and require validateAsync(). The function receives (value, helpers). Can also pass an object: { method, description }.

Joi.string().external(async (value, helpers) => {
    const exists = await db.exists(value);
    if (!exists) {
        return helpers.error('any.invalid');
    }
}, 'db check');

// Object form
Joi.string().external({
    method: async (value) => { ... },
    description: 'db check'
});

External functions are stored in $_terms.externals as { method, description } objects.

Schema composition

.concat(schema)

Merges source schema into the current schema. Limitations:

• Types must match, or one must be any (any adopts the other's type)

• Neither schema can have an open ruleset

• Single (non-multi) rules in source replace same-named rules in target (unless keep is set)

• Both _valids and _invalids are merged (cross-removed)

• If both have .empty(), the empty schemas are concatenated

• Terms (arrays) are concatenated

• Flags are merged (source wins)

  const base = Joi.string().min(1); const extended = base.concat(Joi.string().max(100));

.alter(targets)

Takes an object where keys are target names and values are adjuster functions (schema) => schema:

const schema = Joi.object({
    name: Joi.string()
        .alter({
            create: (s) => s.required(),
            update: (s) => s.optional()
        })
});

schema.tailor('create');  // name becomes required
schema.tailor('update');  // name becomes optional

.extract(path)

Extracts nested schema by path. Path can be a dot-separated string or array. Lookup checks .id() first, then key name:

const schema = Joi.object({
    user: Joi.object({
        name: Joi.string().id('userName')
    })
});

schema.extract('user.name');      // By key path
schema.extract(['user', 'name']); // Array path form

Ruleset & rule modifiers

.ruleset (or .$) marks the start position. Subsequent rules are part of the set. .rule(options) then applies modifiers to all rules in the set:

Joi.number().$.min(0).max(100).rule({ message: 'Must be 0-100' });

Available rule modifiers (defined in any type):

Validation methods

Introspection

const desc = Joi.string().min(3).describe();
// { type: 'string', rules: [{ name: 'min', args: { limit: 3 } }] }

Joi.isSchema(value, [options])

Returns true if the value is a joi schema.

Joi.isSchema(Joi.string());  // true
Joi.isSchema('hello');       // false

Joi.compile(schema, [options])

Compiles various inputs into joi schemas:

Top-level Joi methods

Shortcuts on root Joi that delegate to Joi.any():

Joi.allow(), Joi.custom(), Joi.disallow(), Joi.equal(), Joi.exist(),
Joi.forbidden(), Joi.invalid(), Joi.not(), Joi.only(), Joi.optional(),
Joi.options(), Joi.prefs(), Joi.preferences(), Joi.required(),
Joi.strip(), Joi.valid(), Joi.when()