Validation and Serialization

Fastify uses a schema-based approach, and even if it is not mandatory we recommend using JSON Schema to validate your routes and serialize your outputs. Internally, Fastify compiles the schema into a highly performant function.

⚠ Security Notice

Treat the schema definition as application code. As both validation and serialization features dynamically evaluate code with new Function(), it is not safe to use user-provided schemas. See Ajv and fast-json-stringify for more details.

Core concepts

The validation and the serialization tasks are processed by two different, and customizable, actors:

These two separate entities share only the JSON schemas added to Fastify’s instance through .addSchema(schema).

Adding a shared schema

Thanks to the addSchema API, you can add multiple schemas to the Fastify instance and then reuse them in multiple parts of your application. As usual, this API is encapsulated.

The shared schemas can be reused through the JSON Schema $ref keyword. Here an overview on how references work:

  • myField: { $ref: '#foo'} will search for field with $id: '#foo' inside the current schema
  • myField: { $ref: '#/definitions/foo'} will search for field definitions.foo inside the current schema
  • myField: { $ref: 'http://url.com/sh.json#'} will search for a shared schema added with $id: 'http://url.com/sh.json'
  • myField: { $ref: 'http://url.com/sh.json#/definitions/foo'} will search for a shared schema added with $id: 'http://url.com/sh.json' and will use the field definitions.foo
  • myField: { $ref: 'http://url.com/sh.json#foo'} will search for a shared schema added with $id: 'http://url.com/sh.json' and it will look inside of it for object with $id: '#foo'

Simple usage:

  1. fastify.addSchema({
  2.   $id: 'http://example.com/',
  3.   type: 'object',
  4.   properties: {
  5.     hello: { type: 'string' }
  6.   }
  7. })
  9. fastify.post('/', {
  10.   handler () {},
  11.   schema: {
  12.     body: {
  13.       type: 'array',
  14.       items: { $ref: 'http://example.com#/properties/hello' }
  15.     }
  16.   }
  17. })

$ref as root reference:

  1. fastify.addSchema({
  2.   $id: 'commonSchema',
  3.   type: 'object',
  4.   properties: {
  5.     hello: { type: 'string' }
  6.   }
  7. })
  9. fastify.post('/', {
  10.   handler () {},
  11.   schema: {
  12.     body: { $ref: 'commonSchema#' },
  13.     headers: { $ref: 'commonSchema#' }
  14.   }
  15. })

Retrieving the shared schemas

If the validator and the serializer are customized, the .addSchema method will not be useful since the actors are no longer controlled by Fastify. So, to access the schemas added to the Fastify instance, you can simply use .getSchemas():

  1. fastify.addSchema({
  2.   $id: 'schemaId',
  3.   type: 'object',
  4.   properties: {
  5.     hello: { type: 'string' }
  6.   }
  7. })
  9. const mySchemas = fastify.getSchemas()
  10. const mySchema = fastify.getSchema('schemaId')

As usual, the function getSchemas is encapsulated and returns the shared schemas available in the selected scope:

  1. fastify.addSchema({ $id: 'one', my: 'hello' })
  2. // will return only `one` schema
  3. fastify.get('/', (request, reply) => { reply.send(fastify.getSchemas()) })
  5. fastify.register((instance, opts, done) => {
  6.   instance.addSchema({ $id: 'two', my: 'ciao' })
  7.   // will return `one` and `two` schemas
  8.   instance.get('/sub', (request, reply) => { reply.send(instance.getSchemas()) })
  10.   instance.register((subinstance, opts, done) => {
  11.     subinstance.addSchema({ $id: 'three', my: 'hola' })
  12.     // will return `one`, `two` and `three`
  13.     subinstance.get('/deep', (request, reply) => { reply.send(subinstance.getSchemas()) })
  14.     done()
  15.   })
  16.   done()
  17. })

Validation

The route validation internally relies upon Ajv, which is a high-performance JSON Schema validator. Validating the input is very easy: just add the fields that you need inside the route schema, and you are done!

The supported validations are:

  • body: validates the body of the request if it is a POST or a PUT.
  • querystring or query: validates the query string.
  • params: validates the route params.
  • headers: validates the request headers.

All the validations can be a complete JSON Schema object (with a type property of 'object' and a 'properties' object containing parameters) or a simpler variation in which the type and properties attributes are forgone and the parameters are listed at the top level (see the example below).

