SchemaTypes

SchemaTypes handle definition of path defaults, validation, getters, setters, field selection defaults for queries, and other general characteristics for Mongoose document properties.

What is a SchemaType?

You can think of a Mongoose schema as the configuration object for a Mongoose model. A SchemaType is then a configuration object for an individual property. A SchemaType says what type a given path should have, whether it has any getters/setters, and what values are valid for that path.

  1. const schema = new Schema({ name: String });
  2. schema.path('name') instanceof mongoose.SchemaType; // true
  3. schema.path('name') instanceof mongoose.Schema.Types.String; // true
  4. schema.path('name').instance; // 'String'

A SchemaType is different from a type. In other words, mongoose.ObjectId !== mongoose.Types.ObjectId. A SchemaType is just a configuration object for Mongoose. An instance of the mongoose.ObjectId SchemaType doesn’t actually create MongoDB ObjectIds, it is just a configuration for a path in a schema.

The following are all the valid SchemaTypes in Mongoose. Mongoose plugins can also add custom SchemaTypes like int32. Check out Mongoose’s plugins search to find plugins.

Example

  1. const schema = new Schema({
  2.   name:    String,
  3.   binary:  Buffer,
  4.   living:  Boolean,
  5.   updated: { type: Date, default: Date.now },
  6.   age:     { type: Number, min: 18, max: 65 },
  7.   mixed:   Schema.Types.Mixed,
  8.   _someId: Schema.Types.ObjectId,
  9.   decimal: Schema.Types.Decimal128,
  10.   array: [],
  11.   ofString: [String],
  12.   ofNumber: [Number],
  13.   ofDates: [Date],
  14.   ofBuffer: [Buffer],
  15.   ofBoolean: [Boolean],
  16.   ofMixed: [Schema.Types.Mixed],
  17.   ofObjectId: [Schema.Types.ObjectId],
  18.   ofArrays: [[]],
  19.   ofArrayOfNumbers: [[Number]],
  20.   nested: {
  21.     stuff: { type: String, lowercase: true, trim: true }
  22.   },
  23.   map: Map,
  24.   mapOfString: {
  25.     type: Map,
  26.     of: String
  27.   }
  28. })
  30. // example use
  32. const Thing = mongoose.model('Thing', schema);
  34. const m = new Thing;
  35. m.name = 'Statue of Liberty';
  36. m.age = 125;
  37. m.updated = new Date;
  38. m.binary = Buffer.alloc(0);
  39. m.living = false;
  40. m.mixed = { any: { thing: 'i want' } };
  41. m.markModified('mixed');
  42. m._someId = new mongoose.Types.ObjectId;
  43. m.array.push(1);
  44. m.ofString.push("strings!");
  45. m.ofNumber.unshift(1,2,3,4);
  46. m.ofDates.addToSet(new Date);
  47. m.ofBuffer.pop();
  48. m.ofMixed = [1, [], 'three', { four: 5 }];
  49. m.nested.stuff = 'good';
  50. m.map = new Map([['key', 'value']]);
  51. m.save(callback);

The `type` Key

type is a special property in Mongoose schemas. When Mongoose finds a nested property named type in your schema, Mongoose assumes that it needs to define a SchemaType with the given type.

  1. // 3 string SchemaTypes: 'name', 'nested.firstName', 'nested.lastName'
  2. const schema = new Schema({
  3.   name: { type: String },
  4.   nested: {
  5.     firstName: { type: String },
  6.     lastName: { type: String }
  7.   }
  8. });

As a consequence, you need a little extra work to define a property named type in your schema. For example, suppose you’re building a stock portfolio app, and you want to store the asset’s type (stock, bond, ETF, etc.). Naively, you might define your schema as shown below:

  1. const holdingSchema = new Schema({
  2.   // You might expect `asset` to be an object that has 2 properties,
  3.   // but unfortunately `type` is special in Mongoose so mongoose
  4.   // interprets this schema to mean that `asset` is a string
  5.   asset: {
  6.     type: String,
  7.     ticker: String
  8.   }
  9. });

