Modeling language considerations for SDKs

[xibz]

The SDKs currently rely on JSON schema to generate code. However, the generation code for the SDKs are quite verbose and handwritten. This means we have to maintain this generation code as well, and makes it much harder to get newer features and events to the SDKs.

We need a more powerful modeling language for the SDKs and some mentions from the spec SIG were:

• CueLang
• Proto
• OpenAPI
  • It was mentioned that OpenAPI may not be a suitable fit for the SDKs given its primary use case is to generate web services.

[xibz]

Consider using a single generator tool to generate all code generation for all SDKs - @sbtaylor15

[davidB]

Comment for memory

link to a related discussion: cdevents/spec#240
link to my sandbox repo with my wip exploration: https://github.com/davidB/sandbox_cdevents_spec

[m-linner-ericsson]

Interesting topic that I will try to follow.

In Eiffel we have created a custom definition language that we use to create the JSON and documentation from. For more info see https://github.com/eiffel-community/eiffel/blob/master/eiffel-syntax-and-usage/event-schemas.md

I notice that you want to generate the code also which is not the case for Eiffel, we only generate the JSON and documentation. However the https://github.com/eiffel-community/eiffelevents-sdk-go is generated from the JSON schema. Check with https://github.com/magnusbaeck if you want more information on the code generation.

[xibz]

@m-linner-ericsson I will check this out! In the next appropriate SIG, may be spec or implementations, @davidB and myself plan on demoing a few modeling languages that may solve this problem:

• Investigate the use of PKL to generate JSON schema in a more consistent manner which will still rely on JSON schema, so not too much change is required.
• Investigate the use of OpenAPI to generate the SDKs

I will take a look at some of the code generation. Is there a single generator? I noticed you mentioned Go is generated from the schema, and I think that's a pattern we want to move away from where each SDK is using its own generator.

[m-linner-ericsson]

• Investigate the use of OpenAPI to generate the SDKs

Have you taken a look at https://www.asyncapi.com/docs/tutorials/generate-code also?

[xibz]

Have you taken a look at asyncapi.com/docs/tutorials/generate-code also?

David has been looking into OpenAPI, but we can definitely ask at the SIG next week. I've never used async API, but what are the benefits to using this as opposed to something like OpenAPI?

[magnusbaeck]

I will take a look at some of the code generation. Is there a single generator? I noticed you mentioned Go is generated from the schema, and I think that's a pattern we want to move away from where each SDK is using its own generator.

Well, you could produce SDKs for multiple languages with a single generator. To a large degree I'd expet it to be a question of sending the schema data through different template files (see the eiffelevents-sdk-go templates). This is probably more work than using an existing description language with language bindings, but you'll get the APIs you want and won't face any restrictions imposed by the description language.

[xibz]

@magnusbaeck Thanks. Yea, Im very familiar with code generation in general, especially in Go. However, I wanted to make it easy to maintain, AKA someone else's generator and templates haha. I'll take a look at the repos you all provided and see if there's any nice overlap there that could make it easier for us.

[m-linner-ericsson]

Have you taken a look at asyncapi.com/docs/tutorials/generate-code also?

David has been looking into OpenAPI, but we can definitely ask at the SIG next week. I've never used async API, but what are the benefits to using this as opposed to something like OpenAPI?

AsyncAPI describes themselves as OpenAPI for event based interfaces so that is why I was asking about AsyncAPI.

[afrittoli]

FYI cdevents/spec#148

[xibz]

We have decided upon AsyncAPI. It seems to be the best fitting solution, and there could be other better solutions. However, with our deep dive on the various known modeling languages, we wanted to make some decision rather than spending too much time on investigation. So we have chosen AsyncAPI to move forward on the generating SDKs.

[xibz]

@m-linner-ericsson We have went with AsyncAPI. Thank you for the suggestion!