Discussion about JSON payloads and code generation

With this post I would like to talk about the current situation of describing JSON payloads and how we can use those specifications for code generation. To get started I will explain the situation from my view and also the lessons learned which we have gathered from building TypeSchema.

Currently the most known specification to describe JSON payloads is JSON Schema, this is also due to the fact that it is integrated into OpenAPI. JSON Schema is great to validate JSON payloads but it is difficult to use for code generators, since it has a highly recursive and flexible nature. Currently there are tools available which use JSON Schema for code generation but they all have to somehow solve the inherent problems of JSON Schema.

It looks like OpenAPI will be in future versions more JSON Schema independent so that it would be possible to use also other schema specifications, which are more optimized for a specific use case like i.e. code generation. There is currently already JTD RFC8927 which tries to solve those problems and we have developed a specification called TypeSchema for our use cases. JSON Schema has also this idea of vocabularies, which theoretical could lead to a solution but there is currently no vocabulary available for code generation and from my point of view it would be best to develop this in a separate specification, since all vocabularies inherent properties from JSON Schema which are not suited for code generation.

To be more specific we have wrote down some points which are (from our view) useful for a code generation specification:

1. Determine type based on the schema

2. Unique name for each entity

In this case a code generator has no unique name for the “parent” object. We need this name since this object is maybe also used in other objects and we want to generate only a single class to represent this type. Because of this we have disallowed nested objects at TypeSchema and allow only references inside an object, the example above would look like:

Through this restriction we are always able to find a unique name which we can use i.e. as class name and which is also recognized by the author of the schema. In JTD it looks like nested objects are also allowed, this would then result in the same problem.

3. Extending existing types

4. Generics

This makes it also easy to change an existing collection even if it used by many entities. Also code generators can generate actual “generics” if the language supports this like i.e. Java or TypeScript.

5. Union/Intersection types

6. Import

7. Keyword compatibility

Conclusion

I am a developer in the API space, currently working on Fusio an open source API management platform