JSON Schema Documentation

[Tristan Deane]

Hello, I'm looking for some general guidance on how best to format schema documentation on Confluence. More specifically, we have JSON data that needs to be precisely documented because it's referenced across many different systems within my company. There is a complete list of all of the different keys, and depending on the product the actual data the product uses is a subset of the keys from the complete list. Additionally for objects, not all child keys within an object are applicable, they may also fluctuate depending on the product. For example, one project may have parent.child_1 and parent.child_2 but another product may only have parent.child_2 in its schema.

Another thing to consider is that the data structure is not flat and there are many JSON objects that are several layers deep, objects within objects within objects. I need to have a clean way of describing the data elements within the child object. Tables within tables within tables get complex quickly, and having a separate column in a table for child fields can make for many many columns that are mostly empty making the data sparse and hard to read.

So far I've tried the following:

1. A row in a table for the highest level object only, each child key within the object is described but is not documented in its own line within a table.
2. Having each row in a table include the full structure, so it looks like the following
   
   parent
   ----
   parent.child_1
   ----
   parent.child_2
   ----
   parent.child_2.grandchild_1
3. Create a row in a table about the parent key, and then all child fields are in their own completely independent table. This has mostly been used when a child object's data structure is re-used across multiple parent objects.

None of the options have really been great for one reason or another. Option 3 has been the best so far but there is a lot of bouncing around a page as you drill in to objects and people get lost at times. I'm not sure what other people use to solve this problem. Any add-ons or built in tools are welcome suggestions. Thank you!