What tools to use on documenting event schema

Question

Our team is starting to implement event driven designs. We are now figuring what's the best tool/s and practices for documenting the schema of these events.

What are the common tools used for this use case?

Any links or suggestions is appreciated.

Elba

Answer 1

I would start off with the common CloudEvents spec and model my events based on that, i.e., define the events as subtypes of the generic CloudEvent model. The benefit here is interoperability with other systems based on the same spec as well as the existing tooling such as language SDKs.

As for documentation, I'd go for JSONSchema: here's the JSONSchema definition for a generic CloudEvent for example.

As an alternative, there's the AsyncAPI specification which you can use instead of or together with CloudEvents: read here on how the two relate.

Anabasis