Dereferencing rules

[char0n]

Hello everybody,

This issue is specifically about AsyncApi 2.0.0, but applies to v2.1.0 respectively. I'm working on a dereferencing tool a bumped to another issue regarding JSON Schema dereference. We've already stipulated in #552 that whenever the $ref field is intercepted in Schema Object, this Schema Object becomes a Reference Object and not a Schema Object with $ref keyword. This effectively means that dereference is purely guided using rules around Reference Object.

Never the less, the File Structure section contains following sentence:

The A2S representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.

The interesting part is the second (last) sentence. It's not very clear what this sentence actually tries to tell us.

There can be two possible interpretations (that I can see):

1. $ref fields follow rules around JSON Schema dereference

As stipulated in #552 this in not true.

2. $ref fields supports only referencing JSON Schemas

Again this in not true. $ref field can only be present (and have semantics) in Reference Object and Reference Object can reference other specification objects (Security Scheme, Parameter, Message, etc..).

IMHO this sentence mandates a major change in wording to clarify it's true meaning.

We can take inspiration from OpenApi 3.1:

An AsyncAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, Reference Objects are used.

[magicmatatjahu]

@char0n Hi! I think that this sentence points to logic how it works in the JSON Schema (...This is applicable for $ref fields...), I mean, referencing between files, but doesn't tell that it's only used for Schema Objects, but also for another part of spec - something like an example in correlation to another "tool", which is JSON Schema.

[magicmatatjahu]

@char0n Do you have any suggestions to improve the description of dereferencing rules?

[char0n]

Hi @magicmatatjahu,

Hi! I think that this sentence points to logic how it works in the JSON Schema (...This is applicable for $ref fields...)

How it works in JSON Schema is completely different how Reference Object works in AsyncApi spec. That's my whole point. This is why this sentence is confusing for the reader and opens door for different interpretations.

I mean, referencing between files

In AsyncApi, referencing is defined exclusively by Reference Object and not by JSON Schema rules. Even JSON Schema uses Reference Object to process references and transclution.

I've already provided my suggestion in my first comment:

I'd replace this sentence:

The A2S representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.

with the following one:

An AsyncAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, Reference Objects is used.

If agreed I can issue a PR.

[char0n]

I've issued a PR with the clarification: #602

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[char0n]

Attached PR has been merged, closing this.