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. This 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 query parameters are listed at the top level (see the example below).
    • params: validates the route params.
    • headers: validates the request headers.

    Example:

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

    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.

    There are two ways to reuse your shared schemas:

    • $ref-way: as described in the standard, you can refer to an external schema. To use it you have to addSchema with a valid $id absolute URI.
    • replace-way: this is a Fastify utility that lets you to substitute some fields with a shared schema. To use it you have to addSchema with an $id having a relative URI fragment which is a simple string that applies only to alphanumeric chars [A-Za-z0-9].

    Here an overview on how to set an $id and how references to it:

    • replace-way
      • myField: 'foobar#' will search for a shared schema added with $id: 'foobar'
    • $ref-way
      • 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: ' will search for a shared schema added with $id: 'http://url.com/sh.json'
      • myField: { $ref: ' will search for a shared schema added with $id: 'http://url.com/sh.json' and will use the field definitions.foo
      • myField: { $ref: ' 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'

    More examples:

    $ref-way usage examples:

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

    replace-way usage examples:

    1. const fastify = require('fastify')()
    3. fastify.addSchema({
    4.   $id: 'greetings',
    5.   type: 'object',
    6.   properties: {
    7.     hello: { type: 'string' }
    8.   }
    9. })
    11. fastify.route({
    12.   method: 'POST',
    13.   url: '/',
    14.   schema: {
    15.     body: 'greetings#'
    16.   },
    17.   handler: () => {}
    18. })
    20. fastify.register((instance, opts, done) => {
    22.   /**
    23.    * In children's scope can use schemas defined in upper scope like 'greetings'.
    24.    * Parent scope can't use the children schemas.
    25.    */
    26.   instance.addSchema({
    27.     $id: 'framework',
    28.     type: 'object',
    29.     properties: {
    30.       fastest: { type: 'string' },
    31.       hi: 'greetings#'
    32.     }
    33.   })
    35.   instance.route({
    36.     method: 'POST',
    37.     url: '/sub',
    38.     schema: {
    39.       body: 'framework#'
    40.     },
    41.     handler: () => {}
    42.   })
    44.   done()
    45. })
    1. const fastify = require('fastify')()
    3. fastify.addSchema({
    4.   $id: 'greetings',
    5.   type: 'object',
    6.   properties: {
    7.     hello: { type: 'string' }
    8.   }
    9. })
    11. fastify.route({
    12.   method: 'POST',
    13.   url: '/',
    14.   schema: {
    15.     body: {
    16.       type: 'object',
    18.         greeting: 'greetings#',
    19.         timestamp: { type: 'number' }
    20.       }
    21.   },
    22.   handler: () => {}
    23. })

    Retrieving a copy of shared schemas

    The function getSchemas returns the shared schemas available in the selected scope:

    1. fastify.addSchema({ $id: 'one', my: 'hello' })
    2. fastify.get('/', (request, reply) => { reply.send(fastify.getSchemas()) })
    4. fastify.register((instance, opts, done) => {
    5.   instance.addSchema({ $id: 'two', my: 'ciao' })
    6.   instance.get('/sub', (request, reply) => { reply.send(instance.getSchemas()) })
    8.   instance.register((subinstance, opts, done) => {
    9.     subinstance.addSchema({ $id: 'three', my: 'hola' })
    10.     subinstance.get('/deep', (request, reply) => { reply.send(subinstance.getSchemas()) })
    11.     done()
    12.   })
    13.   done()
    14. })

    This example will returns:

    Schema Compiler

    The schemaCompiler is a function that returns a function that validates the body, url parameters, headers, and query string. The default schemaCompiler returns a function that implements the 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.   allErrors: true,   // check for all errors
    6.   nullable: true     // support keyword "nullable" from Open API 3 specification.
    7. }

    This baseline configuration cannot be modified. If you want to change or set additional config options, you will need to create your own instance and override the existing one like:

    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.

    But maybe you want to change the validation library. Perhaps you like Joi. In this case, you can use it to validate the url parameters, body, and query string!

    1. const Joi = require('joi')
    3. fastify.post('/the/url', {
    4.   schema: {
    5.     body: Joi.object().keys({
    6.       hello: Joi.string().required()
    7.     }).required()
    8.   },
    9.   schemaCompiler: schema => data => Joi.validate(data, schema)
    10. }, handler)

    In that case the function returned by schemaCompiler returns an object like:

    • error: filled with an instance of Error or a string that describes the validation error
    • value: the coerced value that passed the validation

    Schema Resolver

    The schemaResolver is a function that works together with the schemaCompiler: you can't use it with the default schema compiler. This feature is useful when you use complex schemas with $ref keyword in your routes and a custom validator.

    1. const fastify = require('fastify')()
    2. const Ajv = require('ajv')
    3. const ajv = new Ajv()
    5. ajv.addSchema({
    6.   $id: 'urn:schema:foo',
    7.   definitions: {
    8.     foo: { type: 'string' }
    9.   },
    10.   type: 'object',
    11.   properties: {
    12.     foo: { $ref: '#/definitions/foo' }
    13.   }
    14. })
    15. ajv.addSchema({
    16.   $id: 'urn:schema:response',
    17.   type: 'object',
    18.   required: ['foo'],
    19.   properties: {
    20.     foo: { $ref: 'urn:schema:foo#/definitions/foo' }
    21.   }
    22. })
    23. ajv.addSchema({
    24.   $id: 'urn:schema:request',
    25.   type: 'object',
    26.   required: ['foo'],
    27.   properties: {
    28.     foo: { $ref: 'urn:schema:foo#/definitions/foo' }
    29.   }
    30. })
    32. fastify.setSchemaCompiler(schema => ajv.compile(schema))
    33. fastify.setSchemaResolver((ref) => {
    34.   return ajv.getSchema(ref).schema
    35. })
    37. fastify.route({
    38.   method: 'POST',
    39.   url: '/',
    40.   schema: {
    41.     body: ajv.getSchema('urn:schema:request').schema,
    42.     response: {
    43.       '2xx': ajv.getSchema('urn:schema:response').schema
    44.     }
    45.   },
    46.   handler (req, reply) {
    47.     reply.send({ foo: 'bar' })
    48.   }
    49. })

    Usually you will send your data to the clients via 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 will increase your throughput by 100-400% depending on your payload and will 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',
    6.         value: { type: 'string' },
    7.         otherValue: { type: 'boolean' }
    8.       }
    9.     },
    10.     201: {
    11.       properties: {
    12.         value: { type: 'string' }
    13.       }
    14.     }
    15.   }
    16. }
    18. fastify.post('/the/url', { schema }, handler)

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

    When schema validation fails for a request, Fastify will automtically 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

    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. })

    You can also use 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 here

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

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

    Examples

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