Example:

  1. const bodyJsonSchema = {
  2.   type: 'object',
  3.   required: ['requiredKey'],
  4.   properties: {
  5.     someKey: { type: 'string' },
  6.     someOtherKey: { type: 'number' },
  7.     requiredKey: {
  8.       type: 'array',
  9.       maxItems: 3,
  10.       items: { type: 'integer' }
  11.     },
  12.     nullableKey: { type: ['number', 'null'] }, // or { type: 'number', nullable: true }
  13.     multipleTypesKey: { type: ['boolean', 'number'] },
  14.     multipleRestrictedTypesKey: {
  15.       oneOf: [
  16.         { type: 'string', maxLength: 5 },
  17.         { type: 'number', minimum: 10 }
  18.       ]
  19.     },
  20.     enumKey: {
  21.       type: 'string',
  22.       enum: ['John', 'Foo']
  23.     },
  24.     notTypeKey: {
  25.       not: { type: 'array' }
  26.     }
  27.   }
  28. }
  30. const queryStringJsonSchema = {
  31.   type: 'object',
  32.   properties: {
  33.     name: { type: 'string' },
  34.     excitement: { type: 'integer' }
  35.   }
  36. }
  38. const paramsJsonSchema = {
  39.   type: 'object',
  40.   properties: {
  41.     par1: { type: 'string' },
  42.     par2: { type: 'number' }
  43.   }
  44. }
  46. const headersJsonSchema = {
  47.   type: 'object',
  48.   properties: {
  49.     'x-foo': { type: 'string' }
  50.   },
  51.   required: ['x-foo']
  52. }
  54. const schema = {
  55.   body: bodyJsonSchema,
  56.   querystring: queryStringJsonSchema,
  57.   params: paramsJsonSchema,
  58.   headers: headersJsonSchema
  59. }
  61. fastify.post('/the/url', { schema }, handler)

Note that Ajv will try to coerce the values to the types specified in your schema type keywords, both to pass the validation and to use the correctly typed data afterwards.

The Ajv default configuration in Fastify doesn’t support coercing array parameters in querystring. However, Fastify allows customOptions in Ajv instance. The coerceTypes: 'array' will coerce one parameter to a single element in array. Example:

  1. const opts = {
  2.   schema: {
  3.     querystring: {
  4.       type: 'object',
  5.       properties: {
  6.         ids: {
  7.           type: 'array',
  8.           default: []
  9.         },
  10.       },
  11.     }
  12.   }
  13. }
  15. fastify.get('/', opts, (request, reply) => {
  16.   reply.send({ params: request.query })
  17. })
  19. fastify.listen(3000, (err) => {
  20.   if (err) throw err
  21. })

Using Fastify defaults the following request will result in 400 status code:

  1. curl -X GET "http://localhost:3000/?ids=1
  3. {"statusCode":400,"error":"Bad Request","message":"querystring/hello should be array"}

Using coerceTypes as ‘array’ should fix it:

  1. const ajv = new Ajv({
  2.   removeAdditional: true,
  3.   useDefaults: true,
  4.   coerceTypes: 'array', // This line
  5.   allErrors: true
  6. })
  8. fastify.setValidatorCompiler(({ schema, method, url, httpPart }) => {
  9.   return ajv.compile(schema)
  10. })
  1. curl -X GET "http://localhost:3000/?ids=1
  3. {"params":{"hello":["1"]}}

For further information see here

Ajv Plugins

You can provide a list of plugins you want to use with Ajv:

Refer to ajv options to check plugins format

  1. const fastify = require('fastify')({
  2.   ajv: {
  3.     plugins: [
  4.       require('ajv-merge-patch')
  5.     ]
  6.   }
  7. })
  9. fastify.post('/', {
  10.   handler (req, reply) { reply.send({ ok: 1 }) },
  11.   schema: {
  12.     body: {
  13.       $patch: {
  14.         source: {
  15.           type: 'object',
  16.           properties: {
  17.             q: {
  18.               type: 'string'
  19.             }
  20.           }
  21.         },
  22.         with: [
  23.           {
  24.             op: 'add',
  25.             path: '/properties/q',
  26.             value: { type: 'number' }
  27.           }
  28.         ]
  29.       }
  30.     }
  31.   }
  32. })
  34. fastify.post('/foo', {
  35.   handler (req, reply) { reply.send({ ok: 1 }) },
  36.   schema: {
  37.     body: {
  38.       $merge: {
  39.         source: {
  40.           type: 'object',
  41.           properties: {
  42.             q: {
  43.               type: 'string'
  44.             }
  45.           }
  46.         },
  47.         with: {
  48.           required: ['q']
  49.         }
  50.       }
  51.     }
  52.   }
  53. })

