JSON API validation in nodejs

Building REST APIs comes with many challenges and one of them is making sure that incoming payload from client is valid and is in proper format before sending it to proper processing or doing some high cost operation such as SQL Operation or file operation. JSON API validation in nodejs is quite a over head work because we expect different kind of payload and data in API’s.

View on NPM View on Github

I was looking for something which does more than the sanity test i.e email type or empty strings etc. I wanted something which validates the structure of JSON payload with the one i am expecting for the API.

Unfortunately i haven’t found anything which suits my need so i worked on one. Its called “payload-validator” and it does the validation of your JSON structure for API’s.

JSON API validation in nodejs using payload-validator

To install payload-validator run following command.

npm install --save payload-validator

–save will write the package name in your JSON file.

How to use payload-validator

Payload-validator have just one function called “validator” and it accepts following parameter.

  • Incoming payload
  • Expected payload
  • Mandatory elements array
  • Blank value allowed flag

To use it in your code, require the payload-validator and call the validator function with above parameter. Here is sample example.

Require the module

var payloadChecker = require('payload-validator');

Call the validator function

var result = payloadChecker.validator(incoming-payload,expected-payload,["key1","key2"],false);
// Look for result.success key which will be true or false depending upon validation.
// if false look for result.response.errorMessage key to know more about the validator error.

Example project

Let’s develop one simple project which deals with JSON payload. Let’s create sample package.json using npm init command.

  "name": "payload-checker",
  "version": "1.0.0",
  "description": "",
  "main": "app.js",
  "scripts": {
    "test": "echo "Error: no test specified" && exit 1"
  "author": "",
  "license": "ISC"

Let’s install Express and payload-validator in our project. Run following command.

npm install --save express payload-validator body-parser

Let’s create our sample application file with Server code.

var express = require('express');
var bodyParser = require('body-parser');
var payloadChecker = require('payload-validator');
var app = express();
var router = express.Router();
var expectedPayload = {
    "name" : "",
    "message" : ""


    .get(function(req,res) {
        res.json({"message" : "GET not supported"});
    .post(function(req,res) {
        // cross check req.body.message payload
        if(req.body) {
            var result = payloadChecker.validator(req.body,expectedPayload,["name","message"],false);
            if(result.success) {
                res.json({"message" : "Payload is valid"});
            } else {
                res.json({"message" : result.response.errorMessage});
        } else {
            res.json({"message" : "paylod not correct"});

app.listen(3000,function() {
    console.log("App is running on port 3000");

Let’s run the app and check the module. Run the app by using following command.

node app.js

In order to hit the POST API open up your API simulator ( We recommend POSTMAN chrome extension ) and hit a POST request to localhost:3000/api.

Passing blank data

In this case we are passing blank value to mandatory fields. Even though blank flag is set as false but it will check for it because it is mandatory field.
Payload validation nodejs

Passing invalid data

In this case we are passing number instead of string. it will show following message.
payload validator node

Passing correct payload

payload validator node


If any bugs or feature request, please create an issue at github repo. You are more then welcome to fork and add more features into it.


Payload validator can help you in not doing repetitive validation every single time. It can also make sure that your app is getting correct data from client.


Founder of Codeforgeek. Technologist. Published Author. Engineer. Content Creator. Teaching Everything I learn!

Articles: 126