TypeSchema an alternative to JsonSchema

TypeSchema is a code generator friendly alternative to JsonSchema. You may be thinking, why do we need an alternative to JsonSchema, let me explain it:

For code generators it is difficult to work with JSON Schema since it is designed to validate JSON data. In JSON Schema you dont need to provide any keywords i.e. {} is a valid JSON Schema which basically allows every value and the defined keywords are applied based on the actual data. This means you can interpret a schema only if you have also the actual data. A code generator on the other hand needs to determine a concrete type of a schema without the actual data.

Because of this TypeSchema is designed in such a way that it is possible to determine a concrete type based on the used keywords. You can think: TypeSchema is to JsonSchema what TypeScript is to Javascript, a more type safe version which has also keywords for better inheritance, union/intersection and generic handling.

An important factor for the development of TypeSchema is the OpenAPI specification. We want to use the OpenAPI specification to automatically generate client SDK code, but we have realized that JsonSchema is not optimal designed for code generators.

At the OpenAPI specification there is also an ongoing discussion about the direction of JsonSchema. Initially the OpenAPI spec contained a restricted JsonSchema spec and was separated from the originally JsonSchema spec since the authors also noticed that the idea how JsonSchema works is not designed to describe data structures. After some time a group of people tried to combine those specs so that the OpenAPI spec only referenced the JsonSchema spec. At the first look this sounds like an great idea so that users don`t get confused with two specifications.

But in my honest opinion this is a bad decision, since OpenAPI is designed to model your data and not to validate data. JsonSchema has developed the idea of “vocabularies” so that it would be possible to cover also other concerns then validation, but currently there is no code generation vocabulary available. Also it does not solve the inherent problem of JsonSchema, that we can interpret a schema only along side the actual data. In my opinion it would be much better if the OpenAPI specification would contain also the part how to model the data. Then the OpenAPI spec would be free to define the keywords which are required to model your data. If you take a look at the discussion about the removal i.e. of the “discriminator” keyword, which is perfectly designed to describe a tagged union, you can see the problems which occur when two specifications needs to arrange.

Currently it looks like the OpenAPI spec goes the JsonSchema road to reference only the JsonSchema spec. To solve this problem and to be independent of the decisions of the JsonSchema community we have developed TypeSchema. A TypeSchema can be easily converted into a JsonSchema which we can then use at any OpenAPI spec. If you like the idea of TypeSchema feel free to like and share the repository. We are currently at the beginning of development but we think this is the right direction to go.