[JSON Schema Store] IDEs cannot determine the version of the JSON Schema to use

[smoya]

Describe the bug

IDEs, like VSCode, cannot determine the version of the JSON Schema file to use based on the AsyncAPI version in use.

How to Reproduce

• Copy any example from https://github.com/asyncapi/spec/tree/master/examples
• Change the version from 2.4.0 to 2.3.0.
• You will still notice the IDE is using AsyncAPI (2.4.0.json) (as in the screenshot above).

Expected behavior

IDEs should pick up the proper JSON Schema file based on the version selected on the AsyncAPI file.

The solution can be found in SchemaStore/schemastore#2229 (comment)

[smoya]

I found a small rock on the path.

In order to support several versions, we need to provide a file like this one.
The point is that the $id of our JSON Schema documents look like http://asyncapi.com/definitions/1.0.0/asyncapi.json -- note the /definitions path part.
However, if we want to measure the downloads from Schema-Store linked documents, we should set $ref to point to /schema-store paths since Schema Store plugins will download making a GET from the $id (as it is an URL).

{
  "$id": "http://asyncapi.com/schema-store/all.json",
  "$schema": "http://json-schema.org/draft-07/schema",
  "title": "JSON Schema documents for all AsyncAPI spec versions",
  "description": "All AsyncAPI JSON Schema documents listed in one file. Needed for serving all documents through schemastore.org",
  "type": "object",
  "oneOf": [
    {
      "allOf": [
        {
          "properties": {
            "asyncapi": {
              "const": "1.0.0"
            }
          }
        },
        {
          "$ref": "http://asyncapi.com/schema-store/1.0.0.json"
        }
      ]
    },

The real problem behind that is that the $id of the document served at http://asyncapi.com/schema-store/1.0.0.json is http://asyncapi.com/definitions/1.0.0.json, so it's kind of inconsistent on those cases where the schema has been loaded already from http://asyncapi.com/schema-store/1.0.0.json (on a local schema registry), forcing the tool to download it again.

It is not a big issue as Schema-Store plugin is being used for development, but still a bit inconsistent.

Posible solutions

1. Just deal with it. To have one all.schema-store.json file with all $ref pointing to the http://asyncapi.com/schema-store/<doc>.json

2. To provide two files, one all.schema-store.json and a all.json, with all $ref pointing to the http://asyncapi.com/schema-store/<doc>.json and http://asyncapi.com/definitions/<doc>.json respectively.

Even though I'm not sure if any user will use the all.json tbh. The only use case I can think of is for our parsers.

Any preference or alternative @derberg @fmvilas ?

I'm going to move on with just the first option as we can always move with the second.

[smoya]

This is not fixed yet. SchemaStore/schemastore#2342 will be the last PR required. @derberg could you reopen it?

Nevermind, this is now considered as fixed since the PR on Schema Store has been merged.

We can confirm it works because since the PR got merged, schemas for other AsyncAPI versions started to be downloaded:

cc @derberg