docs: update readme with new release strategy (#458)

README.md

@@ -1,24 +1,39 @@
 ![npm](https://img.shields.io/npm/v/@asyncapi/specs?style=for-the-badge) ![npm](https://img.shields.io/npm/dt/@asyncapi/specs?style=for-the-badge)
 
-# AsyncAPI
+## Overview
 
 This is a mono repository, which provides all the JSON Schema documents for validating AsyncAPI documents.
 
-## Overview
+### Two types of schemas
+
+This repository contains [JSON Schema](https://json-schema.org) files for all the versions of AsyncAPI specification. There are two types of JSON Schema files, with and without **$id** feature. We need two versions of schemas because of the differences it tooling implementation of JSON Schema `$ref` and `$id` keywords. Some implementations treat `$id` by default as prefix reference for `$ref` and require it, therefore it is needed to properly correlate `$ref` and `$id` values. Unfortunately other tools do not understand `$id` values and fail dereferencing. This is why we need two different versions of schemas, with and without the `$id`.
+
+### Releases and pre-releases
+
+This repository contains JSON Schema files for official AsyncAPI releases and also for release candidates. Before you decide to use a specific JSON Schema file in production, make sure a corresponding [official release of AsyncAPI specification](https://github.com/asyncapi/spec/releases) is produced, not a release candidate.
+
+JSON Schema which describes a version of AsyncAPI specification that is not yet officially released is considered an unstable pre-release that can change anytime and is not considered to be a breaking-change.
+
+If you want to make sure you only use stable schemas, you have to make sure that you use only certain schema versions, not all by default.
+
+### JSON Schema vs AsyncAPI specification
+
+These JSON Schema files do not reflect 1:1 the specification and shouldn't be treated as specification itself but rather as a tool (e.g., for validation).
+
+These JSON Schema files shouldn't be used as the only tool for validating AsyncAPI documents because some rules described in the AsyncAPI specification can't be described with JSON Schema.
+
+### Libraries
 
-* This repository contains [JSON Schema](https://json-schema.org) files for all the versions of AsyncAPI specification. There are two types of JSON Schema files, with and without **$id** feature. We need two versions of schemas because of the differences it tooling implementation of JSON Schema `$ref` and `$id` keywords. Some implementations treat `$id` by default as prefix reference for `$ref` and require it, therefore it is needed to properly correlate `$ref` and `$id` values. Unfortunately other tools do not understand `$id` values and fail dereferencing. This is why we need two different versions of schemas, with and without the `$id`.
-* These JSON Schema files do not reflect 1:1 the specification and shouldn't be treated as specification itself but rather as a tool (e.g., for validation).
-* These JSON Schema files shouldn't be used as the only tool for validating AsyncAPI documents because some rules described in the AsyncAPI specification can't be described with JSON Schema.
-* In addition, this repo provides JavaScript and Go modules that make it easier to access JSON Schema files through code. These packages provide access only to schemas with version larger or equal 2.0.0.
+In addition, this repo provides JavaScript and Go modules that make it easier to access JSON Schema files through code. These packages provide access only to schemas with version larger or equal 2.0.0.
 
 ## Custom Validation Needs
 
 If you decide to validate AsyncAPI documents only with the JSON Schema files provided in this repo, your AsyncAPI documents will not be properly validated.
 It's recommended to use [AsyncAPI JavaScript Parser](https://github.com/asyncapi/parser-js) that uses the AsyncAPI JSON Schema files for validation but also implements additional custom validations.
 
-The following additional custom validations need to be provided:
+The following additional custom validations need to be provided for documents prior to `3.0.0`:
 
-* Variables provided in the URL property have a corresponding variable object defined and its example is correct.
+* Variables provided in the `url` property have a corresponding variable object defined and its example is correct.
 * `operationId`s are not duplicated in the document.
 * `messageId`s are not duplicated in the document.
 * Server security is declared properly and the name has a corresponding `securitySchemes` definition in `components` with the same name.

migrations/migrate-to-version-6.md

@@ -16,6 +16,6 @@ module.exports = {
 };
 ```
 
-However, while it's still a pre-release, the underlying schemas CAN contain breaking changes from version to version, up until the AsyncAPI specification is released. This means that one AsyncAPI document using v3 in the pre-release stage might be valid in `6.0.0`, but invalid in the `6.1.0`. This ONLY applies to pre-release schemas, and NOT regular ones that are set in stone.
+However, while it's still a pre-release, the underlying schemas CAN contain breaking changes from version to version, up until [the AsyncAPI specification is released](https://github.com/asyncapi/spec/releases). This means that one AsyncAPI document using v3 in the pre-release stage might be valid in `6.0.0`, but invalid in the `6.1.0`. This ONLY applies to pre-release schemas, and NOT regular ones that are set in stone.
 
 If you want to make sure you don't use a schema not released yet, you have to whitelist which versions you allow in your tool.