Shorthand schema declaration for Mongoose

Usage no npm install needed!

<script type="module">
  import mongogo from '';



MIT licensed npm Coveralls branch Build Status Twitter

Mongogo is a small library that simplifies common schema declarations for Mongoose. It has been designed for simplicity and minimalism; its only dependency is Mongoose^4.


The aim of Mongogo is to provide a number of shorthand schema declaration methods that facilitate faster coding and more readable syntax.

With mongogo.Schema and mongogo.Model, when you specify your top-level fields as strings, it will convert them from Mongogo shorthand to their equivalent Mongoose JSON. Three additional methods, mongogo.field(), mongogo.option(), mongogo.index() are provided for using Mongogo shorthand in nested objects or other areas.


Regular Mongoose:

let mongoose = require('mongoose');

let schema = mongoose.Schema({
  username:       { type: String, unique: true },
  email:          { type: String, unique: true },
  first_name:     { type: String, trim: true },
  last_name:      { type: String, trim: true },
  age:            { type: number, min: 18, max: 100 },
  dob:            { type: Date, default: new Date(123467) },
  created:        { type: Date, default: },
  alive:          { type: Boolean, default: true },
  best_friend:    { type: mongoose.Schema.Types.ObjectId, ref: 'person' },
  favorite_thing: { type: mongoose.Schema.Type.ObjectId },
  parents: {
    father:       { type: mongoose.Schema.Types.ObjectId, ref: 'person' },
    mother:       { type: mongoose.Schema.Types.ObjectId, ref: 'person' },
  some_string:    String,
  job_title:      { type: String, index: true, sparse: true }
}, {
  timestamps: true,
  autoIndex: false,
  strict:   'throw'

schema.index({ username: 1, email: 1, dob: -1 }, { unique: true });
schema.index({ best_friend: 1, job_title: -1 }, { sparse: true });

schema.pre('find', ...);

module.exports = mongoose.model('person', schema);


import { mongogo, field, index } from 'mongogo';

let schema = mongogo.Schema({
  username:         'string,unique',
  email:            'string,unique',
  first_name:       'string,trim',
  last_name:        'string,trim',
  age:              'number,min:18,max:100',
  dob:              'date,default:1234567',
  created:          'now', // or the long way, 'date,default:now'
  alive:            'boolean,default:true',
  best_friend:      'ref:person,sparse',

  favorite_thing:    'id',
  parents: {
    father:     field('ref:person,index'),
    mother:     field('ref:person,index')

  // Any non-string field value is passed to Mongoose as-is.
  some_string:  String,
  job_title:    { type: String, index: true, sparse: true }
  'timestamps,ai:false,throw'      // Options

// Index shorthand

schema.pre('find', ...);

export default mongogo.mongoose.model('person', schema);

Mongogo Shorthand Model Syntax:

import { mongogo, field } from 'mongogo';

mongogo.Model('MyModel', {
  fields: {
    username:           'string,unique',
    email:              'string,unique',
    first_name:         'string,trim',
    last_name:          'string,trim',
    age:                'number,min:18,max:100',
    dob:                'date,default:1234567',
    created:            'now',
    alive:              'boolean,default:yes',
    best_friend:        'ref:person,sparse',

    favorite_thing:     'id',  
    parents: {
      father:           field('ref:person,index'),
      mother:           field('ref:person,index')

    some_string:        String,
    job_title:          { type: String, index: true, sparse: true }

  options: 'timestamps,ai:false,throw',

  index: [
    'username,+email,-dob,$unique', // shorthand
    { fields: { best_friend: 1, job_title: -1 }, options: { sparse: true }} // JSON declaration, if needed  

  statics: {
    findByUsername: function(username){
      return this.findOne({ username: username }).exec();

  methods: {
    isAlive: function(){
      return this.alive === true;
    cakeDay: function(){

  schema: function(schema){
    schema.pre('find', ...)

  connection: myMongoConnection // Optional - for use when you want to use your own connection, or `false` to return the generated schema without compiling model.


Mongogo's field and option keywords are available on the wiki, and in keywords.js.

Variable / Default Values

Mongogo converts default and variable values to the correct type for the following types:

  • String (simple strings only - read more below)
  • Boolean
  • Number
  • Date ('now' for or a number to use as a UNIX timestamp)

The other types (Buffer, Array, Mixed, ObjectId / id) cannot have default values specified. Mongogo is for shorthand, so in the event that you need to define these types, you should use regular Mongoose syntax instead.


The shorthand parser is very simple - if you need to specify string values, they too should be simple. You can use the extras parameter to specify more complex values.


field(`string,default:I am a string!,trim`);
field('string,trim', { default: "I, am, Silliam, Whattner!"});


The mongogo object exports the following:

import {
  default,      // Self-reference, for `import mongogo from 'mongogo';`
  mongogo,      // Self-reference, for import statements
  mongoose,     // Reference to require('mongoose')

  // Methods
  Schema,       // Schema method
  Model,        // Model method
  field,        // field method
  option,       // option method

  // Keywords
  fields,       // field keywords used by `field`
  keywords,     // semver compatibility - references `fields`
  options,      // options keywords used by `options`

  // Convenience
  ObjectId,     // Reference to mongoose ObjectId
  Mixed,        // Reference to mongoose Mixed

} from 'mongogo';

More Documentation on the Wiki

Complete documentation can be found on the Wiki.


Mongogo is licensed under the MIT License. (Readable in LICENSE) It's completely free to use for both personal and commercial purposes. Enjoy!