Validator Compiler

The validatorCompiler is a function that returns a function that validates the body, url parameters, headers, and query string. The default validatorCompiler returns a function that implements the ajv validation interface. Fastify uses it internally to speed the validation up.

Fastify’s baseline ajv configuration is:

  1. {
  2.   removeAdditional: true, // remove additional properties
  3.   useDefaults: true, // replace missing properties and items with the values from corresponding default keyword
  4.   coerceTypes: true, // change data type of data to match type keyword
  5.   nullable: true     // support keyword "nullable" from Open API 3 specification.
  6. }

This baseline configuration can be modified by providing ajv.customOptions to your Fastify factory.

If you want to change or set additional config options, you will need to create your own instance and override the existing one like:

  1. const fastify = require('fastify')()
  2. const Ajv = require('ajv')
  3. const ajv = new Ajv({
  4.   // the fastify defaults (if needed)
  5.   removeAdditional: true,
  6.   useDefaults: true,
  7.   coerceTypes: true,
  8.   nullable: true,
  9.   // any other options
  10.   // ...
  11. })
  12. fastify.setValidatorCompiler(({ schema, method, url, httpPart }) => {
  13.   return ajv.compile(schema)
  14. })

*Note: If you use a custom instance of any validator (even Ajv), you have to add schemas to the validator instead of fastify, since fastify’s default validator is no longer used, and fastify’s addSchema method has no idea what validator you are using.*

Using other validation libraries

The setValidatorCompiler function makes it easy to substitute ajv with almost any Javascript validation library (joi, yup, …) or a custom one:

  1. const Joi = require('@hapi/joi')
  3. fastify.post('/the/url', {
  4.   schema: {
  5.     body: Joi.object().keys({
  6.       hello: Joi.string().required()
  7.     }).required()
  8.   },
  9.   validatorCompiler: ({ schema, method, url, httpPart }) => {
  10.     return data => schema.validate(data)
  11.   }
  12. }, handler)
  1. const yup = require('yup')
  2. // Validation options to match ajv's baseline options used in Fastify
  3. const yupOptions = {
  4.   strict: false,
  5.   abortEarly: false, // return all errors
  6.   stripUnknown: true, // remove additional properties
  7.   recursive: true
  8. }
  10. fastify.post('/the/url', {
  11.   schema: {
  12.     body: yup.object({
  13.       age: yup.number().integer().required(),
  14.       sub: yup.object().shape({
  15.         name: yup.string().required()
  16.       }).required()
  17.     })
  18.   },
  19.   validatorCompiler: ({ schema, method, url, httpPart }) => {
  20.     return function (data) {
  21.       // with option strict = false, yup `validateSync` function returns the coerced value if validation was successful, or throws if validation failed
  22.       try {
  23.         const result = schema.validateSync(data, yupOptions)
  24.         return { value: result }
  25.       } catch (e) {
  26.         return { error: e }
  27.       }
  28.     }
  29.   }
  30. }, handler)
Validation messages with other validation libraries

Fastify’s validation error messages are tightly coupled to the default validation engine: errors returned from ajv are eventually run through the schemaErrorsText function which is responsible for building human-friendly error messages. However, the schemaErrorsText function is written with ajv in mind : as a result, you may run into odd or incomplete error messages when using other validation libraries.

To circumvent this issue, you have 2 main options :

  1. make sure your validation function (returned by your custom schemaCompiler) returns errors in the exact same structure and format as ajv (although this could prove to be difficult and tricky due to differences between validation engines)
  2. or use a custom errorHandler to intercept and format your ‘custom’ validation errors

To help you in writing a custom errorHandler, Fastify adds 2 properties to all validation errors:

  • validation: the content of the error property of the object returned by the validation function (returned by your custom schemaCompiler)
  • validationContext: the ‘context’ (body, params, query, headers) where the validation error occurred

A very contrived example of such a custom errorHandler handling validation errors is shown below:

  1. const errorHandler = (error, request, reply) => {
  2.   const statusCode = error.statusCode
  3.   let response
  5.   const { validation, validationContext } = error
  7.   // check if we have a validation error
  8.   if (validation) {
  9.     response = {
  10.       // validationContext will be 'body' or 'params' or 'headers' or 'query'
  11.       message: `A validation error occurred when validating the ${validationContext}...`,
  12.       // this is the result of your validation library...
  13.       errors: validation
  14.     }
  15.   } else {
  16.     response = {
  17.       message: 'An error occurred...'
  18.     }
  19.   }
  21.   // any additional work here, eg. log error
  22.   // ...
  24.   reply.status(statusCode).send(response)
  25. }

