Docs: json schema for archive format

[ltalirz]

Describe the current issue

The AiiDA archive format is currently "specified by example" on https://aiida-core.readthedocs.io/en/latest/internals/data_storage.html#aiida-archive-format

E.g. it is not specified which fields are optional, which are required; and fields have no associated documentation.

Describe the solution you'd like

It would be useful to replace this example with a JSON schema, which specifies the format more rigorously.
It could be included in the documentation and could also be used to automatically validate the metadata.json and data.json files.

[ltalirz]

I've started looking into this and created a JSON schema for the metadata.json using https://jsonschema.net/home :
https://gist.github.com/ltalirz/7da3a1ff1f87118ada2dc6982ad86578

However, integrating the JSON schema into the documentation proved a bit more difficult than anticipated.
There is sphinx-jsonschema which works fine but it doesn't support "toggling" of subsections and it can't display more than 3 nesting levels in our docs layout (+ there is no horizontal scrolling!)

There is an open issue to add a max depth option lnoor/sphinx-jsonschema#12 but we would have to do it ourselves, and the question is whether we also want toggling.

There is also the more interactive json-schema-for-humans which uses bootstrap and therefore doesn't play well together with sphinx.
There is an open issue to switch to CSS coveooss/json-schema-for-humans#4

Since we're going to overhaul the archive format anyhow, I'm putting this on hold, using this issue to record the status quo.
I suggest we come back to this once we document the new archive format.

[chrisjsewell]

Closing this, since data.json is not a thing anymore and the sqlite database schema is now fully documented (using https://sphinx-sqlalchemy.readthedocs.io), then the only required field in metadata.json is export_version.
Feel free to re-open if you still think there is more documentation to be added