Some Spectral Rules for spec v3 should run after resolving references
- Dominant language
- TypeScript
- Stars
- 144
- Forks
- 144
- Avg merge
- 6m
- Merged PRs (30d)
- 11
Description
#### Describe the bug
Both `asyncapi3-required-operation-channel-unambiguity` and `asyncapi3-required-channel-servers-unambiguity` rules (found [here](https://github.com/asyncapi/parser-js/blob/master/src/ruleset/v3/ruleset.ts#L28-L59)) apply at this moment to the unresolved document, meaning they run when the JSON References ($ref) are not yet resolved.
That was made in this way because it simplifies a lot the logic; we just need to match a pattern to the JSON pointer and voilà!.
However, that simplicity has a cost.
This validation works perfectly when any of the references found in `channel.servers` or `operation.channel` point to the same file.
However, if any point to an external file, the validation might not work as expected. See the next section where you will find an example that illustrate this.
#### How to Reproduce
```yaml
# a.yaml
asyncapi: 3.0.0
info:
title: FileA
version: 1.0.0
channels:
test:
$ref: './b.yaml#/channels/test'
```
```yaml
# b.yaml
asyncapi: 3.0.0
info:
title: FileB
version: 1.0.0
channels:
test:
servers:
- $ref: '#/components/servers/serverA' # Invalid document. Servers of a channel defined in the root channels object should point to root servers object as well.
components:
servers:
serverA:
host: localhost
protocol: http
```
`b.yaml` is an invalid document, as explained in the comment of the yaml file. And the parser shows that error when that document is validated.
However, `a.yaml`, which is referencing an **invalid** channel from `b.yaml` file, won't fail validation.
The reason is that the validation is made by matching that the JSON pointer references to the root object. I.e. for `operation.channel`, the pointer should contain the `#/channels/` literal.
#### Expected behavior
The `a.yaml` located in the previous example should be considered as invalid by the parser.
I think the only way to achieve this is to make the rules pass when the document is unresolved.
cc @fmvilas @jonaslagoni @derberg
Contributor guide
Research direction
Start with src/ruleset/v3/ruleset.ts around lines 28-59 and reproduce the issue using the a.yaml and b.yaml documents in the report. Trace when the two AsyncAPI 3 rules run relative to JSON Reference resolution, then verify that validating a.yaml reports the invalid channel reference just as validating b.yaml does.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100