Serialization

Usually you will send your data to the clients as JSON, and Fastify has a powerful tool to help you, fast-json-stringify, which is used if you have provided an output schema in the route options. We encourage you to use an output schema, as it can drastically increase throughput and help prevent accidental disclosure of sensitive information.

Example:

  1. const schema = {
  2.   response: {
  3.     200: {
  4.       type: 'object',
  5.       properties: {
  6.         value: { type: 'string' },
  7.         otherValue: { type: 'boolean' }
  8.       }
  9.     }
  10.   }
  11. }
  13. fastify.post('/the/url', { schema }, handler)

As you can see, the response schema is based on the status code. If you want to use the same schema for multiple status codes, you can use '2xx', for example:

  1. const schema = {
  2.   response: {
  3.     '2xx': {
  4.       type: 'object',
  5.       properties: {
  6.         value: { type: 'string' },
  7.         otherValue: { type: 'boolean' }
  8.       }
  9.     },
  10.     201: {
  11.       // the contract syntax
  12.       value: { type: 'string' }
  13.     }
  14.   }
  15. }
  17. fastify.post('/the/url', { schema }, handler)

Serializer Compiler

The serializerCompiler is a function that returns a function that must return a string from an input object. You must provide a function to serialize every route where you have defined a response JSON Schema.

  1. fastify.setSerializerCompiler(({ schema, method, url, httpStatus }) => {
  2.   return data => JSON.stringify(data)
  3. })
  5. fastify.get('/user', {
  6.   handler (req, reply) {
  7.     reply.send({ id: 1, name: 'Foo', image: 'BIG IMAGE' })
  8.   },
  9.   schema: {
  10.     response: {
  11.       '2xx': {
  12.         id: { type: 'number' },
  13.         name: { type: 'string' }
  14.       }
  15.     }
  16.   }
  17. })

If you need a custom serializer in a very specific part of your code, you can set one with reply.serializer(...).

Error Handling

When schema validation fails for a request, Fastify will automatically return a status 400 response including the result from the validator in the payload. As an example, if you have the following schema for your route

  1. const schema = {
  2.   body: {
  3.     type: 'object',
  4.     properties: {
  5.       name: { type: 'string' }
  6.     },
  7.     required: ['name']
  8.   }
  9. }

and fail to satisfy it, the route will immediately return a response with the following payload

  1. {
  2.   "statusCode": 400,
  3.   "error": "Bad Request",
  4.   "message": "body should have required property 'name'"
  5. }

If you want to handle errors inside the route, you can specify the attachValidation option for your route. If there is a validation error, the validationError property of the request will contain the Error object with the raw validation result as shown below

  1. const fastify = Fastify()
  3. fastify.post('/', { schema, attachValidation: true }, function (req, reply) {
  4.   if (req.validationError) {
  5.     // `req.validationError.validation` contains the raw validation error
  6.     reply.code(400).send(req.validationError)
  7.   }
  8. })

schemaErrorFormatter

If you want to format errors yourself, you can provide a sync function that must return an error as the schemaErrorFormatter option to Fastify when instantiating. The context function will be the Fastify server instance.

errors is an array of Fastify schema errors FastifySchemaValidationError. dataVar is the currently validated part of the schema. (params | body | querystring | headers).

  1. const fastify = Fastify({
  2.   schemaErrorFormatter: (errors, dataVar) => {
  3.     // ... my formatting logic
  4.     return new Error(myErrorMessage)
  5.   }
  6. })
  8. // or
  9. fastify.setSchemaErrorFormatter(function (errors, dataVar) {
  10.   this.log.error({ err: errors }, 'Validation failed')
  11.   // ... my formatting logic
  12.   return new Error(myErrorMessage)
  13. })

You can also use setErrorHandler to define a custom response for validation errors such as

  1. fastify.setErrorHandler(function (error, request, reply) {
  2.   if (error.validation) {
  3.      reply.status(422).send(new Error('validation failed'))
  4.   }
  5. })

If you want custom error response in schema without headaches and quickly, you can take a look at ajv-errors. Checkout the example usage.

