Documenting Event Contracts using JSON Schema

Typically, when designing a messaging system you choose an open standard for events to conform to, such as JSON or XML. This way, publishers/subscribers are not tied to a certain technology, and they know what format to expect when dealing with the events.

It is common (and good practice) to define all of your event contracts in one central place.

When using a platform like NServiceBus (.NET friendly), this might look like a package containing the C# classes which define the events. This package can then be published using a package manager, like NuGet. This is a good idea as it provides a common place for different services to consume the various events, so that each service doesn’t duplicate any definitions.

However, what if it is not sufficient to tie down your event contracts to a domain-specific technology, like .NET or Java? What if the subscribers could be python or Go applications? Then you need a common vocabulary to describe the events that is understood by any language/platform. A good example of such a vocabulary is JSON Schema.

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.

JSON object -> JSON Schema

If you are have an example JSON object, but are struggling coming up with an appropriate schema, this site generates a sample schema based on the object. It might not be exactly right immediately, but it’s a good starting point.

Validating JSON Schema

If you have defined your schema and simply want to validate an object against it, try out https://www.jsonschemavalidator.net/.

Generating user-friendly documentation

We now have a way of describing the events in a universal language, but JSON schemas quickly become unwieldy in my opinion. They can be quite verbose and hard to read.

One way to alleviate this is to decompose complex schemas into lots of smaller ones, and then compose them, via references. This is certainly better, but it still leaves something to be desired. Presenting lots of fragmented schemas results in clunky navigation between raw JSON files. And let’s be honest, raw JSON is not all that readable either.

It would be nice to be able to present the JSON schemas in a user friendly way, providing useful documentation.

This can be achieved by parsing the JSON schemas and generating markdown files. Presenting the schemas in markdown format would make them readable, even for non-developers.

Implementation

The following npm package has been developed by adobe. Installing it gives you a number of scripts that turn JSON Schema files into readable Markdown documentation.

I have created a simple wrapper Node.js app that should make it easy to tailor the use of this package for your individual needs.

Leveraging cookiecutter, you can use it as a template to create your own customised project, that will help you generate documentation your specific project needs.

The project GitHub repository resides here and the README provides a setup guide.

Example

Earlier, I was talking about documenting event contracts, so the usage of the cookiecutter project in this case is to make a project for documenting the Events. Usage might look like this:

• Install cookiecutter: pip install cookiecutter
• Generate project: cookicutter https://github.com/mikerogers123/json-schema-to-md-cookiecutter.git
• Enter project specific values, when prompted, like Event Contracts for the project name, and Events for the purpose of the documentation:

Now you should have your own tailored project. you should now be ready to add JSON Schemas, and then use the application to generate the markdown. For a good example on the sort of documentation generated, see here.

Built with GatsbyJS, styled using Terminal CSS