diff --git a/docs/Server.md b/docs/Server.md index b7e155074f..889dc1ca01 100644 --- a/docs/Server.md +++ b/docs/Server.md @@ -402,7 +402,7 @@ If `false`, the server routes the incoming request as usual. ### `ajv` -Configure the Ajv instance used by Fastify without providing a custom one. +Configure the Ajv v6 instance used by Fastify without providing a custom one. + Default: @@ -895,6 +895,9 @@ It can be useful when your schemas are stored in another data structure that is See [issue #2446](https://github.com/fastify/fastify/issues/2446) for an example of what this property helps to resolve. +Another use case is to tweak all the schemas processing. +Doing so it is possible to use Ajv v8, instead of the default v6! We will see an example of this later. + ```js const fastify = Fastify({ schemaController: { @@ -968,6 +971,37 @@ const fastify = Fastify({ }); ``` +##### Ajv 8 as default schema validator + +Ajv 8 is the evolution of Ajv 6, and it has a lot of improvements and new features. +To use the new Ajv 8 features such as JTD or the Standalone mode, refers to the [`@fastify/ajv-compiler` documentation](https://github.com/fastify/ajv-compiler#usage). + +To use Ajv 8 as default schema validator, you can use the following code: + +```js +const AjvCompiler = require('@fastify/ajv-compiler') // It must be the v2.x.x version + +// Note that the `format` schema's keyword is no longer supported on Ajv 8 by default. +// So you need to add it manually. +const ajvFormats = require('ajv-formats') + +const app = fastify({ + ajv: { + customOptions: { + validateFormats: true + }, + plugins: [ajvFormats] + }, + schemaController: { + compilersFactory: { + buildValidator: AjvCompiler() + } + } +}) + +// Done! You can now use Ajv 8 options and keywords into your schemas! +``` + #### setNotFoundHandler diff --git a/docs/Validation-and-Serialization.md b/docs/Validation-and-Serialization.md index 2960afc9bf..84867dbdda 100644 --- a/docs/Validation-and-Serialization.md +++ b/docs/Validation-and-Serialization.md @@ -14,7 +14,7 @@ Fastify uses a schema-based approach, and even if it is not mandatory we recomme ### Core concepts The validation and the serialization tasks are processed by two different, and customizable, actors: -- [Ajv](https://www.npmjs.com/package/ajv) for the validation of a request +- [Ajv v6](https://www.npmjs.com/package/ajv/v/6.12.6) for the validation of a request - [fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify) for the serialization of a response's body These two separate entities share only the JSON schemas added to Fastify's instance through `.addSchema(schema)`. @@ -120,7 +120,7 @@ fastify.register((instance, opts, done) => { ### Validation -The route validation internally relies upon [Ajv](https://www.npmjs.com/package/ajv), which is a high-performance JSON Schema validator. +The route validation internally relies upon [Ajv v6](https://www.npmjs.com/package/ajv/v/6.12.6) 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: @@ -131,6 +131,8 @@ The supported validations are: 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). +> ℹ If you need to use the lastest version of Ajv (v8) you should read how to do it in the [`schemaController`](Server.md#schema-controller) section. It is explained the easier way to avoid to implement a custom validator. + Example: ```js const bodyJsonSchema = { @@ -232,7 +234,7 @@ curl -X GET "http://localhost:3000/?ids=1 {"statusCode":400,"error":"Bad Request","message":"querystring/hello should be array"} ``` -Using `coerceTypes` as 'array' should fix it: +Using `coerceTypes` as 'array' will fix it: ```js const ajv = new Ajv({ @@ -258,7 +260,8 @@ For further information see [here](https://ajv.js.org/coercion.html) #### Ajv Plugins -You can provide a list of plugins you want to use with Ajv: +You can provide a list of plugins you want to use with the default `ajv` instance. +Note that the plugin must be **compatible with Ajv v6**. > Refer to [`ajv options`](Server.md#ajv) to check plugins format diff --git a/package.json b/package.json index dc7635990b..41c46533c1 100644 --- a/package.json +++ b/package.json @@ -115,7 +115,7 @@ }, "homepage": "https://www.fastify.io/", "devDependencies": { - "@fastify/ajv-compiler-8": "github:fastify/ajv-compiler#ajv-8", + "@fastify/ajv-compiler-8": "npm:@fastify/ajv-compiler@^2.0.0", "@fastify/pre-commit": "^2.0.1", "@hapi/joi": "^17.1.1", "@sinonjs/fake-timers": "^7.0.0",