joi

What is joi?

The Joi package is a powerful schema description language and data validator for JavaScript. It allows developers to create blueprints or schemas for JavaScript objects to ensure validation of key information. It is commonly used for validating data, such as configuration objects, request data in web applications, and more.

What are joi's main functionalities?

Object Schema Validation

This feature allows you to define a schema for an object, specifying the expected type of each property, and then validate data against this schema. The code sample demonstrates creating a schema for user data and validating an object against it.

{"const Joi = require('joi');\nconst schema = Joi.object({\n  username: Joi.string().alphanum().min(3).max(30).required(),\n  password: Joi.string().pattern(new RegExp('^[a-zA-Z0-9]{3,30}$')),\n  repeat_password: Joi.ref('password'),\n  access_token: [Joi.string(), Joi.number()],\n  birth_year: Joi.number().integer().min(1900).max(2013),\n  email: Joi.string().email({ minDomainSegments: 2, tlds: { allow: ['com', 'net'] } })\n}).with('username', 'birth_year');\n\nconst dataToValidate = {\n  username: 'abc',\n  birth_year: 1994,\n  email: '[e-mail]'\n};\n\nconst result = schema.validate(dataToValidate);\nconsole.log(result);"}

Type Casting

Joi can cast values to other types as part of the validation process. In this example, a string representing a number is cast to an actual number, and a string 'TRUE' is cast to a boolean true.

{"const Joi = require('joi');\nconst schema = Joi.object({\n  age: Joi.number().integer(),\n  active: Joi.string().trim().lowercase().valid('true', 'false').truthy('true').falsy('false').default(false).cast('boolean')\n});\n\nconst dataToValidate = {\n  age: '30',\n  active: 'TRUE'\n};\n\nconst result = schema.validate(dataToValidate, { convert: true });\nconsole.log(result.value); // { age: 30, active: true }"}

Custom Validation Messages

Joi allows you to specify custom validation messages for when data does not conform to the schema. This example shows how to set a custom message for a string that is too short.

{"const Joi = require('joi');\nconst schema = Joi.string().min(10).message('The string needs to be at least 10 characters long.');\n\nconst result = schema.validate('short');\nconsole.log(result.error); // Custom error message"}

Other packages similar to joi

yup

Yup is a JavaScript schema builder for value parsing and validation. It is similar to Joi but is leaner and designed for browser usage as well as Node.js. It uses a similar API to Joi but is built with a different focus on client-side validation.

ajv

Ajv (Another JSON Schema Validator) is a fast JSON schema validator supporting JSON Schema draft-06/07/2019-09/2020-12 and JSON Type Definition (RFC 8927). It is different from Joi in that it uses a JSON-based schema definition rather than a fluent API.

validator

Validator is a library of string validators and sanitizers. It is not a schema-based validation library like Joi but provides a set of string validation functions that can be used individually to validate specific types of input data.

class-validator

Class-validator works with TypeScript and uses decorators to define validation rules within class definitions. It is different from Joi in that it integrates tightly with TypeScript and leverages its type system for validation.

README

Object schema description language and validator for JavaScript objects.

Lead Maintainer: Nicolas Morel

Example

var Joi = require('joi');

var schema = Joi.object().keys({
    username: Joi.string().alphanum().min(3).max(30).required(),
    password: Joi.string().regex(/^[a-zA-Z0-9]{3,30}$/),
    access_token: [Joi.string(), Joi.number()],
    birthyear: Joi.number().integer().min(1900).max(2013),
    email: Joi.string().email()
}).with('username', 'birthyear').without('password', 'access_token');

Joi.validate({ username: 'abc', birthyear: 1994 }, schema, function (err, value) { });  // err === null -> valid

The above schema defines the following constraints:

• username
  • a required string
  • must contain only alphanumeric characters
  • at least 3 characters long but no more than 30
  • must be accompanied by birthyear
• password
  • an optional string
  • must satisfy the custom regex
  • cannot appear together with access_token
• access_token
  • an optional, unconstrained string or number
• birthyear
  • an integer between 1900 and 2013
• email
  • a valid email address string

Usage

Usage is a two steps process. First, a schema is constructed using the provided types and constraints:

var schema = {
    a: Joi.string()
};

Note that joi schema objects are immutable which means every additional rule added (e.g. .min(5)) will return a new schema object.

Then the value is validated against the schema:

Joi.validate({ a: 'a string' }, schema, function (err, value) { });

If the value is valid, null is returned, otherwise an Error object.

The schema can be a plain JavaScript object where every key is assigned a joi type, or it can be a joi type directly:

var schema = Joi.string().min(10);

If the schema is a joi type, the schema.validate(value, callback) can be called directly on the type. When passing a non-type schema object, the module converts it internally to an object() type equivalent to:

var schema = Joi.object().keys({
    a: Joi.string()
});

When validating a schema:

• Keys are optional by default.
• Strings are utf-8 encoded by default.
• Rules are defined in an additive fashion and evaluated in order after whitelist and blacklist checks.

API

See the API Reference.