[RFC] Support JSON Schema for bindings

Question

[RFC] Support JSON Schema for bindings

magicmatatjahu opened this issue 4 years ago · 21 comments

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.

Answer 1 · 2021-03-10T12:13:57.000Z

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.

Answer 2 · 2021-04-13T11:06:06.000Z

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.

Answer 3 · 2021-04-13T11:26:09.000Z

...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 :)

Answer 4 · 2021-04-13T13:21:52.000Z

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? 🤔

Answer 5 · 2021-04-13T13:31:19.000Z

@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.

Answer 6 · 2021-04-14T07:55:39.000Z

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

Answer 7 · 2021-04-15T06:45:14.000Z

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

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?
Reference those Schemas here.
- Where exactly?
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.

Answer 8 · 2021-04-16T08:53:31.000Z

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

Answer 9 · 2021-06-16T00:51:56.000Z

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

Answer 10 · 2021-06-16T11:23:34.000Z

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

Answer 11 · 2021-08-16T00:52:07.000Z

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

Answer 12 · 2021-12-15T00:57:25.000Z

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

Answer 13 · 2022-01-19T15:16:40.000Z

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

Answer 14 · 2022-05-27T00:17:55.000Z

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

Answer 15 · 2022-05-30T09:03:31.000Z

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

Answer 16 · 2022-09-28T00:29:18.000Z

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

Answer 17 · 2022-09-29T13:57:49.000Z

@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

Answer 18 · 2023-03-09T13:27:58.000Z

Agree this can be closed :)

Answer 19 · 2023-09-01T00:16:42.000Z

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

Answer 20 · 2023-10-26T10:32:40.000Z

@derberg can you close this one as complete 🙂

Answer 21 · 2023-10-31T11:54:19.000Z

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