Gnostic JSON Schema Generator

[tfesenko]

Intro

Often times, developers generate documentations and specifications from a machine-readable format. Much less often we can see an executable artifact generated from a human-readable text. This is why I like Gnostic JSON Schema generators for OpenAPI v3. It takes the specification in MD format and generates a JSON Schema from it.

Is Artificial intelligence involved, we are in 2017 at the end? No! No AI, no magic, Just well-organized specification as an input and a talented developer who can write a generator.

JSON Schema is written in Go, you can find the sources here.

Overall Structure

Apparently, as it often happens, the magic is implemented through several steps. Each of them is relatively simple, but together they create an amazing result.

Component by Component

Step 1: ReadSection(): Create a Collection of Section objects from a file text

Read the markdown file and create a list of sections, where a section describes... well, a markdown file section which defines its level, title, text, and subsections:

So simple!

Step 2: NewSchemaModel(): Create a specialized SchemaModel tailored for OpenAPI.

It takes the generic sections and creates a SchemaModel which is customized to describe OpenAPI specification. For example, if a section text contains the "Specification Extensions" string it means that the element can have specification extensions and the schema object marked as "extendable".Note that SchemaModel still speaks the OpenAPI 3 specification vocabulary. "FixedFields" and "PatternedFields" are the terms borrowed directly from the human-readable specification.

This is what is also printed out to debugging.

Step 3: buildSchemaWithModel(): Create a generic SchemaModel using customizations(?)

This is the most interesting part of the generator. This is where the "FixedFields" become JSON Schema "properties" and "PatternedFields" become patternProperties. Human-focused information is transformed into machine-friendly strings here. For example, component names are described as {name} and then explained that "bla".. Modern JSON Schema validators can't interpret descriptions like that yet, not in 2017. They need an old-fashioned regex, so we, humans, need to provide this regex to the JSON Schema validator. buildSchemaWithModel() is the place where we are adding customizations like that and replace a beautiful human-friendly description with a strict machine-readable format.

Step 4: Serialize Schema object in a JSON file

Thanks to the ... , this step is a piece of cake :)
The simplest step, done with the help of the BLA library, which is also a hosted in the gnostic repository.

Conclusion

I really like how JSON Schema generator works, I also contribute changes to it from time to times. it’s seldom enough so I a forget how it’s implemented. That’s why I decided to describe how this no-magic text-to-code generator works. Maybe it will inspire other people to create other text-to-code generators. Or at least write better-organized documentation

[tfesenko]

Used materials

• Diagram: https://www.draw.io/#WE27B9AC017596EA0!857
• Gnostic site: https://github.com/googleapis/gnostic/blob/master/OpenAPIv3/schema-generator/main.go
• Atom-IDE + go extension