JSON API validation in nodejs

is your payload valid

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.

8 thoughts on “JSON API validation in nodejs”

    1. It would be of course. But that’s the thing, if you know that you are getting the data pre-processed by some other engine or computation node then you don’t need this. I came across a issue where front-end submits the request to add something in database and i need to write code in order to know that payload is structured properly. There this is useful.

  1. Hi, this is really interesting, however, I does not help much in the scenario where a different team (or company) develop an api that you need to consume. On some web services, there used to be wsdl file, that you could query to know exactly what a service was asking for. Are the API services capable of doing that? Do you know a validator that could check against something like a wsdl to download the valid payload from the service?

    Thanks and regards.

    1. Hi David,

      I am not sure about any such service but will surely look for it and update you if there is any.

      As far as this package is concern, this can be used at places where you are consuming the API and doing processing over it like in Back-end systems. I am not sure about different team query ? Can you put more detail about this scenario.

      1. Oh thanks a lot for clarification. About the different teams it could be an scenario like this: I’m developing a node / express site, but for some actions I have to consume a Java API developed by other team from my company. Most of times they add new endpoints or update existing ones and there is no way to know what the API endpoint is expecting as payload. I mean, an updated wiki could resolve this, but the wsdl was used to check on service requests and responses for each one of the web methods, kind of service metadata. It would be awesome if there could be something to get the API endpoint metadata… like what is it expecting and what could return, without the need of updating a wiki, don’t you think?

        1. Oh i see. I haven’t worked on it so not sure about any such package. Will let you know if i come across any.

  2. benjamin Rampon

    This module is good, but i was looking for a payload validator, with content filtering, like “it’s a number between 5 & 18”, “it’s a string with 24 chars”, or even “it’s an object containing 2 strings”

    and i discovered the node module JOI


    This module allow so much validation on schema !

    1. Shahid (UnixRoot) Shaikh

      It looks good.

      For sanity validation you can also refer “validator” module available on NPM.

      I wrote article on this here.

Comments are closed.