However, when Mongoose sees type: String, it assumes that you mean asset should be a string, not an object with a property type. The correct way to define an object with a property type is shown below.

  1. const holdingSchema = new Schema({
  2.   asset: {
  3.     // Workaround to make sure Mongoose knows `asset` is an object
  4.     // and `asset.type` is a string, rather than thinking `asset`
  5.     // is a string.
  6.     type: { type: String },
  7.     ticker: String
  8.   }
  9. });

SchemaType Options

You can declare a schema type using the type directly, or an object with a type property.

  1. const schema1 = new Schema({
  2.   test: String // `test` is a path of type String
  3. });
  5. const schema2 = new Schema({
  6.   // The `test` object contains the "SchemaType options"
  7.   test: { type: String } // `test` is a path of type string
  8. });

In addition to the type property, you can specify additional properties for a path. For example, if you want to lowercase a string before saving:

  1. const schema2 = new Schema({
  2.   test: {
  3.     type: String,
  4.     lowercase: true // Always convert `test` to lowercase
  5.   }
  6. });

You can add any property you want to your SchemaType options. Many plugins rely on custom SchemaType options. For example, the mongoose-autopopulate plugin automatically populates paths if you set autopopulate: true in your SchemaType options. Mongoose comes with support for several built-in SchemaType options, like lowercase in the above example.

The lowercase option only works for strings. There are certain options which apply for all schema types, and some that apply for specific schema types.

All Schema Types
  • required: boolean or function, if true adds a required validator for this property
  • default: Any or function, sets a default value for the path. If the value is a function, the return value of the function is used as the default.
  • select: boolean, specifies default projections for queries
  • validate: function, adds a validator function for this property
  • get: function, defines a custom getter for this property using Object.defineProperty().
  • set: function, defines a custom setter for this property using Object.defineProperty().
  • alias: string, mongoose >= 4.10.0 only. Defines a virtual with the given name that gets/sets this path.
  • immutable: boolean, defines path as immutable. Mongoose prevents you from changing immutable paths unless the parent document has isNew: true.
  • transform: function, Mongoose calls this function when you call Document#toJSON() function, including when you JSON.stringify() a document.
  1. const numberSchema = new Schema({
  2.   integerOnly: {
  3.     type: Number,
  4.     get: v => Math.round(v),
  5.     set: v => Math.round(v),
  6.     alias: 'i'
  7.   }
  8. });
  10. const Number = mongoose.model('Number', numberSchema);
  12. const doc = new Number();
  13. doc.integerOnly = 2.001;
  14. doc.integerOnly; // 2
  15. doc.i; // 2
  16. doc.i = 3.001;
  17. doc.integerOnly; // 3
  18. doc.i; // 3
Indexes

You can also define MongoDB indexes using schema type options.

  • index: boolean, whether to define an index on this property.
  • unique: boolean, whether to define a unique index on this property.
  • sparse: boolean, whether to define a sparse index on this property.
  1. const schema2 = new Schema({
  2.   test: {
  3.     type: String,
  4.     index: true,
  5.     unique: true // Unique index. If you specify `unique: true`
  6.     // specifying `index: true` is optional if you do `unique: true`
  7.   }
  8. });
String
  • lowercase: boolean, whether to always call .toLowerCase() on the value
  • uppercase: boolean, whether to always call .toUpperCase() on the value
  • trim: boolean, whether to always call .trim() on the value
  • match: RegExp, creates a validator that checks if the value matches the given regular expression
  • enum: Array, creates a validator that checks if the value is in the given array.
  • minLength: Number, creates a validator that checks if the value length is not less than the given number
  • maxLength: Number, creates a validator that checks if the value length is not greater than the given number
  • populate: Object, sets default populate options
Number
  • min: Number, creates a validator that checks if the value is greater than or equal to the given minimum.
  • max: Number, creates a validator that checks if the value is less than or equal to the given maximum.
  • enum: Array, creates a validator that checks if the value is strictly equal to one of the values in the given array.
  • populate: Object, sets default populate options
Date
  • min: Date
  • max: Date
ObjectId

Usage Notes

String

To declare a path as a string, you may use either the String global constructor or the string 'String'.

  1. const schema1 = new Schema({ name: String }); // name will be cast to string
  2. const schema2 = new Schema({ name: 'String' }); // Equivalent
  4. const Person = mongoose.model('Person', schema2);

