Merge branch 'master' into feature/add_openapi_schema_for_v2_x

README.md

@@ -6,10 +6,10 @@ This is a mono repository, which provides all the JSON Schema documents for vali
 
 ## Overview
 
-* This repository contains [JSON Schema](https://json-schema.org) files for all the versions of AsyncAPI specification.
+* 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.
+* 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
 
@@ -19,16 +19,16 @@ It's recommended to use [AsyncAPI JavaScript Parser](https://github.com/asyncapi
 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.
+* `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.
 * Server `securitySchemes` is an empty array when the security type requires it.
 * Parameters specified in the channel name have corresponding parameters object defined.
 * Channel names do not contain URL parameters.
 * All servers listed for a channel in the `servers` property are declared in the top-level `servers` object.
 * Tags specified in any object have no duplicates. Check must be done for: the top-level object, operations (publish and subscribe), operation traits, channels, messages, and message traits.
 
-At the moment, AsyncAPI JavaScript parser do not cover all validation cases yet
+At the moment, the AsyncAPI JavaScript parser does not cover all validation cases yet.
 All test cases and parsers coverage can be found [here](https://asyncapi.github.io/tck/)
 
 ## Installation
@@ -54,27 +54,34 @@ go get github.com/asyncapi/spec-json-schemas/v2
 Grab a specific AsyncAPI version:
 
 ```js
-const asyncapi = require('@asyncapi/specs/schemas/2.0.0');
+const asyncapi = require('@asyncapi/specs');
 
+console.log(asyncapi.schemas['2.0.0'])
+console.log(asyncapi.schemasWithoutId['2.0.0'])
 // Do something with the schema.
 ```
 
 Get a list of supported versions:
 
 ```js
-const versions = require('@asyncapi/specs');
+const versions = require('@asyncapi/specs').schemas;
 
 console.log(versions);
-// Outputs:
+// Outputs object:
 //
 // {
-//   '1.0.0': [Object],
-//   '1.1.0': [Object]
+//   '2.0.0': [Object],
+//   '2.1.0': [Object],
+//   ...
 // }
-
-const asyncapi = versions['1.1.0'];
-
-// Do something with the schema.
+console.log(Object.keys(versions));
+// Outputs array:
+//
+// [
+//   '2.0.0',
+//   '2.1.0',
+//   ...
+// ]
 ```
 
 > **Note**
@@ -112,42 +119,55 @@ This is the current project structure explained:
 
 ## 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).
+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. 
+These definitions are automatically bundled together on new releases through the npm script `prepublishOnly`, which ensures the project is built. 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:
+## 1a Automated:
 
 ```bash
 npm run startNewVersion --new-version=x.x.x
 ```
 
 Where `x.x.x` is the new version you want to create.
 
+## 1a Manual
+
 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 [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.:
+1. Rename the folder to the new version (`x.x.x`).
+1. Search and replace in the new duplicated folder for `y.y.y` and replace it with `x.x.x`.
+
+## 2 Further steps
+
+1. Edit the [index.js](./index.js) file adding a new line with the new version. I.e.:
+   ```js
+   '2.6.0': require('./schemas/2.6.0.json'),
+   '2.6.0-without-$id': require('./schemas/2.6.0-without-$id.json'),
+   ```
+1. Edit the [index.d.ts](./index.d.ts) file adding a new line with the types for the new version. I.e.:
+   ```js
+   '2.6.0': JSONSchema7;
+   '2.6.0-without-$id': JSONSchema7;
+   ```
+1. 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. Remember about adding `-without-$id` suffix which points to alternative generated schema without $ids. I.e.:
 
     ```json
     {
        "allOf":[
           {
              "properties":{
                 "asyncapi":{
-                   "const":"2.5.0"
+                   "const":"2.6.0"
                 }
              }
           },
           {
-             "$ref":"http://asyncapi.com/schema-store/2.5.0.json"
+             "$ref":"http://asyncapi.com/schema-store/2.6.0-without-$id.json"
           }
        ]
     }
@@ -156,4 +176,4 @@ The manual process of creating a new version is to:
 ### Handling breaking changes
 Whenever a Breaking Change is introduced, the following steps should be taken in Go package:
 
-1. Edit `go.mod` file, and increase the version package suffix in the module name. For example, if the current version is `v2.0.0`, and you are releasing `v3.0.0`, the module name should be `github.com/asyncapi/spec-json-schemas/v3`.
+1. Edit `go.mod` file, and increase the version package suffix in the module name. For example, if the current version is `v2.0.0`, and you are releasing `v3.0.0`, the module name should be `github.com/asyncapi/spec-json-schemas/v3`.