is-express-schema-valid
Middleware to validate json schema of
req.body
,req.params
andreq.query
. It is based on JSONSchema spec and is-my-json-valid that uses code generation to be extremely fast.
Install
npm install is-express-schema-valid --save
Usage
isExpressSchemaValid({ payload, query, params }, options)
Create schema validation middleware using the specified keys for each type of request data:
payload
schema object validatesreq.body
params
schema object validatesreq.params
query
schema object validatesreq.query
Options
filter
- filter away fields that are not in the schema, defaults tofalse
filterReadonly
- filter away fields that are marked asreadonly: true
in schema, defaults tofalse
Example
;;; const app = ; const loginSchema = payload: email: type: 'string' required: true format: 'email' password: type: 'string' required: true minLength: 1 ; app;app;app; { // if schema validation fails // this middleware won't be called} { // validation error will be passed as first argument // you can return it or match with your api responses} app;
Define schemas
When defining a schema for request's payload / params / query you are able to pass a plain object. In this case is-express-schema-valid
will automagically populate your schema with default object
properties:
const schema = payload: foo: type: 'string' required: true ; // will be passed to validator as:// { // type: 'object', // required: true, // additionalProperties: false, // properties: { // foo: { // type: 'string', // required: true // }// }// }
In other cases when you need a different type
use a full schema. For example, when payload needs to be an array
:
const schema = payload: type: 'array' uniqueItems: true items: type: 'number' ; // it will be used as is by validator
Formats
There are several additional formats added for easy validating the requests:
"mongo-object-id"
- check if the string is a valid hex-encoded representation of a MongoDB ObjectId"alpha"
- check if the string contains only letters (a-zA-Z)"alphanumeric"
- check if the string contains only letters and numbers"numeric"
- check if the string contains only numbers"hexadecimal"
- check if the string is a hexadecimal number"hexcolor"
- check if the string is a hexadecimal color"base64"
- check if a string is Base64 encoded"decimal"
- check if a string is a decimal number, such as 0.1, .3, 1.1, 1.00003, 4.0, etc."int"
- check if a string is an integer"float"
- check if a string is a float"uuid"
- check if the string is UUID
In the example below we can ensure that id passed as param is valid MongoDB ObjectId:
; const schema = params: id: type: 'string' format: 'mongo-object-id' ; app;
Just a reminder that there are default built-in formats supported by JSONSchema:
"date-time"
- date representation, as defined by RFC 3339, section 5.6."email"
- internet email address, see RFC 5322, section 3.4.1."hostname"
- internet host name, see RFC 1034, section 3.1."ipv4"
- IPv4 address, according to dotted-quad ABNF syntax as defined in RFC 2673, section 3.2."ipv6"
- IPv6 address, as defined in RFC 2373, section 2.2."uri"
- a universal resource identifier (URI), according to RFC3986.
Errors
If provided data doesn't match provided schema is-express-schema-valid middleware passes instance of SchemaValidationError
class down to your app's error handler middleware:
; { // handle schema validation error if err instanceof SchemaValidationError // check lists of errors for each schema console; // { payload: [...], query: [...], params: [...] } }
JSONSchema
In order to get comfortable with JSONSchema spec and its' features I advice you to check the book "Understanding JSON Schema" (also PDF version) or look at examples.
MIT Licensed