If you pass an element that has a toString() function, Mongoose will call it, unless the element is an array or the toString() function is strictly equal to Object.prototype.toString().

  1. new Person({ name: 42 }).name; // "42" as a string
  2. new Person({ name: { toString: () => 42 } }).name; // "42" as a string
  4. // "undefined", will get a cast error if you `save()` this document
  5. new Person({ name: { foo: 42 } }).name;

Number

To declare a path as a number, you may use either the Number global constructor or the string 'Number'.

  1. const schema1 = new Schema({ age: Number }); // age will be cast to a Number
  2. const schema2 = new Schema({ age: 'Number' }); // Equivalent
  4. const Car = mongoose.model('Car', schema2);

There are several types of values that will be successfully cast to a Number.

  1. new Car({ age: '15' }).age; // 15 as a Number
  2. new Car({ age: true }).age; // 1 as a Number
  3. new Car({ age: false }).age; // 0 as a Number
  4. new Car({ age: { valueOf: () => 83 } }).age; // 83 as a Number

If you pass an object with a valueOf() function that returns a Number, Mongoose will call it and assign the returned value to the path.

The values null and undefined are not cast.

NaN, strings that cast to NaN, arrays, and objects that don’t have a valueOf() function will all result in a CastError once validated, meaning that it will not throw on initialization, only when validated.

Dates

Built-in Date methods are not hooked into the mongoose change tracking logic which in English means that if you use a Date in your document and modify it with a method like setMonth(), mongoose will be unaware of this change and doc.save() will not persist this modification. If you must modify Date types using built-in methods, tell mongoose about the change with doc.markModified('pathToYourDate') before saving.

  1. const Assignment = mongoose.model('Assignment', { dueDate: Date });
  2. Assignment.findOne(function (err, doc) {
  3.   doc.dueDate.setMonth(3);
  4.   doc.save(callback); // THIS DOES NOT SAVE YOUR CHANGE
  6.   doc.markModified('dueDate');
  7.   doc.save(callback); // works
  8. })

Buffer

To declare a path as a Buffer, you may use either the Buffer global constructor or the string 'Buffer'.

  1. const schema1 = new Schema({ binData: Buffer }); // binData will be cast to a Buffer
  2. const schema2 = new Schema({ binData: 'Buffer' }); // Equivalent
  4. const Data = mongoose.model('Data', schema2);

Mongoose will successfully cast the below values to buffers.

  1. const file1 = new Data({ binData: 'test'}); // {"type":"Buffer","data":[116,101,115,116]}
  2. const file2 = new Data({ binData: 72987 }); // {"type":"Buffer","data":[27]}
  3. const file4 = new Data({ binData: { type: 'Buffer', data: [1, 2, 3]}}); // {"type":"Buffer","data":[1,2,3]}

Mixed

An “anything goes” SchemaType. Mongoose will not do any casting on mixed paths. You can define a mixed path using Schema.Types.Mixed or by passing an empty object literal. The following are equivalent.

  1. const Any = new Schema({ any: {} });
  2. const Any = new Schema({ any: Object });
  3. const Any = new Schema({ any: Schema.Types.Mixed });
  4. const Any = new Schema({ any: mongoose.Mixed });

Since Mixed is a schema-less type, you can change the value to anything else you like, but Mongoose loses the ability to auto detect and save those changes. To tell Mongoose that the value of a Mixed type has changed, you need to call doc.markModified(path), passing the path to the Mixed type you just changed.

To avoid these side-effects, a Subdocument path may be used instead.

  1. person.anything = { x: [3, 4, { y: "changed" }] };
  2. person.markModified('anything');
  3. person.save(); // Mongoose will save changes to `anything`.

ObjectIds

An ObjectId is a special type typically used for unique identifiers. Here’s how you declare a schema with a path driver that is an ObjectId:

  1. const mongoose = require('mongoose');
  2. const carSchema = new mongoose.Schema({ driver: mongoose.ObjectId });

