joi

library18.2.1jsnpmunverified

Joi is the most powerful schema description language and data validator for JavaScript. Version 18.2.1 is the current stable release, with regular updates and a comprehensive API for defining schemas using a fluent, chainable syntax. It provides detailed error messages, custom validation, and extensive type support. Joi is widely used for validating API inputs, configuration objects, and form data, and offers a rich plugin ecosystem. It stands out with its expressive API and strong community support.

testing

npm install joi

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JOI

joi

testingjavascriptv18.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Joi

✓ import Joi from 'joi'

✗ const Joi = require('joi')

ESM-only since v17; CommonJS require() fails in Node 20+.

ObjectSchema

✓ import { ObjectSchema } from 'joi'

Type-only import for TypeScript users.

ValidationError

✓ import { ValidationError } from 'joi'

✗ const { ValidationError } = require('joi')

Named export for catching validation errors.

Defines and validates a user object schema with string, number, and boolean fields, demonstrating async validation.

import Joi from 'joi'; const schema = Joi.object({ username: Joi.string().alphanum().min(3).max(30).required(), password: Joi.string().pattern(new RegExp('^[a-zA-Z0-9]{3,30}$')).required(), email: Joi.string().email({ minDomainSegments: 2, tlds: { allow: ['com', 'net'] } }).required(), birth_year: Joi.number().integer().min(1900).max(2013), consent: Joi.boolean().valid(true).required() }); const data = { username: 'abc', password: 'mypassword', email: 'abc@example.com', birth_year: 1990, consent: true }; try { const value = await schema.validateAsync(data); console.log('Valid:', value); } catch (err) { console.error('Validation error:', err.message); }

Debug

Known issues

breakingJoi v17 drops support for Node.js < 12 and requires ESM imports. CommonJS require() will throw an error.

fix

Use import instead of require; upgrade Node to >=12.

affects: >=17.0.0

deprecatedJoi.object().keys() is deprecated; use Joi.object() directly.

fix

Replace .keys() with direct object definition.

affects: >=17.0.0

gotchaJoi v18.2.1 requires Node >= 20. Older Node versions will fail to install.

fix

Upgrade Node to >=20.

affects: >=18.0.0

gotchaUsing Joi.any().allow() with undefined can lead to silent validation errors if not explicitly allowed.

fix

Use Joi.any().allow(null).allow('') to allow null/empty strings explicitly.

affects: >=0.0.0

breakingJoi.string().email() now validates RFC 5321 by default; previously it allowed more lenient formats.

fix

Use Joi.string().email({ tlds: false }) to allow TLD-less emails if needed.

affects: >=17.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/joi not supported.

Using CommonJS require() with Joi v17+ which is ESM-only.

fix

Change require('joi') to import Joi from 'joi'; or use dynamic import().

ValidationError: "username" is not allowed. This is a custom error message.

The schema does not allow the provided field; often due to .unknown(false) (default) for object schemas.

fix

Use Joi.object({...}).unknown(true) to allow unknown keys, or add the field to the schema.

TypeError: Joi.object(...).validateAsync is not a function

Using an older version of Joi that does not support validateAsync (introduced in v17).

fix

Upgrade to Joi v17+ or use .validate() with callback (deprecated).

Upgrade

Version history

18.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubgit://github.com/hapijs/joi ↗

packagejoi ↗

homepagehttps://github.com/hapijs/joi#readme ↗