2.0.4 • Public • Published


    Build Status codecov

    Lightweight application-level schema for Javascript models.

    Why not Mongoose or another ORM

    ORMs don't cover completely the features that the official drivers have. Furthermore, ORMs are notorious for being slow compared to official drivers, and tend to be irregularly maintained as time goes on to be more prone to bugs.

    This module is made for those who are frustrated by reading two docs to communicate with one database. Having a separate Schema from built-in database schemas can be advantageous; data can be validated directly from your application instead of unnecessarily over network requests.

    Getting Started

    Don't be disheartened by all the constructors, they are there to modularize the logic and allow easy implementation of nested validation.

    var Schema = require('machiavelli').Schema
    var Field = Schema.Field;
    var postingSchema = new Schema({
        title: new Field({ type: String }),
        price: new Field({ type: Number }),
        description: new Field({ type: String, required: false })

    Synchronous validation

    var postingDocument = { title: 'Old windows mouse', price: 20 };
    if (postingSchema.isValid(postingDocument)) {
        /* save posting to database */
    } else {
        /* handle error */ 

    Asynchronous validation

    postingSchema.validate(posting, function (err, capturedPosting) {
        if (err) {
            /* handle error */
        } else {
            /* save posting to database, 
             * note that capturedPosting will have only the attributes
             * specified in the schema */

    Schema inheritance

    The inherits method need to be declared after schema declaration. Will not overwrite existing fields, but will inherit validation requirements of other fields.

    var ticketSchema = new Schema({ 
        artist: new Field({ type: String })

    Extending schemas

    A schema can be extended with new fields using the method addField()

        venue: new Field({ type: String, required: false }), 
        anotherField: new Field({ type: Number })

    Why use a Schema at all

    Light-weight schemas can provide another protection layer for malicious database injections.

    Using DataType

    Required is now true by default.

    var DataType = require('machiavelli').DataType;
    var ticketSchema = new Schema({
        _id: new Field({ type: DataType.ObjectID }),
        title: new Field({ type: DataType.String }), 
        price: new Field({ type: DataType.Integer, required: false }), 
        createdAt: new Field({ type: DataType.Date}),
        owner: {
            _id: new Field({ type: DataType.ObjectID }),
            username: new Field({ type: DataType.String })

    Machiavelli-Defined Types

    • Function
    • String
    • Integer
    • Double
    • Date
    • Boolean
    • Array

    Defining new data types

    Simply define a function that returns true if object is of type data type, else returns false. Here we define a new DataType called Coordinate.

    DataType.Coordinate = new DataType(function (coord) {
        var longitude = coord[0];
        var latitude = coord[1];
        return (longitude >= -180 && longitude <= 180) && 
            (latitude >= -90 && latitude <= 90)

    Your own wrappers

    If your data is already wrapped in your own constructor, there is no need to define a new function.

    var Animal = function (specie) { this.specie = specie }
    var zooSchema = new Schema({ 
        animal: new Field({ type: Animal })

    Collection Validation @notImplemented

    DataType.isValidCollection() validates type on a collection level


    Optional keys

    We have seen the the 'required' field, a boolean determining if Schema should fail if the field is not specified. Specifying the 'required' field, unlike the 'type' field, is optional since the default is set to true. There are many other arguments we could use to enhance our schema.

    validators - Custom validators

    The argument to 'validate' should always be in an array, even if it only contains one element.

    Functions specified under the validate argument should return a boolean that specifies whether or not the data is valid. Custom validators can be made by the Validator constructor which takes in arguments isValid as your validation function and error as your error throwing object.

    var isPositive = function (price) { return price >= 0; };
    var Validator = Field.Validator;
    var smallerThanTen = new Validator({ 
        isValid: function(price) { return price < 10 },
        error: new Error('Value not smaller than 10')
    var coffeeSchema = new Schema({
        flavor: new Field({ type: String }),
        price: new Field({ 
            type: Number,
            validators: [isPostive, smallerThanTen] 

    required - Default is true

    Specify required to be false if you want the Schema to not require the field in a document. If value passed to 'default' is a function, the schema will invocate the field's value at runtime.

    var dateSchema = new Schema({
        date: new Field({
           type: Number,


    Specify default value for capture function to pass in second argument of validate.

    Constructor tree

    Accessing the constructors from the module. They are organized less for accessibility than for logic. You will never need to use Validator without using Field, and never Field without using Schema. As for DataType, I found it can be used without Schema.



    Nested schemas

    Schemas can now specify attributes as nested schemas

    var helloSchema = {
        world: worldSchema


    Why so many constructors? While JavaScript is a dynamically-typed language, it can be extremely beneficial to separate concerns by using constructors as dependency injections. Hacking JavaScript can be both fast AND reliable!




    npm i machiavelli

    DownloadsWeekly Downloads






    Last publish


    • baoskee