Unify all referencing mechanisms in v3

[fmvilas]

Spin off from this conversation: #663 (comment).

Summary

We use different referencing mechanisms in the spec:

• By name in components: SecurityRequirement Object
• By name in servers: Channel.servers property
• By using $ref: pretty much everywhere

This issue is to discuss if we should unify all of them and how.

[fmvilas]

I'm in favor of using $ref everywhere possible. More details in #663 (comment).

[GreenRover]

I agree. Having it unique would be a good idea.
$ref looks for me as the best solution as well.

Contra:

• $ref would allow illegal references

operations:
  sendUserSignedUp:
    action: send
    channel:
      $ref: '#/message/xyz' <--- should be /channel/ not /message/

But there for we have schema validator to point out mistakes like this.

Pro:

• It is unique we not need to be use to handle multiple ways to solve the same problem
• It is supported by most IDE. Your have jump marks and mouse over support
• Be more like brother project OpenAPI

[derberg]

let's do $ref but consistently everywhere

[jonaslagoni]

I agree let's use $ref everywhere. Side effect this way makes it easier for tooling as well.

$ref would allow illegal references

That would almost always be the case (when using references) but as this is always caught by validators and parsers, I am not sure we can even say it's a con 😄

[fmvilas]

/progress 60

PR is in place now: #852.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[jonaslagoni]

I cannot seem to find the changes in the parser, @fmvilas are you sure this change is complete?

I have the changes in for the spec #852 and JSON Schema files asyncapi/spec-json-schemas#316.

[fmvilas]

Yes, it's missing. I created an issue here: asyncapi/parser-js#746. Thanks for the pointer!