express.js middleware for JSON schema validation.
- It makes setting up request validation simple and gets out of your way.
- It makes no assumptions about how you want to handle invalid data. Response status codes, message formatting, content type, and logging strategies are not one size fits all.
- It leverages the jsonschema library to conduct JSON schema validation.
jsonschemais popular (10K+ downloads / week) and adheres to the latest IETF published v4 draft of JSON schema.
- Simple - JSON schemas are a simple and expressive way to describe a data structure that your API expects.
- Standard - JSON schemas are not specific to javascript. They are used in many server side languages. The standard specification lives here jscon-schema.org.
- Fail-Fast - Validating a payload before handing it to your application code will catch errors early that would otherwise lead to more confusing errors later.
- Separate Validation - Manually inspecting a payload for errors can get lengthy and clutter up your application code.
- Error Messaging - Coming up with error messaging for every validation error becomes tedious and inconsistent.
- Documentation - Creating a JSON schema documents the API requirements.
$ npm install express-jsonschemavar express = require('express');
var app = express();
var validate = require('express-jsonschema').validate;
// Create a json scehma
var StreetSchema = {
type: 'object',
properties: {
number: {
type: 'number',
required: true
},
name: {
type: 'string',
required: true
},
type: {
type: 'string',
required: true
enum: ['Street', 'Avenue', 'Boulevard']
}
}
}
app.post('/street/', validate({body: StreetSchema}), function(req, res) {
// application code
});A valid post body:
{
number: 12,
name: 'Sycamore',
type: 'Street'
}An invalid post body:
{
number: '12', // This should be a number
// A 'name' key is missing
type: 'Drive' // 'Drive' is not one of the valid types
}Posting the above object would throw a JsonSchemaValidation instance that would look like this
jsonSchemaValidation.validations.body[0]
{
value: '12',
messages: ['is not of a type(s) integer'], // you can have multiple validations
property: 'request.body.number',
}
jsonSchemaValidation.validations.body[1]
{
messages: ['is required'],
property: 'request.body.name'
}
jsonSchemaValidation.validations.body[2]
{
value: 'Drive',
messages: ['is not one of enum values: Street, Avenue, Boulevard'],
property: 'request.body.type'
}Sometimes your route may depend on the body and query both having a specific format. In this
example I use body and query but you can choose to validate any request properties you'd like.
var TokenSchema = {
type: 'object',
properties: {
token: {
type: 'string',
format: 'alphanumeric',
minLength: 10,
maxLength: 10,
required: true
}
}
}
app.post('/street/', validate({body: StreetSchema, query: TokenSchema}), function(req, res) {
// application code
});A valid request would now also require a url like /street/?token=F42G5N5BGC.
As mentioned before, how one handles an invalid request depends on their application. You can easily
create some express error middleware to customize how your application behaves. When the validate middleware finds invalid data it passes an instance of JsonSchemaValidation to the
next middleware. Below is an example of how to handle invalid data.
app.use(function(err, req, res, next) {
var responseData;
if (err.name === 'JsonSchemaValidation') {
// Log the error however you please
console.log(err.message);
// logs "express-jsonschema: Invalid data found"
// Set a bad request http response status
res.status(400);
// Format the response body
responseData = {
statusText: 'Bad Request',
jsonSchemaValidation: true,
validations: err.validations // All of your validation information
};
// Respond with the right content type
if (req.xhr || req.get('Content-Type') === 'application/json') {
res.json(responseData);
} else {
res.render('badrequestTemplate', responseData);
}
} else {
// pass error to next error middleware handler
next(err);
}
});
While JSON schema comes with a lot of validation properties out of the box, you may want to add your own
custom properties. addSchemaProperties allows you to extend the validation properties that can be used in your
schemas. It should be called once at the beginning of your application so that your schemas will
have the custom properties available.
var addAttributes = require('express-jsonschema').addSchemaProperties;
addSchemaProperties({
contains: function(value, schema){
...
},
isDoubleQuoted: function(value, schema){
...
}
});See jsonschema's how to create custom properties.
var express = require('express');
var app = express();
var validate = require('express-jsonschema').validate;
// Address, to be embedded on Person
var AddressSchema = {
"id": "/SimpleAddress",
"type": "object",
"properties": {
"street": {"type": "string"},
"zip": {"type": "string"},
"city": {"type": "string"},
"state": {"type": "string"},
"country": {"type": "string"}
}
};
// Person
var PersonSchema = {
"id": "/SimplePerson",
"type": "object",
"properties": {
"name": {"type": "string"},
"address": {"$ref": "/SimpleAddress"}
}
};
app.post('/person/', validate({body: PersonSchema}, [AddressSchema]), function(req, res) {
// application code
});A valid post body:
{
"name": "Barack Obama",
"address": {
"street": "1600 Pennsylvania Avenue Northwest",
"zip": "20500",
"city": "Washington",
"state": "DC",
"country": "USA"
}
}- scpacetelescope's understanding json schema
- jsonschema
- json-schema.org
- json schema generator
- json schema google group
You can declare that something is required in your schema in two ways.
{
type: 'object',
properties: {
foo: {
type: 'string',
required: true
}
}
}
// OR
{
type: 'object',
properties: {
foo: {
type: 'string'
},
required: ['foo']
}
}The first method works as expected with jsonschema. The second way has a few gotchas. I recommend using the first.
Tests are written using mocha, should, and supertest.
npm test
express-jsonschema is licensed under MIT license.
Copyright (C) 2015 Adrian Adkison <adkison.adrian@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.