Validate.js

Supported runtimes

Validate.js works with any ECMAScript 5.1 runtime which means it works in both the browser and in node.js

All modern browsers are supported (IE9+, Firefox 3+, Opera 10.5+, Safari 4+).
IE8 support can likely be achived by polyfilling the following functions:

• Array.prototype.indexOf

Acknowledgements

• The design of these docs pages have been heavily inspired by backbonejs.org.
• All the validators have been inspired by Rails' validators.

var constraints = {
  username: {presence: true},
  password: {
    presence: true,
    length: {
      minimum: 6,
      message: "must be at least 6 characters"
    }
  }
};
validate({password: "bad"}, constraints);
// => {
//   "username": ["Username can't be blank"],
//   "password": ["Password must be at least 6 characters"]
// }

validate({username: "nicklas", password: "better"}, constraints);
// => undefined

validate({password: "better"}, constraints, {fullMessages: false})
// => {"username": ["can't be blank"]}

validate({}, constraints, {flatten: true})
// => ["Username can't be blank", "Password can't be blank"]

validate({}, {username: {presence: {message: "^You must pick a username"}}});
// => {"username": ["You must pick a username"]}
  

Async validation

Even though none of the built in validators are async it is sometimes useful to have async validations. One example would be to check if a username is already used by asking the server.

Validate.js supports async validations through the validate.async function. It has the same signature as the regular validation function and accepts the same options.

validate.async returns a Promise that is resolved if the validation passes and is rejected if the validation failed, passing the errors as the first argument.
The errors has the same format as the errors from the regular validation function.

You can use the async validate function even if no validations are async, it still returns a promise. You can not, however, use the regular function with async validations.

Any A+ type promise can be used, the following are supported out of the box (in order of precedence):

• ES6 promises (or the polyfill version)
• RSVP.js
• when
• Q

Validate.js looks for the promises in the global scope first and if it can't find it, it tries to import them using the require function if it exists. This means that AMD is supported but you will need to make sure that the implementation you want to use is loaded before you use the async function.

You can easily use any other A+ compatible Promise by simply setting validate.Promise to a function that accepts the promise callback and returns the created promise.
Please note that jQuery's promise implementation is not A+ compatible and will not work.

Example:

var success = function() {
      alert("The validations passed");
    }
  , error = function(errors) {
      alert(JSON.stringify(errors, null, 2));
    }
  , constraints = {name: {presence: true}};

// Will call the success function
validate.async({name: "Nicklas"}, constraints).then(success, error);

// Will call the error function
validate.async({}, constraints).then(success, error);

// Supporting another promise implementation, in this case we'll always use
// the ES6 promise
validate.Promise = function(callback) {
  return new Promise(callback);
};

Nested validation

Validate.js also has limited support for nested objects (objects within objects) using the dot notation.

The implementation is fairly basic and doesn't do anything clever with the messages. It doesn't support things like only validating a sub key if the parent key is present so for more advanced validations multiple validation schemas are recommended.

var constraints = {
  "addresses.shipping": {
    presence: true
  },
  "addresses.shipping.street": {
    format: {
      // Must be numbers followed by a name
      pattern: "^[0-9]+ .+$",
      message: "^The street for the shipping address must be a valid street name"
    }
  }
};

validate({}, constraints);
// => {"addresses.shipping": ["Addresses shipping can't be blank"]}

validate({addresses: {shipping: {street: "Foobar"}}}, constraints);
// => {"addresses.shipping.street": ["The street for the shipping address must be a valid street name"]}

validate({"foo.bar": 3}, {"foo\\.bar": {numericality: {even: true}}});
// => {"foo\.bar": ["Foo bar must be even"]}
            

validate.validators.custom = function(value, options, key, attributes) {
  console.log(value);
  console.log(options);
  console.log(key);
  console.log(attributes);
  return "is totally wrong";
};

// Will log:
//   - "some value"
//   - "some options"
//   - "foo"
//   - {"foo": "some value"}
validate({foo: "some value"}, {foo: {custom: "some options"}});
// => {foo: ["Foo is totally wrong"]}

Writing an async validator

Async validators are equal to a regular one in every way except in what they return. An async validator should return a promise (usually a validate.Promise instance).

The promise should be resolved if the validation passed and rejected if it fails giving the message as the first argument:

