Add documentation for upgrading from v2 to v3 (#107)

* Add 'Upgrading from v2 to v3' section to the README

* Rewrite 'Why validate with JSON schemas?' of the README

Author: simonplend

README.md

@@ -1,7 +1,7 @@
 # Express JSON Validator Middleware
 
 > [Express](https://github.com/expressjs/express/) middleware for validating
-requests against JSON schemas.
+requests against JSON schemas with Ajv.
 
 [![npm version](https://img.shields.io/npm/v/express-json-validator-middleware.svg)](https://www.npmjs.com/package/express-json-validator-middleware)
 [![npm monthly downloads](https://img.shields.io/npm/dm/express-json-validator-middleware.svg)](https://www.npmjs.com/package/express-json-validator-middleware)
@@ -11,12 +11,11 @@ requests against JSON schemas.
 
 ## Why validate with JSON schemas?
 
-- **Simple** - JSON schemas are a simple and expressive way to describe a data structure.
-- **Standard** - JSON schemas are not specific to JavaScript. In fact, they are used just about everywhere.
-- **Fail-Fast** - Catch errors early in your logic, evading confusing errors later.
-- **Separate Validation** - Keep your routes clean. Validation logic doesn't need to be defined in your route handlers.
-- **Error Messaging** - Ajv provides you with rich error objects that can easily be transformed into human-readable format.
-- **Documentation** - Creating a JSON Schema is another way of documenting your application.
+- **Expressive** — JSON schemas are an expressive way to describe data structures.
+- **Standard** — JSON schemas are portable. There are validator implementations in many languages.
+- **Separate validation** — Avoid the need to handle request validation in your route handlers.
+- **Error messaging** — Ajv provides rich and descriptive error objects.
+- **Documentation** — Schemas can help document your application.
 
 ## Requirements
 
@@ -28,6 +27,8 @@ requests against JSON schemas.
 npm install express-json-validator-middleware
 ```
 
+If you're upgrading from v2 to v3, make sure you read the [migration notes](#upgrading-from-v2-to-v3).
+
 ## Getting started
 
 ```javascript
@@ -277,21 +278,31 @@ validator.ajv;
 Ajv must be configured *before* you call `Validator.validate()` to add middleware
 (e.g. if you need to define [custom keywords](https://ajv.js.org/custom.html).
 
-## Ajv versions
+## Upgrading from v2 to v3
+
+v2.x releases of this library use [Ajv v6](https://www.npmjs.com/package/ajv/v/6.6.2).
+v3.x of this library uses [Ajv v8](https://www.npmjs.com/package/ajv/v/8.11.0).
+
+Notable changes between Ajv v6 and v8:
 
-The major version `1.x` of this module uses `ajv@5`, read their changelog and
-migration guide [here](https://github.com/ajv-validator/ajv/releases/tag/5.0.0).
+- All formats have been moved to [ajv-formats](https://www.npmjs.com/package/ajv-formats).
+If you're using formats in your schemas, you must install this package to continue
+using them.
+- The structure of validation errors has changed.
+- Support has been dropped for JSON Schema draft-04.
 
-Major version `2.x` uses `ajv@6` in order to support draft-07 of JSON Schema.
-You have to manually configure Ajv to support **draft-06** schemas
-(see https://github.com/ajv-validator/ajv/tree/v6#using-version-6).
+For full details, read the Ajv migration guide: [Changes from Ajv v6.12.6 to v8.0.0](https://ajv.js.org/v6-to-v8-migration.html).
+
+If you have any Ajv plugins as dependencies, update them to their newest versions.
+Older versions of Ajv plugins are less likely to be compatible with Ajv v8.
 
 ## Tests
 
 Tests are written using [node-tap](https://www.npmjs.com/package/tap).
 
 ```
 npm install
+
 npm test
 ```