[📑 Docs]: Write down all the custom validation rules that are not in JSON Schema

[derberg]

What Dev Docs changes are you proposing?

There is a need to write down what is not in JSON Schema and we wrote custom validation code for it here https://github.com/asyncapi/parser-js/blob/master/lib/customValidators.js so it is transparent and clear what happens if someone decides to validate AsyncAPI document by using directly the AsyncAPI JSON Schema document.

Even our Parser JS is not yet 100% accurate with validation, so https://asyncapi.github.io/tck/asyncapi-parser_js_detailed_report.html should also be treated as source of truth

Code of Conduct

• I agree to follow this project's Code of Conduct

[derberg]

The goal of this task should be to update the README.md

• add Overview section and explain:
  • that this repository contains JSON Schema files for all the versions of AsyncAPI specification. You can link to https://json-schema.org/ for reference
  • that JSON Schema files are not 1:1 reflecting the specification and should not be treated as specification itself but rather as a tool for things like validation for example
  • that these JSON Schema files should not be used as the only tool for validation of AsyncAPI documents, that some rules described in the AsyncAPI specification cannot be described with JSON Schema
• add Custom Validation Needs (not sure if this is the best name for the section) section and explain:
  • JSON Schema does not cover all validation cases, and if users decide to validate AsyncAPI tools with only JSON Schema provided in this repo, they risk that their AsyncAPI documents may not work will all AsyncAPI tools and not pass validation there.
  • point out that there is a need for custom validation implementation, what we already do in https://github.com/asyncapi/parser-js and we recommend using it as a validation tool
  • we need to list what additional custom validations need to be provided:
    • Validate if variables provided in the url property have corresponding variable object defined and if the example is correct
    • Validate if operationIds are duplicated in the document
    • Validate if messageIds are duplicated in the document
    • Validate if server security is declared properly and the name has a corresponding server securitySchemes definition in components with the same name
    • Validate if given server securitySchemes is a proper empty array when security type requires it
    • Validate if parameters specified in the channel name have corresponding parameters object defined and if name does not contain url parameters.
    • Validate that all servers listed for a channel in servers property are declared in the top-level servers object.
    • Validate if tags specified in the objects have no duplicates. Check is done for: root, operations, operation traits, channels, messages and message traits.
  • point out that even parser-js do not cover all validation cases yet, and that all test cases and parsers coverage can be found here -> https://asyncapi.github.io/tck/

All names of objects/properties can be double-checked with https://www.asyncapi.com/docs/reference/specification/v2.4.0

[derberg]

solved in #243 thanks to @Dindihub