validate.validators.myAsyncValidator = function(value) {
  return validate.Promise(function(resolve, reject) {
    setTimeout(function() {
      if (value === "foo") resolve();
      else reject("is not foo");
    }, 100);
  });
};

var constraints = {name: {myAsyncValidator: true}}
  , success = alert.bind(this, "The validations passed")
  , error = function(errors) {
      alert(JSON.stringify(errors, null, 2));
    };

// Will call the success callback
validate.async({name: "foo"}, constraints).then(success, error);

// Will call the error callback with {name: ["Name is not foo"]} as the first argument
validate.async({name: "bar"}, constraints).then(success, error);

The presence validator validates that the value isn't empty. This validator will probably the most used one, it corresponds to HTML5's required attribute.
You can use the message option to customize the message. The default message is can't be blank.

These are the values that are considered empty:

• null
• undefined
• [] (empty objects)
• {} (empty arrays)
• "" (empty string)
• " " (whitespace only string)

Important! All other values are considered valid (including functions)!

validate({}, {username: {presence: true}})
// => {"username": ["Username can't be blank"]}

validate({username: "ansman"}, {username: {presence: true}})
// => undefined

validate({}, {username: {presence: {message: "is required"}}})
// => {"username": ["Username is required"]}

The length validator will check the length of a string.
Any object with the length property can be validated but all the default error messages refers to strings so make sure you override them if you plan on validating arrays using this.

You may specify the following length constraints:

is

The value has to have exactly this length. The default error is is the wrong length (should be %{count} characters)

minimum

The value cannot be shorter than this value. The default error is is too short (minimum is %{count} characters)

maximum

The value cannot be longer than this value. The default error is is too long (maximum is %{count} characters)

You can specify the error message using the wrongLength, tooShort and tooLong options. The default values are is the wrong length (should be %{count} characters), is too short (minimum is %{count} characters) and is too long (maximum is %{count} characters) respectively.

As you may have noticed you can use %{count} as a placeholder for the actual constraint and it will be replaced for you.

You can also use the message as the message for all errors (this overrides any other custom errors).

Per default the number of characters are counted (using the length property), if you want to count something else you can specify the tokenizer option which should be a function that takes a single argument (the value) and the returns a value that should be used when counting.

The tokenizer will never be called with nil or undefined as an argument.

var constraints = {
  key1: {length: {is: 3}},
  key2: {length: {minimum: 20}},
  key3: {length: {maximum: 3}},
  key4: {
    length: {
      minimum: 3,
      tooShort: "needs to have %{count} words or more",
      tokenizer: function(value) {
        return value.split(/\s+/g);
      }
    }
  }
};

validate({}, constraints);
// => undefined
// This is because nil and undefined are valid values.
// Use the presence validator if you don't want to allow empty values.

var values = {
  key1: "wrong length",
  key2: "too short",
  key3: "too long",
  key4: "too short"
};
validate(values, constraints);
// => {
//   "key1": ["Key1 is the wrong length (should be 3 characters)"],
//   "key2": ["Key2 is too short (minimum is 20 characters)"],
//   "key3": ["Key3 is too long (maximum is 3 characters)"],
//   "key4": ["Key4 needs to have 3 words or more"]
// }

The numericality validator will only allow numbers. Per default strings are coerced to numbers using the + operator If this is not desirable you can set the noStrings option to false to disable this behaviour.

The following rescriptions can be applied:

onlyInteger

Real numbers won't be allowed. The error message is must be an integer

greaterThan

The input has to be greater than this value. The error message is must be greater than %{count}

greaterThanOrEqualTo

The input has to be at least this value. The error message is must be greater than or equal to %{count}

equalTo

The input has to be exactly this value. The error message is must be equal to %{count}

lessThanOrEqualTo

The input can be this value at the most. The error message is must be less than or equal to %{count}

lessThan

The input has to be less than this value. The error message is must be less than %{count}

odd

The input has to be odd. The error message is must be odd

even

The input has to be even. The error message is must be even

If you want a custom error message you may specify it using the message option.

// null and undefined are valid values regardless of the options
validate({}, {duration: {numericality: true}});
//= > undefined

validate({duration: "foobar"}, {duration: {numericality: true}});
// => {"duration": ["Duration is not a number"]}

validate({duration: "3"}, {duration: {numericality: true}});
// => undefined

validate({duration: "3"}, {duration: {numericality: {noStrings: true}}});
// => {"duration": ["Duration is not a number"]}

