Using Mermaid to render an ERD from JSONSchema

[mrshll1001]

I've been doing some thinking on how best to generate an ERD directly from the JSONSchemas rather than from the Frictionless Data Package file and I think I might have a way forward.

It still requires an intermediate step, but one that's much more closely aligned to the JSONSchema than currently.

We should be able to transform the Schemas into Mermaid, which allows us to create diagrams with text and code:

• http://mermaid.js.org/intro/
• http://mermaid.js.org/syntax/entityRelationshipDiagram.html

There is a handy Sphinxdoc plugin for Mermaid, which we can then use to render these diagrams in the docs. It can be used to draw a diagram from a reference to a file:

• https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/index.html

In terms of existing tech, it's clear that a few people have done some work to transform JSONSchema files into Mermaid syntax. I have yet to find one that we can integrate into our tooling, though:

• https://github.com/TeemuKurki/json-schema-to-mermaidjs (TypeScript)
• https://github.com/TeemuKurki/json-schema-to-mermaidjs (JavaScript, but dependant on OpenAI/chatGPT by the looks of it)

I think it would be straightforward (not trivial though) to either add this feature to the HSDS Schema tools script, or develop it as an independant Python tool or library which can then be integrated into the former.

Once we had the Mermaid syntax ouput in a file, this would then mean a one-time update to the docs site to point towards the diagram file.

The workflow for updating/generating the diagrams during standard upgrades would be the following:

• do your schema work/edits
• run a command from the HSDS Schema tools to output a diagram into a file (overwrite the existing one)
• build the docs