Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Support JSON Schema for bindings #507

Closed
magicmatatjahu opened this issue Mar 10, 2021 · 21 comments
Closed

[RFC] Support JSON Schema for bindings #507

magicmatatjahu opened this issue Mar 10, 2021 · 21 comments
Assignees
Labels
💭 Strawman (RFC 0) RFC Stage 0 (See CONTRIBUTING.md)

Comments

@magicmatatjahu
Copy link
Member

magicmatatjahu commented Mar 10, 2021

Is your feature request related to a problem? Please describe.

Making review for this PR asyncapi/asyncapi-react#259 I realized that we don't have JSON Schema definitions for officially supported bindings by AsyncAPI. Currently we have only markdown documents like for http -> https://github.com/asyncapi/bindings/tree/master/http

Without JSON Schema for bindings we cannot:

  • validate bindings object in parser-js,
  • using binding's model in templates for parsed schemas by parser-js,
  • render correctly bindings in templates and React component - we still can, but the JSON Schema would make it easier.

how to validate bindings in parser is a different problem, but I'd like to mention it here.

Can't it be tackled using specification extensions? and Describe the solution you'd like

We can use extensions to define JSON Schema for each officially supported bindings (link).

I very like this approach (treating bindings as extensions), because then versioning of bindings is not related to AsyncAPI versioning at all - bindings can be versioned next to the official AsyncAPI release without any problems.

Problems which I see with this solution:

  • where we should store JSON Schemas? Probably the bindings repository is the best place.
  • what with bindingsObject object? Make references to external JSON Schemas in bindings repo or maybe remove whole object and then user should define extension of appropriate binding in spec? TBH I don't know. In my PoV I would like to choose second variant, because I think that AsyncAPI JSON Schema should be as small as possible without reference to external sources, but it could degrade DX. Feel free to share your thoughts about that!

Describe alternatives you've considered

If we cannot use extension to define JSON Schema for official supported bindings, then only solution as I see, is describing definition here, but I very don't like this.

@github-actions
Copy link

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.

Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

@fmvilas fmvilas changed the title [FEATURE REQUEST] Support JSON Schema for bidnings [RFC] Support JSON Schema for bindings Mar 16, 2021
@fmvilas fmvilas added 💭 Strawman (RFC 0) RFC Stage 0 (See CONTRIBUTING.md) and removed feature request labels Mar 16, 2021
@derberg
Copy link
Member

derberg commented Apr 13, 2021

At the moment bindings have versioning independent from spec version, and it is good imho.
we should store schemas in bindings repo so it is easier to binding maintainers to maintain them, and just ref those in here but dereference as part of publishing process because we do not want to do it during parsing.

@magicmatatjahu
Copy link
Member Author

magicmatatjahu commented Apr 13, 2021

...and just ref those in here but dereference as part of publishing process because we do not want to do it during parsing.

I agree with that! We can use for that standalone compilation to generate validation function for our schema to improve performance. At the moment we "compile" (including dereferencing) schema in each execution of the parse function (line). I don't know how we can speed parsing, but I think that it should be faster :)

@jonaslagoni
Copy link
Member

We can use for that standalone compilation to generate validation function for our schema to improve performance. At the moment we "compile" (including dereferencing) schema in each execution of the parse function (line). I don't know how we can speed parsing, but I think that it should be faster :)

@magicmatatjahu are you talking about splitting the task of validating bindings into separate standalone components and only validate those bindings in use? Instead of everything at once? 🤔

@magicmatatjahu
Copy link
Member Author

magicmatatjahu commented Apr 13, 2021

@jonaslagoni No. Ajv supports compilation of the JSON Schema to "standalone" function which can be saved to file and then reused in JS application. In reference to @derberg comments:

we should store schemas in bindings repo so it is easier to binding maintainers to maintain them, and just ref those in here but dereference as part of publishing process because we do not want to do it during parsing.

So by this standalone function we can dereference refs for binding's JSON Schemas, compiled it and save to file and use this function in parser. By this operation we can move @asyncapi/specs package to devDependencies -- currently specs are bundled in parser and we can reduce size.

EDIT: Of course this logic doesn't handle the problem with JSON Schemas for extensions (also for custom bindings), but it is a good way to handle supported bindings and speed up the parser.