ObjectId is a class, and ObjectIds are objects. However, they are often represented as strings. When you convert an ObjectId to a string using toString(), you get a 24-character hexadecimal string:

  1. const Car = mongoose.model('Car', carSchema);
  3. const car = new Car();
  4. car.driver = new mongoose.Types.ObjectId();
  6. typeof car.driver; // 'object'
  7. car.driver instanceof mongoose.Types.ObjectId; // true
  9. car.driver.toString(); // Something like "5e1a0651741b255ddda996c4"

Boolean

Booleans in Mongoose are plain JavaScript booleans. By default, Mongoose casts the below values to true:

  • true
  • 'true'
  • 1
  • '1'
  • 'yes'

Mongoose casts the below values to false:

  • false
  • 'false'
  • 0
  • '0'
  • 'no'

Any other value causes a CastError. You can modify what values Mongoose converts to true or false using the convertToTrue and convertToFalse properties, which are JavaScript sets.

  1. const M = mongoose.model('Test', new Schema({ b: Boolean }));
  2. console.log(new M({ b: 'nay' }).b); // undefined
  4. // Set { false, 'false', 0, '0', 'no' }
  5. console.log(mongoose.Schema.Types.Boolean.convertToFalse);
  7. mongoose.Schema.Types.Boolean.convertToFalse.add('nay');
  8. console.log(new M({ b: 'nay' }).b); // false

Arrays

Mongoose supports arrays of SchemaTypes and arrays of subdocuments. Arrays of SchemaTypes are also called primitive arrays, and arrays of subdocuments are also called document arrays.

  1. const ToySchema = new Schema({ name: String });
  2. const ToyBoxSchema = new Schema({
  3.   toys: [ToySchema],
  4.   buffers: [Buffer],
  5.   strings: [String],
  6.   numbers: [Number]
  7.   // ... etc
  8. });

Arrays are special because they implicitly have a default value of [] (empty array).

  1. const ToyBox = mongoose.model('ToyBox', ToyBoxSchema);
  2. console.log((new ToyBox()).toys); // []

To overwrite this default, you need to set the default value to undefined

  1. const ToyBoxSchema = new Schema({
  2.   toys: {
  3.     type: [ToySchema],
  4.     default: undefined
  5.   }
  6. });

Note: specifying an empty array is equivalent to Mixed. The following all create arrays of Mixed:

  1. const Empty1 = new Schema({ any: [] });
  2. const Empty2 = new Schema({ any: Array });
  3. const Empty3 = new Schema({ any: [Schema.Types.Mixed] });
  4. const Empty4 = new Schema({ any: [{}] });

Maps

New in Mongoose 5.1.0

A MongooseMap is a subclass of JavaScript’s Map class. In these docs, we’ll use the terms ‘map’ and MongooseMap interchangeably. In Mongoose, maps are how you create a nested document with arbitrary keys.

Note: In Mongoose Maps, keys must be strings in order to store the document in MongoDB.

  1. const userSchema = new Schema({
  2.   // `socialMediaHandles` is a map whose values are strings. A map's
  3.   // keys are always strings. You specify the type of values using `of`.
  4.   socialMediaHandles: {
  5.     type: Map,
  6.     of: String
  7.   }
  8. });
  10. const User = mongoose.model('User', userSchema);
  11. // Map { 'github' => 'vkarpov15', 'twitter' => '@code_barbarian' }
  12. console.log(new User({
  13.   socialMediaHandles: {
  14.     github: 'vkarpov15',
  15.     twitter: '@code_barbarian'
  16.   }
  17. }).socialMediaHandles);

The above example doesn’t explicitly declare github or twitter as paths, but, since socialMediaHandles is a map, you can store arbitrary key/value pairs. However, since socialMediaHandles is a map, you must use .get() to get the value of a key and .set() to set the value of a key.

  1. const user = new User({
  2.   socialMediaHandles: {}
  3. });
  5. // Good
  6. user.socialMediaHandles.set('github', 'vkarpov15');
  7. // Works too
  8. user.set('socialMediaHandles.twitter', '@code_barbarian');
  9. // Bad, the `myspace` property will **not** get saved
  10. user.socialMediaHandles.myspace = 'fail';
  12. // 'vkarpov15'
  13. console.log(user.socialMediaHandles.get('github'));
  14. // '@code_barbarian'
  15. console.log(user.get('socialMediaHandles.twitter'));
  16. // undefined
  17. user.socialMediaHandles.github;
  19. // Will only save the 'github' and 'twitter' properties
  20. user.save();

Map types are stored as BSON objects in MongoDB. Keys in a BSON object are ordered, so this means the insertion order property of maps is maintained.

Mongoose supports a special $* syntax to populate all elements in a map. For example, suppose your socialMediaHandles map contains a ref:

  1. const userSchema = new Schema({
  2.   socialMediaHandles: {
  3.     type: Map,
  4.     of: new Schema({
  5.       handle: String,
  6.       oauth: {
  7.         type: ObjectId,
  8.         ref: 'OAuth'
  9.       }
  10.     })
  11.   }
  12. });
  13. const User = mongoose.model('User', userSchema);

To populate every socialMediaHandles entry’s oauth property, you should populate on socialMediaHandles.$*.oauth:

  1. const user = await User.findOne().populate('socialMediaHandles.$*.oauth');

Getters

Getters are like virtuals for paths defined in your schema. For example, let’s say you wanted to store user profile pictures as relative paths and then add the hostname in your application. Below is how you would structure your userSchema:

  1. const root = 'https://s3.amazonaws.com/mybucket';
  3. const userSchema = new Schema({
  4.   name: String,
  5.   picture: {
  6.     type: String,
  7.     get: v => `${root}${v}`
  8.   }
  9. });
  11. const User = mongoose.model('User', userSchema);
  13. const doc = new User({ name: 'Val', picture: '/123.png' });
  14. doc.picture; // 'https://s3.amazonaws.com/mybucket/123.png'
  15. doc.toObject({ getters: false }).picture; // '/123.png'

Generally, you only use getters on primitive paths as opposed to arrays or subdocuments. Because getters override what accessing a Mongoose path returns, declaring a getter on an object may remove Mongoose change tracking for that path.

  1. const schema = new Schema({
  2.   arr: [{ url: String }]
  3. });
  5. const root = 'https://s3.amazonaws.com/mybucket';
  7. // Bad, don't do this!
  8. schema.path('arr').get(v => {
  9.   return v.map(el => Object.assign(el, { url: root + el.url }));
  10. });
  12. // Later
  13. doc.arr.push({ key: String });
  14. doc.arr[0]; // 'undefined' because every `doc.arr` creates a new array!

Instead of declaring a getter on the array as shown above, you should declare a getter on the url string as shown below. If you need to declare a getter on a nested document or array, be very careful!

  1. const schema = new Schema({
  2.   arr: [{ url: String }]
  3. });
  5. const root = 'https://s3.amazonaws.com/mybucket';
  7. // Good, do this instead of declaring a getter on `arr`
  8. schema.path('arr.0.url').get(v => `${root}${v}`);

Schemas

To declare a path as another schema, set type to the sub-schema’s instance.

To set a default value based on the sub-schema’s shape, simply set a default value, and the value will be cast based on the sub-schema’s definition before being set during document creation.

  1. const subSchema = new mongoose.Schema({
  2.   // some schema definition here
  3. });
  5. const schema = new mongoose.Schema({
  6.   data: {
  7.     type: subSchema
  8.     default: {}
  9.   }
  10. });

Creating Custom Types

Mongoose can also be extended with custom SchemaTypes. Search the plugins site for compatible types like mongoose-long, mongoose-int32, and other types.

Read more about creating custom SchemaTypes here.

The `schema.path()` Function

The schema.path() function returns the instantiated schema type for a given path.

  1. const sampleSchema = new Schema({ name: { type: String, required: true } });
  2. console.log(sampleSchema.path('name'));
  3. // Output looks like:
  4. /**
  5.  * SchemaString {
  6.  *   enumValues: [],
  7.   *   regExp: null,
  8.   *   path: 'name',
  9.   *   instance: 'String',
  10.   *   validators: ...
  11.   */

You can use this function to inspect the schema type for a given path, including what validators it has and what the type is.

Further Reading