Validation

    Before we get into the specifics of validation syntax, please keep the following rules in mind:

    • Validation is defined in the SchemaType
    • Validation is middleware. Mongoose registers validation as a pre('save') hook on every schema by default.
    • You can manually run validation using doc.validate(callback) or doc.validateSync()
    • Validators are not run on undefined values. The only exception is the required validator.
    • Validation is asynchronously recursive; when you call Model#save, sub-document validation is executed as well. If an error occurs, your Model#save callback receives it
    • Validation is customizable
    2.     var schema = new Schema({
    3.       name: {
    4.         type: String,
    5.         required: true
    6.       }
    7.     });
    8.     var Cat = db.model('Cat', schema);
    10.     // This cat has no name :(
    11.     var cat = new Cat();
    12.     cat.save(function(error) {
    13.       assert.equal(error.errors['name'].message,
    14.         'Path `name` is required.');
    16.       error = cat.validateSync();
    17.       assert.equal(error.errors['name'].message,
    18.         'Path `name` is required.');
    19.     });

    Built-in Validators

    Mongoose has several built-in validators.

    Each of the validator links above provide more information about how to enable them and customize their error messages.

    2.     var breakfastSchema = new Schema({
    3.       eggs: {
    4.         type: Number,
    5.         min: [6, 'Too few eggs'],
    6.         max: 12
    7.       },
    8.       bacon: {
    9.         type: Number,
    10.         required: [true, 'Why no bacon?']
    11.       },
    12.       drink: {
    13.         type: String,
    14.         enum: ['Coffee', 'Tea'],
    15.         required: function() {
    16.           return this.bacon > 3;
    17.         }
    18.       }
    19.     });
    20.     var Breakfast = db.model('Breakfast', breakfastSchema);
    22.     var badBreakfast = new Breakfast({
    23.       eggs: 2,
    24.       bacon: 0,
    25.       drink: 'Milk'
    26.     });
    27.     var error = badBreakfast.validateSync();
    28.     assert.equal(error.errors['eggs'].message,
    29.       'Too few eggs');
    30.     assert.ok(!error.errors['bacon']);
    31.     assert.equal(error.errors['drink'].message,
    32.       '`Milk` is not a valid enum value for path `drink`.');
    34.     badBreakfast.bacon = 5;
    35.     badBreakfast.drink = null;
    37.     error = badBreakfast.validateSync();
    38.     assert.equal(error.errors['drink'].message, 'Path `drink` is required.');
    40.     badBreakfast.bacon = null;
    41.     error = badBreakfast.validateSync();
    42.     assert.equal(error.errors['bacon'].message, 'Why no bacon?');

    The unique Option is Not a Validator

    A common gotcha for beginners is that the unique option for schemas is not a validator. It’s a convenient helper for building MongoDB unique indexes. See the FAQ for more information.

    2.     var uniqueUsernameSchema = new Schema({
    3.       username: {
    4.         type: String,
    5.         unique: true
    6.       }
    7.     });
    8.     var U1 = db.model('U1', uniqueUsernameSchema);
    9.     var U2 = db.model('U2', uniqueUsernameSchema);
    11.     var dup = [{ username: 'Val' }, { username: 'Val' }];
    12.     U1.create(dup, function(error) {
    13.       // Will save successfully!
    14.     });
    16.     // Need to wait for the index to finish building before saving,
    17.     // otherwise unique constraints may be violated.
    18.     U2.on('index', function(error) {
    19.       assert.ifError(error);
    20.       U2.create(dup, function(error) {
    21.         // Will error, but will *not* be a mongoose validation error, it will be
    22.         // a duplicate key error.
    23.         assert.ok(error);
    24.         assert.ok(!error.errors);
    25.         assert.ok(error.message.indexOf('duplicate key error') !== -1);
    26.       });
    27.     });
    29.     // There's also a promise-based equivalent to the event emitter API.
    30.     // The `init()` function is idempotent and returns a promise that
    31.     // will resolve once indexes are done building;
    32.     U2.init().then(function() {
    33.       U2.create(dup, function(error) {
    34.         // Will error, but will *not* be a mongoose validation error, it will be
    35.         // a duplicate key error.
    36.         assert.ok(error);
    37.         assert.ok(!error.errors);
    38.         assert.ok(error.message.indexOf('duplicate key error') !== -1);
    39.       });
    40.     });

    Custom Validators

    If the built-in validators aren’t enough, you can define custom validators to suit your needs.

    Custom validation is declared by passing a validation function. You can find detailed instructions on how to do this in the SchemaType#validate() API docs.

    2.     var userSchema = new Schema({
    3.       phone: {
    4.         type: String,
    5.         validate: {
    6.           validator: function(v) {
    7.             return /\d{3}-\d{3}-\d{4}/.test(v);
    8.           },
    9.           message: '{VALUE} is not a valid phone number!'
    10.         },
    11.         required: [true, 'User phone number required']
    12.       }
    13.     });
    15.     var User = db.model('user', userSchema);
    16.     var user = new User();
    17.     var error;
    19.     user.phone = '555.0123';
    20.     error = user.validateSync();
    21.     assert.equal(error.errors['phone'].message,
    22.       '555.0123 is not a valid phone number!');
    24.     user.phone = '';
    25.     error = user.validateSync();
    26.     assert.equal(error.errors['phone'].message,
    27.       'User phone number required');
    29.     user.phone = '201-555-0123';
    30.     // Validation succeeds! Phone number is defined
    31.     // and fits `DDD-DDD-DDDD`
    32.     error = user.validateSync();
    33.     assert.equal(error, null);

    Async Custom Validators

    Custom validators can also be asynchronous. If your validator function takes 2 arguments, mongoose will assume the 2nd argument is a callback.

    Even if you don’t want to use asynchronous validators, be careful, because mongoose 4 will assume that all functions that take 2 arguments are asynchronous, like the validator.isEmail function. This behavior is considered deprecated as of 4.9.0, and you can shut it off by specifying isAsync: false on your custom validator.

    2.     var userSchema = new Schema({
    3.       phone: {
    4.         type: String,
    5.         validate: {
    6.           // `isAsync` is not strictly necessary in mongoose 4.x, but relying
    7.           // on 2 argument validators being async is deprecated. Set the
    8.           // `isAsync` option to `true` to make deprecation warnings go away.
    9.           isAsync: true,
    10.           validator: function(v, cb) {
    11.             setTimeout(function() {
    12.               var phoneRegex = /\d{3}-\d{3}-\d{4}/;
    13.               var msg = v + ' is not a valid phone number!';
    14.               // First argument is a boolean, whether validator succeeded
    15.               // 2nd argument is an optional error message override
    16.               cb(phoneRegex.test(v), msg);
    17.             }, 5);
    18.           },
    19.           // Default error message, overridden by 2nd argument to `cb()` above
    20.           message: 'Default error message'
    21.         },
    22.         required: [true, 'User phone number required']
    23.       },
    24.       name: {
    25.         type: String,
    26.         // You can also make a validator async by returning a promise. If you
    27.         // return a promise, do **not** specify the `isAsync` option.
    28.         validate: function(v) {
    29.           return new Promise(function(resolve, reject) {
    30.             setTimeout(function() {
    31.               resolve(false);
    32.             }, 5);
    33.           });
    34.         }
    35.       }
    36.     });
    38.     var User = db.model('User', userSchema);
    39.     var user = new User();
    40.     var error;
    42.     user.phone = '555.0123';
    43.     user.name = 'test';
    44.     user.validate(function(error) {
    45.       assert.ok(error);
    46.       assert.equal(error.errors['phone'].message,
    47.         '555.0123 is not a valid phone number!');
    48.       assert.equal(error.errors['name'].message,
    49.         'Validator failed for path `name` with value `test`');
    50.     });

    Validation Errors

    Errors returned after failed validation contain an errors object whose values are ValidatorError objects. Each ValidatorError has kind, path, value, and message properties. A ValidatorError also may have a reason property. If an error was thrown in the validator, this property will contain the error that was thrown.

    2.     var toySchema = new Schema({
    3.       color: String,
    4.       name: String
    5.     });
    7.     var validator = function(value) {
    8.       return /red|white|gold/i.test(value);
    9.     };
    10.     toySchema.path('color').validate(validator,
    11.       'Color `{VALUE}` not valid', 'Invalid color');
    12.     toySchema.path('name').validate(function(v) {
    13.       if (v !== 'Turbo Man') {
    14.         throw new Error('Need to get a Turbo Man for Christmas');
    15.       }
    16.       return true;
    17.     }, 'Name `{VALUE}` is not valid');
    19.     var Toy = db.model('Toy', toySchema);
    21.     var toy = new Toy({ color: 'Green', name: 'Power Ranger' });
    23.     toy.save(function (err) {
    24.       // `err` is a ValidationError object
    25.       // `err.errors.color` is a ValidatorError object
    26.       assert.equal(err.errors.color.message, 'Color `Green` not valid');
    27.       assert.equal(err.errors.color.kind, 'Invalid color');
    28.       assert.equal(err.errors.color.path, 'color');
    29.       assert.equal(err.errors.color.value, 'Green');
    31.       assert.equal(err.errors.name.message, 'Name `Power Ranger` is not valid');
    32.       assert.equal(err.errors.name.value, 'Power Ranger');
    33.       assert.equal(err.errors.name.reason.message,
    34.         'Need to get a Turbo Man for Christmas');
    36.       assert.equal(err.name, 'ValidationError');
    37.     });

    Required Validators On Nested Objects

    Defining validators on nested objects in mongoose is tricky, because nested objects are not fully fledged paths.

    2.     var personSchema = new Schema({
    3.       name: {
    4.         first: String,
    5.         last: String
    6.       }
    7.     });
    9.     assert.throws(function() {
    10.       // This throws an error, because 'name' isn't a full fledged path
    11.       personSchema.path('name').required(true);
    12.     }, /Cannot.*'required'/);
    14.     // To make a nested object required, use a single nested schema
    15.     var nameSchema = new Schema({
    16.       first: String,
    17.       last: String
    18.     });
    20.     personSchema = new Schema({
    21.       name: {
    22.         type: nameSchema,
    23.         required: true
    24.       }
    25.     });
    27.     var Person = db.model('Person', personSchema);
    29.     var person = new Person();
    30.     var error = person.validateSync();
    31.     assert.ok(error.errors['name']);

    Update Validators

    In the above examples, you learned about document validation. Mongoose also supports validation for update() and findOneAndUpdate() operations. In Mongoose 4.x, update validators are off by default - you need to specify the runValidators option.

    To turn on update validators, set the runValidators option for update() or findOneAndUpdate(). Be careful: update validators are off by default because they have several caveats.

    2.     var toySchema = new Schema({
    3.       color: String,
    4.       name: String
    5.     });
    7.     var Toy = db.model('Toys', toySchema);
    9.     Toy.schema.path('color').validate(function (value) {
    10.       return /blue|green|white|red|orange|periwinkle/i.test(value);
    11.     }, 'Invalid color');
    13.     var opts = { runValidators: true };
    14.     Toy.update({}, { color: 'bacon' }, opts, function (err) {
    15.       assert.equal(err.errors.color.message,
    16.         'Invalid color');
    17.     });

    Update Validators and this

    There are a couple of key differences between update validators and document validators. In the color validation function above, this refers to the document being validated when using document validation. However, when running update validators, the document being updated may not be in the server’s memory, so by default the value of this is not defined.

    2.     var toySchema = new Schema({
    3.       color: String,
    4.       name: String
    5.     });
    7.     toySchema.path('color').validate(function(value) {
    8.       // When running in `validate()` or `validateSync()`, the
    9.       // validator can access the document using `this`.
    10.       // Does **not** work with update validators.
    11.       if (this.name.toLowerCase().indexOf('red') !== -1) {
    12.         return value !== 'red';
    13.       }
    14.       return true;
    15.     });
    17.     var Toy = db.model('ActionFigure', toySchema);
    19.     var toy = new Toy({ color: 'red', name: 'Red Power Ranger' });
    20.     var error = toy.validateSync();
    21.     assert.ok(error.errors['color']);
    23.     var update = { color: 'red', name: 'Red Power Ranger' };
    24.     var opts = { runValidators: true };
    26.     Toy.update({}, update, opts, function(error) {
    27.       // The update validator throws an error:
    28.       // "TypeError: Cannot read property 'toLowerCase' of undefined",
    29.       // because `this` is **not** the document being updated when using
    30.       // update validators
    31.       assert.ok(error);
    32.     });

    The context option

    The context option lets you set the value of this in update validators to the underlying query.

    2.     toySchema.path('color').validate(function(value) {
    3.       // When running update validators with the `context` option set to
    4.       // 'query', `this` refers to the query object.
    5.       if (this.getUpdate().$set.name.toLowerCase().indexOf('red') !== -1) {
    6.         return value === 'red';
    7.       }
    8.       return true;
    9.     });
    11.     var Toy = db.model('Figure', toySchema);
    13.     var update = { color: 'blue', name: 'Red Power Ranger' };
    14.     // Note the context option
    15.     var opts = { runValidators: true, context: 'query' };
    17.     Toy.update({}, update, opts, function(error) {
    18.       assert.ok(error.errors['color']);
    19.     });

    Update Validator Paths

    The other key difference that update validators only run on the paths specified in the update. For instance, in the below example, because ‘name’ is not specified in the update operation, update validation will succeed.

    When using update validators, required validators only fail when you try to explicitly $unset the key.

    2.     var kittenSchema = new Schema({
    3.       name: { type: String, required: true },
    4.       age: Number
    5.     });
    7.     var Kitten = db.model('Kitten', kittenSchema);
    9.     var update = { color: 'blue' };
    10.     var opts = { runValidators: true };
    11.     Kitten.update({}, update, opts, function(err) {
    12.       // Operation succeeds despite the fact that 'name' is not specified
    13.     });
    15.     var unset = { $unset: { name: 1 } };
    16.     Kitten.update({}, unset, opts, function(err) {
    17.       // Operation fails because 'name' is required
    18.       assert.ok(err);
    19.       assert.ok(err.errors['name']);
    20.     });

    Update Validators Only Run On Specified Paths

    One final detail worth noting: update validators only run on the following update operators:

    • $set
    • $unset
    • $push (>= 4.8.0)
    • $addToSet (>= 4.8.0)
    • $pull (>= 4.12.0)
    • $pullAll (>= 4.12.0)

    For instance, the below update will succeed, regardless of the value of number, because update validators ignore $inc. Also, $push, $addToSet, $pull, and $pullAll validation does not run any validation on the array itself, only individual elements of the array.

    2.     var testSchema = new Schema({
    3.       number: { type: Number, max: 0 },
    4.       arr: [{ message: { type: String, maxLength: 10 } }]
    5.     });
    7.     // Update validators won't check this, so you can still `$push` 2 elements
    8.     // onto the array, so long as they don't have a `message` that's too long.
    9.     testSchema.path('arr').validate(function(v) {
    10.       return v.length < 2;
    11.     });
    13.     var Test = db.model('Test', testSchema);
    15.     var update = { $inc: { number: 1 } };
    16.     var opts = { runValidators: true };
    17.     Test.update({}, update, opts, function(error) {
    18.       // There will never be a validation error here
    19.       update = { $push: [{ message: 'hello' }, { message: 'world' }] };
    20.       Test.update({}, update, opts, function(error) {
    21.         // This will never error either even though the array will have at
    22.         // least 2 elements.
    23.       });
    24.     });

    On $push and $addToSet

    New in 4.8.0: update validators also run on $push and $addToSet

    2.     var testSchema = new Schema({
    3.       numbers: [{ type: Number, max: 0 }],
    4.       docs: [{
    5.         name: { type: String, required: true }
    6.       }]
    7.     });
    9.     var Test = db.model('TestPush', testSchema);
    11.     var update = {
    12.       $push: {
    13.         numbers: 1,
    14.         docs: { name: null }
    15.       }
    16.     };
    17.     var opts = { runValidators: true };
    18.     Test.update({}, update, opts, function(error) {
    19.       assert.ok(error.errors['numbers']);
    20.       assert.ok(error.errors['docs']);
    21.     });