Description
Even though background lays the foundation for an AsyncAPI perspective, for the sake of clarity I am going to bring it to light here and try to map the proposals to the requirements and whether they solve the problems we are facing.
The alternative approach we are looking at is making a superset of the JSON Reference standard and restrictively defining the missing behaviors that work for our case (something along the lines of this PR).
The referencing standard is only part one of solving the referencing discrepancies as tooling is the second part that should be able to work with any JSON format which uses some form of referencing standard. See more in this discussion: https://github.com/orgs/asyncapi/discussions/485
The main use-case for us and the reason we want to change the referencing standard is to allow a message to define its payload with something different than JSON formats, which includes but is not limited to Protobuf and XSD formats.
The requirements we are looking at are the following (this primarily comes from questions raised when trying to build a referring tool and where the specs did not provide an answer):
- Should always produce a valid JSON document (resolving referenced resource should always be compatible with JSON)
- Should define the behavior for referencing non-JSON resources in a JSON document (this can be as simple as resolving the content into a string value)
- Should define the behavior for referencing JSON data
- Should define the behavior for referencing JSON data that also have reference behavior, and how they interconnect / or not (say two standards both use
$ref
the new standard should define a clear separation between the two and how referencing tools should interpret it) - Should define the behavior of nested schemas within the same file (so there is no difference between what the spec allows and what tooling enables)
If you have any questions/concerns feel free to raise them below! I am gonna block out some time to map the proposals to the requirements we have at some point, if you are bored, feel free to jump-start the process 😄!