fix: prepare next-major-spec for release (#421)

Co-authored-by: Sergio Moya <[email protected]>

README.md

@@ -108,6 +108,8 @@ func Do() {
 
 If you are currently using version 2, check out [migration guideline to version 3](./migrations/migrate-to-version-3.md).
 If you are currently using version 3, check out [migration guideline to version 4](./migrations/migrate-to-version-4.md).
+If you are currently using version 4, check out [migration guideline to version 5](./migrations/migrate-to-version-5.md).
+If you are currently using version 5, check out [migration guideline to version 6](./migrations/migrate-to-version-6.md).
 
 ## Repository structure
 
@@ -183,7 +185,7 @@ Whenever a Breaking Change is introduced, the following steps should be taken in
 
 ## SchemaStore compatibility testing
 
-AsyncAPI JSON Schema is referenced in [SchemaStore](https://www.schemastore.org/json/). In many IDEs, like VSCode, some extensions integrate with SchemaStore, like [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). This way we enable autocompletion, validation and tooltips that helps writing AsyncAPI documents.
+AsyncAPI JSON Schema is referenced in [SchemaStore](https://www.schemastore.org/json/). In many IDEs, like VSCode, some extensions integrate with SchemaStore, like [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). This way we enable autocompletion, validation and tooltips that help write AsyncAPI documents.
 
 Whenever you make changes in AsyncAPI JSON Schema, you should always manually verify that the schema is still supported by [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) and that it will be able to fetch and dereference it.
 

migrations/migrate-to-version-5.md

@@ -0,0 +1,28 @@
+# Migrating to version 5
+
+In version 5, we now export two different types of schemas, one using `$id` feature in JSON Schema, and one without.
+
+In v4, the library would export the schemas as:
+```js
+module.exports = {
+  '2.0.0': require('./schemas/2.0.0.json'),
+  ...
+};
+```
+
+In v5, you need to access the schemas through `.schemas` instead.
+
+```js
+module.exports = {
+    'schemas': {
+        '2.0.0': require('./schemas/2.0.0.json'),
+        ...
+    },
+    'schemasWithoutId': {
+        '2.0.0': require('./schemas/2.0.0-without-$id.json'),
+        ...
+    }
+};
+```
+
+And if you want the schemas without `$id`, use `schemasWithoutId`.

migrations/migrate-to-version-6.md

@@ -0,0 +1,21 @@
+# Migrating to version 6
+
+In version 6 and onwards, all pre-release AsyncAPI specification versions will be released as a regular feature request, before the AsyncAPI specification itself is released.
+
+The pre-release version will be released as if it was not a pre-release, for example for AsyncAPI 3.0, it will be released as normal:
+```js
+module.exports = {
+    'schemas': {
+        ...
+        '3.0.0': require('./schemas/3.0.0.json'),
+    },
+    'schemasWithoutId': {
+        ...
+        '3.0.0': require('./schemas/3.0.0-without-$id.json'),
+    }
+};
+```
+
+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.
+
+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.

schemas/all.schema-store.json

@@ -172,6 +172,20 @@
           "$ref": "http://asyncapi.com/schema-store/2.6.0-without-$id.json"
         }
       ]
+    },
+    {
+      "allOf": [
+        {
+          "properties": {
+            "asyncapi": {
+              "const": "3.0.0"
+            }
+          }
+        },
+        {
+          "$ref": "http://asyncapi.com/schema-store/3.0.0-without-$id.json"
+        }
+      ]
     }
   ]
 }