feat!: remove unsupported specs from NodeJS export (#248)

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

README.md

@@ -1,18 +1,23 @@
 ![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)
-> If you are currently using version 2, check out [migration guideline to version 3](./migrations/Migrate%20to%20version%203.md). You might be able to update it without any change.
+
 # AsyncAPI
+
 This is a mono repository, which provides all the JSON Schema documents for validating AsyncAPI documents.
+
 ## Overview
+
 * This repository contains [JSON Schema](https://json-schema.org) files for all the versions of 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.
 * In addition, this repo provides JavaScript and Go modules that make it easier to access JSON Schema files through code.
 
 ## 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:
+
 * Variables provided in the URL property have a corresponding variable object defined and its example is correct.
 * operationIds are not duplicated in the document.
 * messageIds are not duplicated in the document.
@@ -29,14 +34,19 @@ All test cases and parsers coverage can be found [here](https://asyncapi.github.
 ## Installation
 
 ### NodeJS
+
 ```bash
 npm install @asyncapi/specs
+// OR by Yarn
+yarn add @asyncapi/specs
 ```
 
 ### Go
+
 ```bash
 go get github.com/asyncapi/spec-json-schemas/v2
 ```
+
 ## Usage
 
 ### NodeJS
@@ -49,7 +59,7 @@ const asyncapi = require('@asyncapi/specs/schemas/2.0.0');
 // Do something with the schema.
 ```
 
-Get a list of versions:
+Get a list of supported versions:
 
 ```js
 const versions = require('@asyncapi/specs');
@@ -66,7 +76,12 @@ const asyncapi = versions['1.1.0'];
 
 // Do something with the schema.
 ```
+
+> **Note**
+> The main export of the package provides only supported versions of AsyncAPI (newer or equal to `2.0.0`). To use older ones (e.g. `1.2.0`) please import an absolute path like `@asyncapi/specs/schemas/1.2.0`;
+
 ### Go
+
 Grab a specific AsyncAPI version:
 
 ```go
@@ -81,32 +96,46 @@ func Do() {
     // Do something with the schema
 }
 ```
+
+## Migration guidelines
+
+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).
+
 ## Repository structure
-This is the current project structure explained.
+
+This is the current project structure explained:
+
 - [./definitions](./definitions) - contain all the individual schemas that will automatically be bundled together to provide the schemas in [./schemas](./schemas).
 - [./tools/bundler](./tools/bundler) - is the tool that bundles all the individual schemas together.
 - [./schemas](./schemas) - contain all automatically bundled and complete schemas for each AsyncAPI version. These schemas should **NOT** be manually changed as they are automatically generated. Any changes should be done in [./definitions](./definitions).
 
 ## Schema Bundling
+
 Changes should not be done manually to the schemas in [./schemas](./schemas), but instead be done in their individual definitions located in [./definitions](./definitions).
 
 These definitions are automatically bundled together on new releases through the npm script `prepublishOnly`, which ensures the project is build. This is where the [bundler](./tools/bundler) is called. 
 
 For example, for [2.2.0](./definitions/2.2.0), the [bundler](./tools/bundler/index.js) starts with the [asyncapi.json](definitions/2.2.0/asyncapi.json) file and recursively goes through all references (`$ref`) to create the [appropriate bundled version](./schemas/2.2.0.json).
 
 ### Creating a new version
+
 To create a new version, simply run the following command:
-```
+
+```bash
 npm run startNewVersion --new-version=x.x.x
 ```
+
 Where `x.x.x` is the new version you want to create.
 
 The manual process of creating a new version is to:
 1. Duplicate the latest version (`y.y.y`) under definitions (so we have the correct base to make changes from). 
 2. Rename the folder to the new version (`x.x.x`).
 3. Search and replace in the new duplicated folder for `y.y.y` and replace it with `x.x.x`.
 4. Edit the [index.js](./index.js) file adding a new line with the new version. I.e. `'2.5.0': require('./schemas/2.5.0.json'),`.
-5. Edit the [schemas/all.schema-store.json](./schemas/all.schema-store.json) file adding a new entry under the `oneOf` keyword with the new version. I.e.:
+5. Edit the [index.d.ts](./index.d.ts) file adding a new line with the types for the new version. I.e. `'2.5.0': JSONSchema7,`.
+6. Edit the [schemas/all.schema-store.json](./schemas/all.schema-store.json) file adding a new entry under the `oneOf` keyword with the new version. I.e.:
+
     ```json
     {
        "allOf":[
@@ -122,7 +151,4 @@ The manual process of creating a new version is to:
           }
        ]
     }
-    ```
-
-
-
+    ```

index.d.ts

@@ -0,0 +1,14 @@
+import type { JSONSchema7 } from 'json-schema';
+
+declare module '@asyncapi/specs' {
+  const specs: {
+    '2.0.0': JSONSchema7,
+    '2.1.0': JSONSchema7,
+    '2.2.0': JSONSchema7,
+    '2.3.0': JSONSchema7,
+    '2.4.0': JSONSchema7,
+    '2.5.0': JSONSchema7,
+  }
+
+  export default specs;
+}

index.js

@@ -1,9 +1,4 @@
 module.exports = {
-  '1.0.0': require('./schemas/1.0.0.json'),
-  '1.1.0': require('./schemas/1.1.0.json'),
-  '1.2.0': require('./schemas/1.2.0.json'),
-  '2.0.0-rc1': require('./schemas/2.0.0-rc1.json'),
-  '2.0.0-rc2': require('./schemas/2.0.0-rc2.json'),
   '2.0.0': require('./schemas/2.0.0.json'),
   '2.1.0': require('./schemas/2.1.0.json'),
   '2.2.0': require('./schemas/2.2.0.json'),

migrations/migrate-to-version-4.md

@@ -0,0 +1,3 @@
+# Migrating to version 4
+
+In version 4, we removed unsupported versions of AsyncAPI from the package: `1.0.0`, `1.1.0`, `1.2.0`, `2.0.0-rc1` and `2.0.0-rc2`. In addition, we added [Typescript](https://www.typescriptlang.org/) types to the existing specifications.