Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Validate JSON objects against a schema written in JSON
tree: b3df86dad0

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


A lightweight, chaining validation library.

  • Zero dependencies. Can be used in browsers, Node, and Mongo/Couch Map/Reduce functions.
  • Recursively test JSON data structures.
  • Easy to extend with your own validations.
  • Excellent test coverage (run npm test).
    var Valid = require('valid');
    var inRange = Valid.number().min(4).max(9)
    inRange.check(3)            // check returns true/false, here it returns false
    inRange.test(12)            // returns "is not less than or equal to 9"

    Valid.optional().string().check(null);       // can be null, undefined, or a string
    Valid.array(Valid.integer).check([1,2,3]);   // checks each item in the array
    var isHex = Valid.match(/^[0-9A-F]$/i).message("should be a hexadecimal number");

    // test JSON structures:
    var Schema = {
        Name:     Valid.notBlank(),
        Address: {
            State:    /^[A-Z][A-Z]$/,  // shortcut for Valid.match(/^[A-Z][A-Z]$/)
            Country:  "US"

    var data = {
        Name:     "Jed",
        Numbers:  [1, 9, 25],
        Address: {
            State:    "CA",
            Country:  "US"


    // Easily define your own validations:
    Valid.isPowerOfTen = Valid.mod(10).message("should be a power of ten).define();

# Gruntles

This library is scary new.

- simplify error objects
- try to shrink the api, implement kitchen-sink
- npm publish
- pass a json schema to array()?  factor into RunSubtest & have everything call this.
- write isDate, isBefore, isAfter
- write isEmail() isIP() isUrl() isUUID()
- test coverage?
- Allow putting value first?  i.e. Valid(9).lt(12).gt(10) throws "9 is not greater than 10"
- write an assertion function?  Valid.assert(12).integer().min(5);
- convert to using nested functions instead of the `__queue` array?
- 'not' should try to modify the error message on the way through
- Valid.Escape needs some love
- do a doctest somehow

# Introduction

Valid allows you to declare a validation and then test it against
any number of values:

    var validation = Valid.integer().even().min(6);
    validation.check(9);      // returns "9 is not even"
    validation.isValid(10);   // returns true.

check() returns undefined if the validation succeeds, a string like "should not be null" if it fails, or an error object for JSON validations (see Errors below). isValid() just returns true or false.

Built-In Validations

This list is probably incomplete but the code at the bottom of valid.js should be reasonably readable.

  • Presence: defined(), undef(), *undefined(), nil(), *null(), notNull()
  • Pass error message to Valid constructor? make errorMessage a synonym for message?
  • Equality: equal(a[,b...]), notEqual(...), oneOf(arrayOrObject), *in(arrayOrObject)
  • Comparison: eq(n), lt(n), le(n), ge(n), gt(n), ne(n)
  • Numbers: number(), integer(), mod(x[,rem]), even(), odd()
  • Booleans: *boolean(), isTrue(), *true(), isFalse(), *false()
  • Arrays: array([validationForEachItem]), len(min,max), empty()
  • Strings: string(), len(min,max), blank(), notBlank()
  • Regexps: match(regex[,modifiers]), nomatch(regex[,modifiers])
  • Logic: and(test[,test...]), or(test[,test...]), not(test,message)
  • Utilities: nop(), fail([message]), message(msg), todo([test])
  • JSON: json(schema)

*: These function names are also JavaScript keywords. While Valid.undefined() works with a lot of interpreters, it doesn't work everywhere. Each keyword validation has a more compatible alternative that should be used instead: Valid.undef(), Valid.nil(), etc.


When a validation fails, check() returns a concise, positive message with the value implied at the front: "must be even", "can't be blank", etc. The messages are meant to be understandable by end users.

Concatenating the value and message is one obvioius use ("7 must be even"), but this style of wording is useful in other ways too. For instance, a web app can display the message to the right of the form element containing the error.

It's easy to supply your own error messages:

Valid.match(/-/).message("must contain a dash")

Because JSON validations need to return multiple errors, they return an object instead of a string. The value field contains the value that failed to validate.

        "Name"               : { message: "is blank", value: "" },
        "Addresses[0].State" : { message: "doesn't match /[A-Z][A-Z]/", value: "ca" }

Extending Valid

To define your own validations, just end the chain with "define()" and add it to the root object:

    Valid.latitude  =;
    Valid.longitude =;
    Valid.integer().latitude().isValid(20);  // true!

You can also add validations that take parameters:

    Valid.mod10 = function(rem) { return this.mod(10,rem).message("must end in" + rem); }
    Valid.mod10(6).check(127);   // returns "must end in 6"

Or just rename them:

    Valid.every = Valid.and;
    Valid.any = Valid.or;


On Node 0.4.x, if the console tries to print a Valid chain, you get this error:

> Valid.integer()
TypeError: Function.prototype.toString is not generic
    at Function.toString (native)
    at Array.toString (native)

It's a Node bug. 0.5.x does the correct thing and prints the chain:

> Valid.integer()
{ _queue: 
   [ { [Function: SimpleTest] data: [Object] },
     { [Function: SimpleTest] data: [Object] } ] }


  • The syntax is pretty sweet: check('abc').len(6,12).isEmail();
  • Only supports immediate use, can't declare validations.
  • Only meant to work inside node. Can't recurse over JSON.

  • Validates JSON using a declared schema.
  • Only supports static use, can't do immediate validations.
  • Produces unsatisfying error messages on deeply nested schemas.


Pain-free MIT.

Something went wrong with that request. Please try again.