Adopt and/or adapt Spectral rules from AsyncAPI v2 Core ruleset to v3
- 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
Assessment
This issue has not been assessed yet.