Document schema API

[nbgl]

Documentation required for:

• Making a JSON file with the schema. Consider a format similar to the OpenAPI documentation.
• Making schema within code.

Aha! Link: https://csiro.aha.io/features/ANONLINK-47

[wilko77]

One aspect is that the it would be nice to have the schema definition to be the source for the docs. Similar to openAPI which can be nicely visualized with swagger UI https://swagger.io/tools/swagger-ui/. This would have the advantage that the doc always represent the current schema, and the extra work of reproducing the schema structure in the docs would be obsolete. (Maybe this sphinx extension would work: https://github.com/lnoor/sphinx-jsonschema)

Another thing I can think of is that the documentation around programmatic schema creation (using the API) is somewhat neglected. Tasks for this would include assessing what we've got. Is it enough to help someone to create a valid schema? Should we provide more guidance?

In general, the current linkage schema documentation does not contain a lot of information to make informed choices. (think of strategies, comparisons, more exotic features like XOR-folding)

[wilko77]

sphinx-jsonschema extension doesn't work. It does not support all json schema features, i.e., definitions, which are integral to our schema.

[wilko77]

I've also tried https://github.com/adobe/jsonschema2md. Again, not usable, as it cannot read definitions properly.