Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
Celebration

Earn badges and make progress

You're on your way to the next level! Join the Kudos program to earn points and save your progress.

Deleted user Avatar
Deleted user

Level 1: Seed

25 / 150 points

Next: Root

Avatar

1 badge earned

Collect

Participate in fun challenges

Challenges come and go, but your rewards stay with you. Do more to earn more!

Challenges
Coins

Gift kudos to your peers

What goes around comes around! Share the love by gifting kudos to your peers.

Recognition
Ribbon

Rise up in the ranks

Keep earning points to reach the top of the leaderboard. It resets every quarter so you always have a chance!

Leaderboard

Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
4,458,045
Community Members
 
Community Events
176
Community Groups

JSON Schema Documentation

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!

0 answers

Suggest an answer

Log in or Sign up to answer
TAGS

Atlassian Community Events