Skip to content


Subversion checkout URL

You can clone with
Download ZIP
JSON spec validator for RESTful APIs
JavaScript CSS
Branch: master
Failed to load latest commit information.
.gitignore - initial commit


Request data validating library for RESTful APIs. rest-pec can validate POST/PUT/PATCH JSON data as well as GET/DELETE query string parameters using JSON schema and is easy to use with express.js. It generates endpoint documentation on the fly too.


Say, we run an API for a blog. We could define our schema for a blog post like this and save it in a post.json file:

    "type": "object",
    "properties": {
        "title": {
            "type": "string", 
            "description": "Title of the post."
        "body": {
            "type": "string",
            "description": "Text body of the post"
        "tags": {
            "type": "array",
            "items": { "type": "string" },
            "uniqueItems": true,
            "description": "Post tags"
    "required": ["title", "body"],
    "additionalProperties": false,
    "description": "Blog post"

Our API code references this schema in a middleware that will return a 422 reponse with a list of errors before the main body of the endpoint is executed. The name of the schema is taken from the filename.

var express = require('express');
var RestSpec = require('rest-spec');
var schema = RestSpec.validator(__dirname); // look for spec files in current directory
var storage = require('myWickedStorage');

var app = express();'/posts', schema('post'), function(req, res, next) {
    var newPost = req.body;
    newPost = storage.posts.add(newPost, function(post) {
    }, function(error) {
        res.json(400, error);

// make API documentation accessible at `/docs/` URL. 
RestSchema.explorer('/docs', app)

console.log('Running API on port 3000');

POSTing malformed request will make API return 422 with the reason:

$ curl -XPOST -H "Content-Type: application/json" -d '{"title": "My first post", "kittens": true}' http://localhost:3000/posts

  "description": "Some fields failed to validate",
  "fields": [
      "field": "body",
      "error": "Required."
      "field": "kittens",
      "error": "Extra field not allowed"

Note the explorer bit in the api code:

RestSchema.explorer('/docs', app)

It maps dynamically generated documentation to /docs.

Something went wrong with that request. Please try again.