var constraints = {
  duration: {
    numericality: {
      onlyInteger: true,
      greaterThan: 0,
      lessThanOrEqualTo: 30,
      even: true
    }
  }
};

validate({duration: 3.14}, constraints);
// => {"duration": ["Duration must be an integer"]}

validate({duration: 4711}, constraints);
// => {
//   "duration": [
//     "Duration must be less than or equal to 30",
//     "Duration must be even"
//   ]
// }

This datetime validator can be used to validate dates and times. The default implementation supports XDate and moment.js but it's easy to use any date library (see example below).

You can specify the follow constraints:

earliest

The date cannot be before this time. This argument will be parsed using the parse function, just like the value. The default error must be no earlier than %{date}

latest

The date cannot be after this time. This argument will be parsed using the parse function, just like the value. The default error must be no later than %{date}

dateOnly

If true, only dates (not datetimes) will be allowed. The default error is must be a valid date

dateFormat

The format for dates. The values for this will be different depending on which date library is used. Check the XDate or moment.js documentation for more information.

If you want to use some other library you can override the parse and format functions:

validate({}, {depature: {datetime: true}});
// => undefined

validate({departure: "foobar"}, {depature: {datetime: true}});
// => {"departure": ["Departure must be a valid date"]}

validate({departure: "2013-12-11 10:09:08", {departure: {datetime: true}}});
// => undefined

var constraints = {
  birthday: {
    datetime: {
      dateOnly: true,
      latest: XDate.today().addYears(-18),
      message: "^You need to be atleast 18 years old"
    }
  }
};

validate({birthday: "3013-11-14 22:34:52"}, constraints);
// => {"birthday": ["Birthday must be a valid date"]}

validate({birthday: "3013-11-14"}, constraints);
// => {"birthday": ["You need to be atleast 18 years old"]}


// If you want to use another library override the two methods below:

// Value will be the input (guaranteed not to be null or undefined) and options
// are options given to the validator.
// This function should return the number of milliseconds since the UTC epoch
// or NaN if it's not a valid date.
validate.validators.datetime.parse = function(value, options) {
  return new XDate(value, true).getTime();
};

// This function is only used when formatting dates for error messages.
// Value is the number of milliseconds since the UTC epoch.
// You should return a formatted strings of the given date.
// Make sure to check options.dateOnly and options.dateFormat when formatting.
validate.validators.datetime.format = function(value, options) {
  var format = options.dateFormat || (options.dateOnly ? "yyyy-MM-dd" : "u");
  return new XDate(date, true).toString(format);
};

You may also want to override the format function in order to customize the formatting of dates which are formatted as ISO8601 per default.
If you want to change the parsing but keep using XDate you can create a custom XDate parser.

The date validator is just a shorthand for the datetime validator with the dateOnly option set to true.

The format validator will validate a value against a regular expression of your chosing. The default message if the value doesn't match is is invalid so you'll likely want to customize it.

The pattern option can either be a javascript regexp or string that will be passed to the RegExp constructor. If the pattern is a string and you want to specify flags you may use the flags option.

Please note that the whole string must match the regexp, not just a part of the value.

var pattern = /\d{5}(-\d{4})?/;

validate({}, {zipCode: {format: pattern}});
// => undefined

validate({zipCode: "foobar"}, {zipCode: {format: pattern}});
// => {"zipCode": ["Zip code is invalid"]};

validate({zipCode: "12345"}, {zipCode: {format: pattern}});
// => undefined

var constraints = {
  username: {
    format: {
      pattern: "[a-z0-9]+",
      flags: "i",
      message: "can only contain a-z and 0-9"
    }
  }
};

validate({username: "Nicklas!"}, constraints);
// => {"username": ["Username can only contain a-z and 0-9"]}

validate({username: "Nicklas"}, constraints);
// => undefined

The inclusion validator is useful for validating input from a dropdown for example.
It checks that the given value exists in the list given by the within option.

You can specify within as a list or as an object (in which case the keys of the object are used).
The default message is ^%{value} is not included in the list

var sizes = ["small", "medium", "large"];

validate({}, {size: {inclusion: sizes}});
// => undefined

validate({size: "xlarge"}, {size: {inclusion: sizes}});
// => {"size": ["xlarge is not included in the list"]}

var constraints = {
  size: {
    inclusion: {
      within: {"Small": "s", "Medium": "m", "Large": "l"},
      message: "^We're currently out of %{value}"
    }
  }
};

