• Validation is defined in the
    • Validation is middleware. Mongoose registers validation as a pre('save') hook on every schema by default.
    • You can disable automatic validation before save by setting the option
    • You can manually run validation using doc.validate(callback) or doc.validateSync()
    • You can manually mark a field as invalid (causing validation to fail) by using doc.invalidate(...)
    • Validators are not run on undefined values. The only exception is the .
    • Validation is asynchronously recursive; when you call Model#save, sub-document validation is executed as well. If an error occurs, your callback receives it
    • Validation is customizable

    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.

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

    Custom Error Messages

    You can configure the error message for individual validators in your schema. There are two equivalent ways to set the validator error message:

    • Array syntax: min: [6, 'Must be at least 6, got {VALUE}']
    • Object syntax: enum: { values: ['Coffee', 'Tea'], message: '{VALUE} is not supported' }

    Mongoose also supports rudimentary templating for error messages. Mongoose replaces {VALUE} with the value being validated.

    1. const breakfastSchema = new Schema({
    2.   eggs: {
    3.     type: Number,
    4.     min: [6, 'Must be at least 6, got {VALUE}'],
    5.     max: 12
    6.   },
    7.   drink: {
    8.     type: String,
    9.     enum: {
    10.       values: ['Coffee', 'Tea'],
    11.       message: '{VALUE} is not supported'
    12.     }
    13.   }
    14. });
    15. const Breakfast = db.model('Breakfast', breakfastSchema);
    17. const badBreakfast = new Breakfast({
    18.   eggs: 2,
    19.   drink: 'Milk'
    20. });
    21. let error = badBreakfast.validateSync();
    22. assert.equal(error.errors['eggs'].message,
    23.   'Must be at least 6, got 2');
    24. assert.equal(error.errors['drink'].message, 'Milk is not supported');

    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 . See the FAQ for more information.

    1. const uniqueUsernameSchema = new Schema({
    2.   username: {
    3.     type: String,
    4.     unique: true
    5.   }
    6. });
    7. const U2 = db.model('U2', uniqueUsernameSchema);
    9. const dup = [{ username: 'Val' }, { username: 'Val' }];
    10. U1.create(dup, err => {
    11.   // Race condition! This may save successfully, depending on whether
    12.   // MongoDB built the index before writing the 2 docs.
    13. });
    15. // You need to wait for Mongoose to finish building the `unique`
    16. // index before writing. You only need to build indexes once for
    17. // a given collection, so you normally don't need to do this
    18. // in production. But, if you drop the database between tests,
    19. // you will need to use `init()` to wait for the index build to finish.
    20. U2.init().
    21.   then(() => U2.create(dup)).
    22.   catch(error => {
    23.     // Will error, but will *not* be a mongoose validation error, it will be
    25.     // See: https://masteringjs.io/tutorials/mongoose/e11000-duplicate-key
    26.     assert.ok(error);
    27.     assert.ok(!error.errors);
    28.     assert.ok(error.message.indexOf('duplicate key error') !== -1);
    29.   });

    Custom Validators

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

    Custom validators can also be asynchronous. If your validator function returns a promise (like an async function), mongoose will wait for that promise to settle. If the returned promise rejects, or fulfills with the value false, Mongoose will consider that a validation error.

    1. const userSchema = new Schema({
    2.   name: {
    3.     type: String,
    4.     // You can also make a validator async by returning a promise.
    5.     validate: () => Promise.reject(new Error('Oops!'))
    6.   },
    7.   email: {
    8.     type: String,
    9.     // There are two ways for an promise-based async validator to fail:
    10.     // 1) If the promise rejects, Mongoose assumes the validator failed with the given error.
    11.     // 2) If the promise resolves to `false`, Mongoose assumes the validator failed and creates an error with the given `message`.
    12.     validate: {
    13.       validator: () => Promise.resolve(false),
    14.       message: 'Email validation failed'
    15.     }
    16.   }
    17. });
    19. const User = db.model('User', userSchema);
    20. const user = new User();
    22. user.email = 'test@test.co';
    23. user.name = 'test';
    24. user.validate().catch(error => {
    25.   assert.ok(error);
    26.   assert.equal(error.errors['name'].message, 'Oops!');
    27.   assert.equal(error.errors['email'].message, 'Email validation failed');
    28. });

    Validation Errors

    Errors returned after failed validation contain an errors object whose values are ValidatorError objects. Each 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.

    1. const toySchema = new Schema({
    2.   color: String,
    3.   name: String
    4. });
    6. const validator = function(value) {
    7.   return /red|white|gold/i.test(value);
    8. };
    9. toySchema.path('color').validate(validator,
    10.   'Color `{VALUE}` not valid', 'Invalid color');
    11. toySchema.path('name').validate(function(v) {
    12.   if (v !== 'Turbo Man') {
    13.     throw new Error('Need to get a Turbo Man for Christmas');
    14.   }
    15.   return true;
    16. }, 'Name `{VALUE}` is not valid');
    18. const Toy = db.model('Toy', toySchema);
    20. const toy = new Toy({ color: 'Green', name: 'Power Ranger' });
    22. toy.save(function(err) {
    23.   // `err` is a ValidationError object
    24.   // `err.errors.color` is a ValidatorError object
    25.   assert.equal(err.errors.color.message, 'Color `Green` not valid');
    26.   assert.equal(err.errors.color.kind, 'Invalid color');
    27.   assert.equal(err.errors.color.path, 'color');
    28.   assert.equal(err.errors.color.value, 'Green');
    30.   // This is new in mongoose 5. If your validator throws an exception,
    31.   // mongoose will use that message. If your validator returns `false`,
    32.   // mongoose will use the 'Name `Power Ranger` is not valid' message.
    33.   assert.equal(err.errors.name.message,
    34.     'Need to get a Turbo Man for Christmas');
    35.   assert.equal(err.errors.name.value, 'Power Ranger');
    36.   // If your validator threw an error, the `reason` property will contain
    37.   // the original error thrown, including the original stack trace.
    38.   assert.equal(err.errors.name.reason.message,
    39.     'Need to get a Turbo Man for Christmas');
    41.   assert.equal(err.name, 'ValidationError');
    42. });

    Before running validators, Mongoose attempts to coerce values to the correct type. This process is called casting the document. If casting fails for a given path, the error.errors object will contain a CastError object.

    Casting runs before validation, and validation does not run if casting fails. That means your custom validators may assume v is null, undefined, or an instance of the type specified in your schema.

    1. const vehicleSchema = new mongoose.Schema({
    2.   numWheels: { type: Number, max: 18 }
    3. });
    4. const Vehicle = db.model('Vehicle', vehicleSchema);
    5. const doc = new Vehicle({ numWheels: 'not a number' });
    6. const err = doc.validateSync();
    8. err.errors['numWheels'].name; // 'CastError'
    9. // 'Cast to Number failed for value "not a number" at path "numWheels"'
    10. err.errors['numWheels'].message;

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

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

    1. const toySchema = new Schema({
    2.   color: String,
    3.   name: String
    4. });
    6. const Toy = db.model('Toys', toySchema);
    8. Toy.schema.path('color').validate(function(value) {
    9.   return /red|green|blue/i.test(value);
    10. }, 'Invalid color');
    12. const opts = { runValidators: true };
    13. Toy.updateOne({}, { color: 'not a color' }, opts, function(err) {
    14.   assert.equal(err.errors.color.message,
    15.     'Invalid color');
    16. });

    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.

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

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

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

    The other key difference is 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.

    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.

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