[2.0.0 REVIEW] Type-safe references

[vearutop]

AsyncAPI Review Document

Project name	Reviewers	Company	Spec version
Not relevant	Viacheslav Poturaev	Not relevant	v2.0.0

Our goals with this project are to:

1. Not relevant

We expect to:

1. Reliably validate AsyncAPI schemas with general purpose JSON Schema validator

We found the following challenges or difficulties:

1. References can point to wrong places

For example message is allowed to be a reference or an object, reference can point to any place including wrong one like #/components/parameters/MyParam. Current JSON schema can not help to invalidate such case.

We think it can be solved by...

We can add a spec requirement that local references of component entities MUST point to appropriate component. On schema level such requirement can be enforced bypattern constraint of $ref value.

Overall, we think this challenge/difficulty is...

• [x] A "nice to have".
• [ ] A blocker for us to adopt this version of the spec.
• [ ] Something that doesn't affect the specification.

Other thoughts?

I've made similar proposal to OpenAPI spec where it can be considered a breaking change. Here in AsyncAPI such problem is less relevant as version 2.0.0 is still pending release.

I can submit a PR is that makes sense.

---

AsyncAPI Initiative — (website: asyncapi.org, twitter: @AsyncAPISpec)

[fmvilas]

I see what you mean. However, adding a pattern restriction to local references is fine for, well, local references but remote/file references are impossible to restrict, so that would be a partial solution.

I think validity should be checked using the structure, always. Basically, because you don't know where the definition can come from.

[vearutop]

It is true, the definitive solution would be to validate final structure that was resolved from reference(s), unfortunately there is no way to do it with means of JSON Schema (afaik).

So such validation can be only implemented in a custom tool explicitly aware of AsyncAPI realm, which does not scale.

Given that schemas with remote references are less popular than self-contained, I think it would be beneficial to have a partial solution at least for most common case.

[fmvilas]

unfortunately there is no way to do it with means of JSON Schema (afaik)

JSON Schema does exactly that. It validates that a given JSON object has the expected structure.

[vearutop]

I think you've missed an important detail:

structure that was resolved from reference(s)

JSON Schema is helpless to set any constraints on the destination of $ref like here:

    parameters:
      streetlightId:
          $ref: '#/components/parameters/streetlightId'

FYI here is a relevant proposal for JSON Schema: https://github.com/json-schema-org/json-schema-spec/issues/141.

[fmvilas]

Oh, you mean validating before dereferencing?

[vearutop]

I mean validating after dereferencing :) So that a dereferenced value of #/components/parameters/streetlightId:

      description: The ID of the streetlight.
      schema:
        type: string

is validated against parameter schema.

That would be a perfect solution for me, unfortunately JSON Schema does not (yet?) have a spec for that.

---

At the moment the only way to put some validation pressure on referenced value is an indirect validation through $ref string itself.

[fmvilas]

I see what you mean now. It's interesting indeed. I'm marking it as "under consideration" so I don't forget to review it when planning the next release (2.0.0 is already closed). Thanks!

[github-actions[bot]]

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

[github-actions[bot]]

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

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 :heart:

[github-actions[bot]]

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

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 :heart:

[github-actions[bot]]

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

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 :heart: