JSON Schema documentation generator

[pvlasov]

Hello,

I've created a documentation generator for JSON schemas and generated a documentation site for the A2A JSON schema. It features generated diagrams, full text search, and more as explained in Documenting JSON schemas story.

I use the documentation to get a grasp JSON structures in a non-linear way - by looking and diagrams and clicking on diagram elements instead of scrolling text. I think this approach to documenting JSON schemas can be helpful in driving understanding and adoption of a particular schema or a set of related schemas.

Currently the A2A documentation site contains only the information what was available in the schema itself - everything was generated - I added one documentation sentence and manually rearranged elements on the home page diagram, which was generated as well. However, documentation pages can be extended with hand-crafted documentation - descriptions, code snippets, ...

An important note - this is not a tool which you feed a schema and get a documentation site, although such a tool can be created - see below. It is a solution/process - generate a model from a schema, enrich with fine-grained documentation, generate diagrams and a web site. It took me a few hours to produce the A2A schema documentation site from scratch. If an organization is planning to invest considerable amounts of effort in schema development and promotion, a few hours shall be a little investment with a great return!

Tool

A tool can be created as a CLI command taking a schema file or URL and producing a Drawio diagram with multiple pages - one for the schema and a page per class with a context diagram. The tool will also generate markdown files for the schema and every class. It may also generate additional files for the site command to generate a site as explained in Drawio site template.

The generation process can be incremental - it would only overwrite documentation and diagram elements for schema elements which did not exist in the previous generation, has not been "touched" or is marked as "ok to overwrite". Touch can be detected by a change in an element digest computed from the element definition - properties and geometry (size and location), and the documentation file. If the digest is the same, then it is OK to re-generate. There might be two digests - one for the diagram element and another for documentation file. So, the generation process would overwrite a diagram element or a documentation file only if there is a digest property and it did not change. This would allow parallel evolution of the schema, the diagram, and documentation files.

Being a CLI command, the tool can be executed in a build pipeline, e.g. GitHub Actions - in the same way as Drawio sites are published to GitHub Pages - it will be just an extra command in a workflow file.