asyncapi / asyncapi/parser-js

Adopt and/or adapt Spectral rules from AsyncAPI v2 Core ruleset to v3

Open
#1,016 11 comments 0 reactions 1 assignee Claimed by @AayushSaini101 View on GitHub
area/typescript enhancement
Dominant language
TypeScript
Stars
144
Forks
144
Avg merge
6m
Merged PRs (30d)
11

Description

### Context

Spectral rules are the rules that validate AsyncAPI documents. There are different types or levels:
- [Core ruleset](https://github.com/asyncapi/parser-js/blob/master/src/ruleset/ruleset.ts#L10). Basic but required validation. Apply to both v2 and v3 (with some exceptions).
- [Recommended ruleset](https://github.com/asyncapi/parser-js/blob/master/src/ruleset/ruleset.ts#L81). Just like good practices. Those won't create validation errors but warnings. Apply to only v2 documents. Not very clear if we want to add for v3 and forward.
- **Specific** rulesets per AsyncAPI Spec version. Contain particular rulesets that apply only to documents of a particular Spec version.:
- Core rulesets: Rules that are important and a doc of this Spec version must fulfil.
- Recommended rulesets: Best practices for this particular Spec version

In the case of **AsyncAPI Spec v3**, the rules that apply ATM are:

- [Core ruleset](https://github.com/asyncapi/parser-js/blob/master/src/ruleset/ruleset.ts#L10):
- `asyncapi-is-asyncapi` - The input must be a document with a supported version of AsyncAPI.
- `asyncapi-latest-version` - Checking if the AsyncAPI document is using the latest version.
- `asyncapi-document-resolved` - Checking if the AsyncAPI document has valid resolved structure.
- `asyncapi-document-unresolved` - Checking if the AsyncAPI document has valid unresolved structure.
- `asyncapi-internal` - That rule is internal to extend Spectral functionality for Parser purposes.
- [V3 specific ruleset](https://github.com/asyncapi/parser-js/blob/master/src/ruleset/v3/ruleset.ts):
- V3 Core rulesets:
- `asyncapi3-operation-messages-from-referred-channel` - Operation "messages" must be a subset of the messages defined in the channel referenced in this operation.
- `asyncapi3-required-operation-channel-unambiguity` - The "channel" field of an operation under the root "operations" object must always reference a channel under the root "channels" object.
- `asyncapi3-required-channel-servers-unambiguity` - The "servers" field of a channel under the root "channels" object must always reference a subset of the servers under the root "servers" object.

### Description

If you check how many specific v2 rules are, you will notice a lot compared to v3. This PR tries to fix that gap between Spec versions and adopt or adapt those rules from v2 that make sense in v3. We will be focusing on **Core rules** and skip **Recommended rules** by now (we will work on it in a next iteration).

#### Core Rules we might want to adopt/adapt from v2 to v3:

- [x] #1017
- [x] #1018
- [x] #1019
- [x] #1020
- [x] #1021
- [x] #1022
- [x] #1023
- [x] #1024
- Discussion about this happening at https://github.com/asyncapi/parser-js/pull/1007

#### Discarded rules:
- `asyncapi2-server-security` - Server have to reference a defined security schemes.
- No need since v3 Spec got a rewrite and removed the concept of Security Requirements. Now Security Schemes are specified directly into the `security` field.
- `asyncapi2-operation-security` - Operation have to reference a defined security schemes.
- Discarded because of the same reasons as `asyncapi2-server-security`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.