Event Dictionary - generate human readable documentation library

[dashirov]

All,

We have completed initial development of the documentation app and are ready to share the spoils. Some things worked out, some we may need the community expertise to help us out with.

Limitations:

1. iglu-central contains schemas in jsonschema and avro formats. Documentation app currently only covers self-describing schemas in jsonschema format. Question to the community - who uses avro schemas and in what context?
2. iglu-central contains self-describing schemas with no corresponding jsonpaths and sql artifacts. Those can we generated using igluctl or similar utilities, but that action should be performed by schema owners. Question to the community - should repository PRs be accepted if these artifacts are not submitted by schema vendors? Should defaults be generated? What should be the default constraints on string fields in those cases?
3. In our opinion, Ideally documentation app is deployed on top of iglu scala server, similar to current co-deployment of scala components and a swagger interface. We could not fully integrate the documentation UI with iglu during the initial iteration. Instead we developed a few scripts to (a) export public iglu server schemas to local file system and (b) merge jsonpaths and sql artifacts into the body of the jsonschema artifacts.
   
   
   
   
   
   
   
   
4. We introduced, as was suggested in previous ports on this subject, the following elements:
   (a) description - to capture notes for human consumption, (b) example - to serve both as a part of documentation of each payload element and as means to generate example for the entire event. The end-results are similar to previously posted screenshots.

There are two alternative implementations we can think of:

• fully integrated with iglu scala server, it could use backend API to discover schemas stored on the iglu server and provide immediate response from documentation rendering perspective.

• fully compatible with iglu static content repository. It could compute sql file and jsonpath file corresponding to a given schema and try to load it into a complete doc.

Our current iteration lies somewhere in-between.

Is there an interest in the community to take these ideas forward? Is this just another cool thing or will you actually benefit from the app? Are we willing to make modifications to igluctl and other utilities to support updated self-describing schema format?