validate({size: "Extra large"}, constraints);
// => {"size": ["We're currently out of Extra large"]}

validate({size: "Medium"}, constraints);
// => undefined

The exclusion validator is useful for restriction certain values.
It checks that the given value is not in the list given by the within option.

You can specify within as a list or as an object (in which case the keys of the object are used).
The default message is ^%{value} is restricted

var restrictedDomains = ["jp", "ch"];

validate({}, {subdomain: {exclusion: restrictedDomains}});
// => undefined

validate({subdomain: "jp"}, {subdomain: {exclusion: restrictedDomains}});
// => {"size": ["jp is restricted"]}

var constraints = {
  subdomain: {
    exclusion: {
      within: {jp: "Japan", "ch": "China"},
      message: "^We don't support %{value} right now, sorry"
    }
  }
};

validate({subdomain: "jp"}, constraints);
// => {"subdomain": ["We don't support jp right now, sorry"]}

validate({subdomain: "com"}, constraints);
// => undefined

The email validator attempts to make sure the input is a valid email.
Validating emails is tricky business due to the complex rules of email address formatting.

For example john.doe@gmail is a perfectly valid email but it's mostly likely just the case that John has forgotten to write .com at the end.

Validate.js tries to be pragmatic and allows most valid emails but tries to catch common typos such as forgetting the TLD.
If you want to know more about email validation the Wikipedia article and the email page on regular-expressions.info are good places to start.

You can customize the regexp used by setting validate.validators.email.PATTERN to a regexp of your chosing, just remember that javascript regexp does substring matching.

The default message is is not a valid email and as usual you can override it using the message option.

var constraints = {
  from: {
    email: true
  }
};

validate({from: null}, constraints);
// => undefined

validate({from: "nicklas@ansman"}, constraints);
// => {"email": ["From is not a valid email"]}

// Any TLD is allowed
validate({from: "nicklas@foo.faketld"}, constraints);
// => undefined

// Upper cased emails are allowed
validate({from: "NICKLAS@ANSMAN.SE"}, constraints);
// => undefined

constraints = {
  from: {
    email: {
      message: "doesn't look like a valid email"
    }
  }
};

validate({from: "foobar"}, constraints);
// => {"email": ["From doesn't look like a valid email"]}

// It allows unicode
validate({from: "first.läst@example.com"}, constraints);
// => undefined

node.js

Install it like every other npm package:

$ npm install validate.js

You can also add it to the dependencies section of your package.json like so:

{
  "dependencies": {
    "validate.js": "~0.3.1"
  }
}

Then in your code you can do something like this:

var validate = require("validate.js");

validate({}, {username: {presence: true}});
// => {"username": ["Username can't be blank"]};

Browser

Simply add this to your HTML:

<script src="path/to/validate.min.js"></script>

If you want to use Source Maps just place the validate.min.map file in the same directory as the javascript file.

If you're using a commonjs compatible AMD such as require.js you can use this code to include validate.js

require(["validate"], function(validate) {
  // Your code
});

Bower

To install using Bower just run:

$ bower install validate

or add it to your bower.json file:

{
  "dependencies": {
    "validate": "0.3.1"
  }
}

0.3.1 - Sep 22, 2014 - Docs - Diff

• Fix an issue with the date validator that made it unusable. Thanks mrdanimal for reporting this.

0.3.0 - Sep 5, 2014 - Docs - Diff

• Allow upper case letters in email addresses
• Breaking: Nested validation - periods can now be used for validated nested objects. Thanks colinskow for implementing this.
• Support moment.js for datetime parsing and formatting

0.2.0 - Jan 22, 2014 - Docs - Diff

• Fix a bug where functions were considered blank. Thanks MarFarMa for discovering and fixing this.
• Added support for AMD (require.js, commonjs etc). Thanks to zubulonj for this.
• Breaking: Dropped support for IE8
• Support for async validations

0.1.3 - Nov 26, 2013 - Docs - Diff

• Fix a bug where only upper cased 2 letter TLDs were allowed in the email validator
• More lax validation of the TLDs in the email validator

0.1.2 - Nov 25, 2013 - Docs - Diff

• Add bower.json
• Add an easy way of validating emails using the email validator

0.1.1 - Nov 16, 2013 - Docs - Diff

• Fix a bug when fullMessages was false and errors were prefixed by ^

0.1.0 - Nov 15, 2013 - Docs

• Initial release