docs: add spectral ruleset docs (#790)

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

.gitignore

@@ -1,6 +1,7 @@
 node_modules
 .vscode
 .DS_Store
+/docs/api.md
 /coverage
 /lib
 /esm

README.md

@@ -227,6 +227,43 @@ Additionally to all the methods declared in the [Parser-API](https://github.com/
 - `jsonPath()` which returns the JSON Path of the given object.
 - `meta()` which returns the metadata of a given object, like a parsed AsyncAPI Document.
 
+## Spectral rulesets
+
+[Spectral](https://github.com/stoplightio/spectral) powers the validation of AsyncAPI documents within ParserJS. For this reason, it is possible to use your rulesets/rules or overwrite existing ones, passing the `ruleset` option to the Parser instance: 
+
+```ts
+import { Parser, stringify, unstringify } from '@asyncapi/parser';
+const parser = new Parser({
+  ruleset: {
+    extends: [],
+    rules: {
+      'asyncapi-defaultContentType': 'off',
+      'asyncapi-termsOfService': {
+        description: 'Info "termsOfService" should be present and non-empty string.',
+        recommended: true,
+        given: '$',
+        then: {
+          field: 'info.termsOfService',
+          function: 'truthy',
+        },
+      },
+    }
+  }
+});
+// The returned diagnostics object will include `asyncapi-termsOfService` diagnostic with `warning` (`recommended: true`) severity because `$.info.termsOfService` is not defined in the following AsyncAPI document.
+// On the other hand, since we turned it off, we won't see the diagnostics related to the `defaultContentType` field.
+const diagnostics = await parser.validate(`
+  asyncapi: '2.0.0'
+  info:
+    title: Example AsyncAPI specification
+    version: '0.1.0'
+  channels: {}
+`);
+```
+
+[ParserJS has some built-in Spectral rulesets](./docs/ruleset) that validate AsyncAPI documents and inform on good practices. 
+
+
 ## Using in the browser/SPA applications
 
 The package contains a built-in version of the parser. To use it, you need to import the parser into the HTML file as below:

docs/ruleset/README.md

@@ -0,0 +1,11 @@
+# AsyncAPI Spectral Ruleset
+
+ParserJS has some built-in Spectral rulesets that validate AsyncAPI documents and inform about good practices. Those are:
+
+- [Core Ruleset](./core-ruleset.md) - validates the overall structure of AsyncAPI documents (applied for each version, starting from `2.0.0`).
+- [Recommended Ruleset](./recommended-ruleset.md) - verifies good practices within AsyncAPI documents structure (applied for each version, starting from `2.0.0`).
+- [v2 Core Ruleset](./v2-core-ruleset.md) - validates the overall structure of AsyncAPI version `2.x.x` documents.
+- [v2 Recommended Ruleset](./v2-recommended-ruleset.md) - verifies good practices within AsyncAPI version `2.x.x` documents.
+
+> **Note**
+> The described rulesets are similar to the one found at https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md. They have been adapted under the rights of the Apache-2.0 license.

docs/ruleset/core-ruleset.md

@@ -0,0 +1,118 @@
+# AsyncAPI Core Ruleset
+
+The core ruleset validates the overall structure of AsyncAPI documents.
+
+> **Note**
+> These rules will apply to each version, starting from `2.0.0`.
+
+## Rules
+
+### asyncapi-is-asyncapi
+
+The input must be a document with a supported version of AsyncAPI.
+
+#### Good example
+
+```yaml
+asyncapi: 2.0.0
+...
+```
+
+#### Bad example
+
+```yaml
+openapi: 3.1.0
+...
+```
+
+```yaml
+asyncapi: 2.1.37
+...
+```
+
+### asyncapi-latest-version
+
+Checking if the AsyncAPI document is using the latest version.
+
+#### Good example
+
+Assuming the latest version is `2.6.0`:
+
+```yaml
+asyncapi: 2.6.0
+...
+```
+
+#### Bad example
+
+```yaml
+asyncapi: 2.5.0
+...
+```
+
+### asyncapi-document-resolved
+
+Checking if the AsyncAPI document has a valid resolved (with resolved references) structure based on the specification's JSON Schema.
+
+#### Good example
+
+```yaml
+asyncapi: 2.0.0
+info:
+  title: Valid AsyncAPI document
+  version: 1.0
+channels:
+  user/signup:
+    publish:
+      message:
+        $ref: '#/components/messages/user'
+components:
+  messages:
+    user: {...}
+```
+
+#### Bad example
+
+```yaml
+asyncapi: 2.0.0
+info:
+  title: Invalid AsyncAPI document
+  version: 1.0
+```
+
+### asyncapi-document-unresolved
+
+Checking if the AsyncAPI document has a valid unresolved (with unresolved references) structure based on the specification's JSON Schema.
+
+#### Good example
+
+```yaml
+asyncapi: 2.0.0
+info:
+  title: Valid AsyncAPI document
+  version: 1.0
+channels:
+  user/signup:
+    publish:
+      message:
+        $ref: '#/components/messages/user'
+components:
+  messages:
+    user: {...}
+```
+
+#### Bad example
+
+```yaml
+asyncapi: 2.0.0
+info:
+  title: Invalid AsyncAPI document
+  version: 1.0
+channels:
+  user/signup:
+    publish:
+      $ref: '#/components/x-operations/someOperation'
+components:
+  'x-operations':
+    someOperation: {}
+```