1![joi Logo](https://raw.github.com/hapijs/joi/master/images/joi.png)
 2
 3Object 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://secure.travis-ci.org/hapijs/joi.svg)](http://travis-ci.org/hapijs/joi)
 7[![Dependencies Status](https://david-dm.org/hapijs/joi.svg)](https://david-dm.org/hapijs/joi)
 8[![DevDependencies Status](https://david-dm.org/hapijs/joi/dev-status.svg)](https://david-dm.org/hapijs/joi#info=devDependencies)
 9
10[![Join the chat at https://gitter.im/hapijs/joi](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/hapijs/joi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
11
12Lead Maintainer: [Nicolas Morel](https://github.com/marsup)
13
14# Example
15
16```javascript
17var Joi = require('joi');
18
19var schema = Joi.object().keys({
20    username: Joi.string().alphanum().min(3).max(30).required(),
21    password: Joi.string().regex(/^[a-zA-Z0-9]{3,30}$/),
22    access_token: [Joi.string(), Joi.number()],
23    birthyear: Joi.number().integer().min(1900).max(2013),
24    email: Joi.string().email()
25}).with('username', 'birthyear').without('password', 'access_token');
26
27Joi.validate({ username: 'abc', birthyear: 1994 }, schema, function (err, value) { });  // err === null -> valid
28```
29
30The above schema defines the following constraints:
31* `username`
32    * a required string
33    * must contain only alphanumeric characters
34    * at least 3 characters long but no more than 30
35    * must be accompanied by `birthyear`
36* `password`
37    * an optional string
38    * must satisfy the custom regex
39    * cannot appear together with `access_token`
40* `access_token`
41    * an optional, unconstrained string or number
42* `birthyear`
43    * an integer between 1900 and 2013
44* `email`
45    * a valid email address string
46
47# Usage
48
49Usage is a two steps process. First, a schema is constructed using the provided types and constraints:
50
51```javascript
52var schema = {
53    a: Joi.string()
54};
55```
56
57Note that **joi** schema objects are immutable which means every additional rule added (e.g. `.min(5)`) will return a
58new schema object.
59
60Then the value is validated against the schema:
61
62```javascript
63Joi.validate({ a: 'a string' }, schema, function (err, value) { });
64```
65
66If the value is valid, `null` is returned, otherwise an `Error` object.
67
68The schema can be a plain JavaScript object where every key is assigned a **joi** type, or it can be a **joi** type directly:
69
70```javascript
71var schema = Joi.string().min(10);
72```
73
74If 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,
75the module converts it internally to an object() type equivalent to:
76
77```javascript
78var schema = Joi.object().keys({
79    a: Joi.string()
80});
81```
82
83When validating a schema:
84
85* Keys are optional by default.
86* Strings are utf-8 encoded by default.
87* Rules are defined in an additive fashion and evaluated in order after whitelist and blacklist checks.
88
89# API
90See the [API Reference](API.md).