asyncapi / asyncapi/parser-js

Some Spectral Rules for spec v3 should run after resolving references

Open
#924 1 comment 0 reactions 0 assignees View on GitHub
bug keep-open
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.