fix: update references for avro and openapi schema (#395)

README.md

@@ -125,24 +125,24 @@ These definitions are automatically bundled together on new releases through the
 
 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
+## Creating a new version
 
-## 1a Automated:
+### 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
+### 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). 
 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
+### 2 Further steps
 
 1. Edit the [index.js](./index.js) file adding a new line with the new version. I.e.:
    ```js
@@ -173,7 +173,24 @@ The manual process of creating a new version is to:
     }
     ```
 
-### Handling breaking changes
+## 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`.
+
+## 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.
+
+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.
+
+- Make sure you have VSCode and YAML extension
+- Once you make changes in schemas, bundle them with `npm run bundle`
+- Edit [this sample AsyncAPI document](./test/fixtures/asyncapi.yml). Add a new field, hover over some property to see if tooltip still shows up. This sample document contains the following line that assures YAML uses your local schema and not the one from SchemaStore. Make sure it points to the schema bundle that you generated and that contains your changes:
+   ```yaml
+   # yaml-language-server: $schema=YOUR-PROJECTS-DIRECTORY/spec-json-schemas/schemas/2.6.0-without-$id.json
+   ```
+
+
+
+

test/fixtures/asyncapi.yml

@@ -0,0 +1,42 @@
+# yaml-language-server: $schema=YOUR-PROJECTS-DIRECTORY/spec-json-schemas/schemas/2.6.0-without-$id.json
+asyncapi: 2.6.0
+
+info:
+
+  title: test.mosquitto.org
+  version: This service is in charge of processing all the events related to comments.
+
+servers:
+  dev:
+    url: test.mosquitto.org
+    protocol: mqtt
+
+channels:
+  comment/liked:
+
+    description: Updates the likes count in the database when new like is noticed.
+    publish:
+      operationId: commentLiked
+      message:
+        description: Message that is being sent when a comment has been liked by someone.
+        payload:
+          $ref: '#/components/schemas/commentId'
+
+  comment/unliked:
+    description: Updates the likes count in the database when comment is unliked.
+    publish: 
+      operationId: commentUnliked
+      message:
+        description: Message that is being sent when a comment has been unliked by someone.
+        messageId: ddd
+        payload:
+          $ref: '#/components/schemas/commentId'
+
+components:
+  schemas:
+    commentId:
+      type: object
+      additionalProperties: false
+      properties:
+        commentId: 
+          type: string

tools/bundler/index.js

@@ -55,7 +55,6 @@ console.log(`Using the following output directory: ${outputDirectory}`);
   console.log('done');
 })();
 
-
 /**
  * we first update definitions from URL to normal names
  * than update refs to point to new definitions, always inline never remote
@@ -72,6 +71,9 @@ function modifyRefsAndDefinitions(bundledSchema) {
   }
 
   traverse(bundledSchema, replaceRef);
+  traverse(bundledSchema.definitions.avroSchema_v1, updateAvro);
+  traverse(bundledSchema.definitions.openapiSchema_3_0, updateOpenApi);
+  traverse(bundledSchema.definitions['json-schema-draft-07-schema'], updateJsonSchema);
 
   return bundledSchema
 }
@@ -99,14 +101,57 @@ function replaceRef(schema) {
   //traversing shoudl take place only in case of schemas with refs
   if (schema.$ref === undefined ) return;
 
-  // '#/definitions' refs are always those related to JSON Schema draft, so we just need to update them to point to json schema draft that is inlined inside schema
-  if (schema.$ref.startsWith('#/definitions')) {
-    schema.$ref = schema.$ref.replace('#/definitions/', `#/definitions/${JSON_SCHEMA_PROP_NAME}/definitions/`);
-  // '#' refs need to be updated to point to the root of inlined json schema draft
-  } else if (schema.$ref === '#') {
-    schema.$ref = `#/definitions/${JSON_SCHEMA_PROP_NAME}`;
-  // the rest of refs are those related to remote URL refst that need to be update and point to inlined versions
-  } else {
-    schema.$ref = `#/definitions/${getDefinitionName(schema.$ref)}`;
+  // updating refs that are related to remote URL refs that need to be update and point to inlined versions
+  if (!schema.$ref.startsWith('#')) schema.$ref = `#/definitions/${getDefinitionName(schema.$ref)}`;
+}
+
+/**
+ * this is a callback used when traversing through json schema
+ * to fix avro schema definitions to point to right direction
+ */
+function updateAvro(schema){
+  //traversing shoudl take place only in case of schemas with refs
+  if (schema.$ref === undefined) return;
+
+  schema.$ref = schema.$ref.replace(
+    '#/definitions/',
+    '#/definitions/avroSchema_v1/definitions/'
+  );
+}
+
+/**
+ * this is a callback used when traversing through json schema
+ * to fix open api schema definitions to point to right direction
+ */
+function updateOpenApi(schema){
+  //traversing shoudl take place only in case of schemas with refs
+  if (schema.$ref === undefined) return;
+  const openApiPropName = 'openapiSchema_3_0';
+
+  schema.$ref = schema.$ref.replace(
+    '#/definitions/',
+    `#/definitions/${openApiPropName}/definitions/`
+  );
+
+  if (schema.$ref === '#') {
+    schema.$ref = `#/definitions/${openApiPropName}`;
   }
 }
+
+/**
+ * this is a callback used when traversing through json schema
+ * to fix open api schema definitions to point to right direction
+ */
+function updateJsonSchema(schema){
+  //traversing shoudl take place only in case of schemas with refs
+  if (schema.$ref === undefined) return;
+
+  schema.$ref = schema.$ref.replace(
+    '#/definitions/',
+    `#/definitions/${JSON_SCHEMA_PROP_NAME}/definitions/`
+  );
+
+  if (schema.$ref === '#') {
+    schema.$ref = `#/definitions/${JSON_SCHEMA_PROP_NAME}`;
+  }
+}