Below is an example showing how to add custom error messages for each property of a schema by supplying custom AJV options. Inline comments in the schema below describe how to configure it to show a different error message for each case:

  1. const fastify = Fastify({
  2.   ajv: {
  3.     customOptions: { jsonPointers: true },
  4.     plugins: [
  5.       require('ajv-errors')
  6.     ]
  7.   }
  8. })
  10. const schema = {
  11.   body: {
  12.     type: 'object',
  13.     properties: {
  14.       name: {
  15.         type: 'string',
  16.         errorMessage: {
  17.           type: 'Bad name'
  18.         }
  19.       },
  20.       age: {
  21.         type: 'number',
  22.         errorMessage: {
  23.           type: 'Bad age', // specify custom message for
  24.           min: 'Too young' // all constraints except required
  25.         }
  26.       }
  27.     },
  28.     required: ['name', 'age'],
  29.     errorMessage: {
  30.       required: {
  31.         name: 'Why no name!', // specify error message for when the
  32.         age: 'Why no age!' // property is missing from input
  33.       }
  34.     }
  35.   }
  36. }
  38. fastify.post('/', { schema, }, (request, reply) => {
  39.   reply.send({
  40.     hello: 'world'
  41.   })
  42. })

If you want to return localized error messages, take a look at ajv-i18n

  1. const localize = require('ajv-i18n')
  3. const fastify = Fastify()
  5. const schema = {
  6.   body: {
  7.     type: 'object',
  8.     properties: {
  9.       name: {
  10.         type: 'string',
  11.       },
  12.       age: {
  13.         type: 'number',
  14.       }
  15.     },
  16.     required: ['name', 'age'],
  17.   }
  18. }
  20. fastify.setErrorHandler(function (error, request, reply) {
  21.   if (error.validation) {
  22.     localize.ru(error.validation)
  23.     reply.status(400).send(error.validation)
  24.     return
  25.   }
  26.   reply.send(error)
  27. })

JSON Schema support

JSON Schema has some type of utilities in order to optimize your schemas that, in conjunction with the Fastify’s shared schema, let you reuse all your schemas easily.

Use CaseValidatorSerializer
$ref to $id️️✔️✔️
$ref to /definitions✔️✔️
$ref to shared schema $id✔️✔️
$ref to shared schema /definitions✔️✔️

Examples

Usage of $ref to $id in same JSON Schema
  1. const refToId = {
  2.   type: 'object',
  3.   definitions: {
  4.     foo: {
  5.       $id: '#address',
  6.       type: 'object',
  7.       properties: {
  8.         city: { type: 'string' }
  9.       }
  10.     }
  11.   },
  12.   properties: {
  13.     home: { $ref: '#address' },
  14.     work: { $ref: '#address' }
  15.   }
  16. }
Usage of $ref to /definitions in same JSON Schema
  1. const refToDefinitions = {
  2.   type: 'object',
  3.   definitions: {
  4.     foo: {
  5.       $id: '#address',
  6.       type: 'object',
  7.       properties: {
  8.         city: { type: 'string' }
  9.       }
  10.     }
  11.   },
  12.   properties: {
  13.     home: { $ref: '#/definitions/foo' },
  14.     work: { $ref: '#/definitions/foo' }
  15.   }
  16. }
Usage $ref to a shared schema $id as external schema
  1. fastify.addSchema({
  2.   $id: 'http://foo/common.json',
  3.   type: 'object',
  4.   definitions: {
  5.     foo: {
  6.       $id: '#address',
  7.       type: 'object',
  8.       properties: {
  9.         city: { type: 'string' }
  10.       }
  11.     }
  12.   }
  13. })
  15. const refToSharedSchemaId = {
  16.   type: 'object',
  17.   properties: {
  18.     home: { $ref: 'http://foo/common.json#address' },
  19.     work: { $ref: 'http://foo/common.json#address' }
  20.   }
  21. }
Usage $ref to a shared schema /definitions as external schema
  1. fastify.addSchema({
  2.   $id: 'http://foo/shared.json',
  3.   type: 'object',
  4.   definitions: {
  5.     foo: {
  6.       type: 'object',
  7.       properties: {
  8.         city: { type: 'string' }
  9.       }
  10.     }
  11.   }
  12. })
  14. const refToSharedSchemaDefinitions = {
  15.   type: 'object',
  16.   properties: {
  17.     home: { $ref: 'http://foo/shared.json#/definitions/foo' },
  18.     work: { $ref: 'http://foo/shared.json#/definitions/foo' }
  19.   }
  20. }

Resources