@derberg
Copy link
Member

derberg commented Apr 14, 2021

I would not worry much about custom bindings, we accept any bindings in the spec, look at IBM or Anypoint (in progress). Json schema for extensions will be solved by extension registry.

My feeling is this is not related to spec at all as json schema is a tool, not the spec. Next step would be to first create those JSON Schemas for bindings, right? the only open problem for me is location. Bindings repo seems best as it will be better to maintain it, but on the other hand, in the asyncapi json schema we should not reference files from master but rather a tag. Now question is, I'm not decided, is it ok to always push new tag on bindings repo even if there will be a change just in one binding (bindings are versioned separately). For me this is just a technical tag, not related to specification, so sounds good to me, but correct me if I'm wrong

@KhudaDad414
Copy link
Member

I want to help implement this feature, As I understand we need to:

  1. Create JSON Schema for each binding and store them in binding repo.
    • How are we going to approach this? just look at the specifications and create a JSON Schema for it?
  2. Reference those Schemas here.
    • Where exactly?
  3. generate standalone functions to validate the bindings against JSON Schemas(that we created at the first stage) and use them in parser.
    • Where, at what repo and when?

Sorry, these questions might have obvious answers that I don't see.

@derberg
Copy link
Member

derberg commented Apr 16, 2021

How are we going to approach this? just look at the specifications and create a JSON Schema for it?

yeap 😄 but don't worry, some do not have bindings defined yet.
my only concern is that there are different bindings per different AsyncAPI object, like operation and message for example. So there will be maximum of 4 schemas per protocol. So 🤔 we either have 4 files, with proper pattern in file name, or one custom yaml with 4 schemas in it.

Where exactly?
Here https://github.com/asyncapi/asyncapi-node/blob/master/schemas/2.0.0.json. For example now we have kafka: {} and should have kafka: '$ref: xxx'
.But not now, this is next step. We do not want to have url refs, at least I think.

Where, at what repo and when?

This one is a next step after the previous one, like a final step on how to at the end enable parser to consume these schemas.


Let's just solve it step by step I think and first figure out how and then create files with JSON schemas

@github-actions
Copy link

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 ❤️

@derberg
Copy link
Member

derberg commented Jun 16, 2021

Bindings schemas are already merged with asyncapi/bindings#60
Now we need to figure out how to handle it in the parser and the asyncapi json schema asyncapi/parser-js#315

@github-actions
Copy link

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 ❤️

@github-actions github-actions bot added the stale label Aug 16, 2021
@derberg derberg removed the stale label Aug 16, 2021
@github-actions
Copy link

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 ❤️

@github-actions github-actions bot added the stale label Dec 15, 2021
@derberg derberg removed the stale label Dec 15, 2021
@jonaslagoni
Copy link
Member

I think it makes sense to move this to https://github.com/asyncapi/spec-json-schemas, right?

@github-actions
Copy link

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 ❤️

@magicmatatjahu
Copy link
Member Author

@derberg Could you unstale that issue. We have discussed solution for it :)

@derberg derberg removed the stale label May 30, 2022
@github-actions
Copy link

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 ❤️

@github-actions github-actions bot added the stale label Sep 28, 2022
@derberg derberg removed the stale label Sep 29, 2022
@derberg
Copy link
Member

derberg commented Sep 29, 2022

@magicmatatjahu I suggest we close it

  • schemas were created long time ago already by Khuda
  • Jonas is not integrating them in the spec-json-schema

or we move it to spec-json-schema and close once PR from Jonas is merged

@jonaslagoni
Copy link
Member

Agree this can be closed :)

@github-actions
Copy link

github-actions bot commented Sep 1, 2023

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 ❤️

@github-actions github-actions bot added the stale label Sep 1, 2023
@jonaslagoni
Copy link
Member

@derberg can you close this one as complete 🙂

@github-actions github-actions bot removed the stale label Oct 27, 2023
@derberg
Copy link
Member

derberg commented Oct 31, 2023

closing as merge of asyncapi/spec-json-schemas#208 will solve it definitely

@derberg derberg closed this as completed Oct 31, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
💭 Strawman (RFC 0) RFC Stage 0 (See CONTRIBUTING.md)
Projects
None yet
Development

No branches or pull requests

5 participants