1 | ![joi Logo](https://raw.github.com/hapijs/joi/master/images/joi.png)
|
2 |
|
3 | Object schema description language and validator for JavaScript objects.
|
4 |
|
5 | [![npm version](https://badge.fury.io/js/joi.svg)](http://badge.fury.io/js/joi)
|
6 | [![Build Status](https://travis-ci.org/hapijs/joi.svg?branch=master)](https://travis-ci.org/hapijs/joi)
|
7 | [![NSP Status](https://nodesecurity.io/orgs/hapijs/projects/0394bf83-b5bc-410b-878c-e8cf1b92033e/badge)](https://nodesecurity.io/orgs/hapijs/projects/0394bf83-b5bc-410b-878c-e8cf1b92033e)
|
8 | [![Known Vulnerabilities](https://snyk.io/test/github/hapijs/joi/badge.svg)](https://snyk.io/test/github/hapijs/joi)
|
9 |
|
10 | Lead Maintainer: [Nicolas Morel](https://github.com/marsup)
|
11 |
|
12 | # Introduction
|
13 |
|
14 | Imagine you run facebook and you want visitors to sign up on the website with real names and not something like `l337_p@nda` in the first name field. How would you define the limitations of what can be inputted and validate it against the set rules?
|
15 |
|
16 | This is joi, joi allows you to create *blueprints* or *schemas* for JavaScript objects (an object that stores information) to ensure *validation* of key information.
|
17 |
|
18 | # API
|
19 | See the detailed [API Reference](https://github.com/hapijs/joi/blob/v14.3.1/API.md).
|
20 |
|
21 | # Example
|
22 |
|
23 | ```javascript
|
24 | const Joi = require('joi');
|
25 |
|
26 | const schema = Joi.object().keys({
|
27 | username: Joi.string().alphanum().min(3).max(30).required(),
|
28 | password: Joi.string().regex(/^[a-zA-Z0-9]{3,30}$/),
|
29 | access_token: [Joi.string(), Joi.number()],
|
30 | birthyear: Joi.number().integer().min(1900).max(2013),
|
31 | email: Joi.string().email({ minDomainAtoms: 2 })
|
32 | }).with('username', 'birthyear').without('password', 'access_token');
|
33 |
|
34 | // Return result.
|
35 | const result = Joi.validate({ username: 'abc', birthyear: 1994 }, schema);
|
36 | // result.error === null -> valid
|
37 |
|
38 | // You can also pass a callback which will be called synchronously with the validation result.
|
39 | Joi.validate({ username: 'abc', birthyear: 1994 }, schema, function (err, value) { }); // err === null -> valid
|
40 |
|
41 | ```
|
42 |
|
43 | The above schema defines the following constraints:
|
44 | * `username`
|
45 | * a required string
|
46 | * must contain only alphanumeric characters
|
47 | * at least 3 characters long but no more than 30
|
48 | * must be accompanied by `birthyear`
|
49 | * `password`
|
50 | * an optional string
|
51 | * must satisfy the custom regex
|
52 | * cannot appear together with `access_token`
|
53 | * `access_token`
|
54 | * an optional, unconstrained string or number
|
55 | * `birthyear`
|
56 | * an integer between 1900 and 2013
|
57 | * `email`
|
58 | * a valid email address string
|
59 | * must have two domain parts e.g. `example.com`
|
60 |
|
61 | # Usage
|
62 |
|
63 | Usage is a two steps process. First, a schema is constructed using the provided types and constraints:
|
64 |
|
65 | ```javascript
|
66 | const schema = {
|
67 | a: Joi.string()
|
68 | };
|
69 | ```
|
70 |
|
71 | Note that **joi** schema objects are immutable which means every additional rule added (e.g. `.min(5)`) will return a
|
72 | new schema object.
|
73 |
|
74 | Second, the value is validated against the defined schema:
|
75 |
|
76 | ```javascript
|
77 | const {error, value} = Joi.validate({ a: 'a string' }, schema);
|
78 |
|
79 | // or
|
80 |
|
81 | Joi.validate({ a: 'a string' }, schema, function (error, value) { });
|
82 | ```
|
83 |
|
84 | If the input is valid, then the `error` will be `null`, otherwise it will be an `Error` object providing more information.
|
85 |
|
86 | The schema can be a plain JavaScript object where every key is assigned a **joi** type, or it can be a **joi** type directly:
|
87 |
|
88 | ```javascript
|
89 | const schema = Joi.string().min(10);
|
90 | ```
|
91 |
|
92 | 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,
|
93 | the module converts it internally to an object() type equivalent to:
|
94 |
|
95 | ```javascript
|
96 | const schema = Joi.object().keys({
|
97 | a: Joi.string()
|
98 | });
|
99 | ```
|
100 |
|
101 | When validating a schema:
|
102 |
|
103 | * Values (or keys in case of objects) are optional by default.
|
104 |
|
105 | ```javascript
|
106 | Joi.validate(undefined, Joi.string()); // validates fine
|
107 | ```
|
108 |
|
109 | To disallow this behavior, you can either set the schema as `required()`, or set `presence` to `"required"` when passing `options`:
|
110 |
|
111 | ```javascript
|
112 | Joi.validate(undefined, Joi.string().required());
|
113 | // or
|
114 | Joi.validate(undefined, Joi.string(), /* options */ { presence: "required" });
|
115 | ```
|
116 |
|
117 | * Strings are utf-8 encoded by default.
|
118 | * Rules are defined in an additive fashion and evaluated in order, first the inclusive rules, then the exclusive rules.
|
119 |
|
120 | # Browsers
|
121 |
|
122 | Joi doesn't directly support browsers, but you could use [joi-browser](https://github.com/jeffbski/joi-browser) for an ES5 build of Joi that works in browsers, or as a source of inspiration for your own builds.
|