Flat or nested JSON for hierarchal data?

Question

I've switched back and forth ~5 times already. This REST endpoint at /api/tags/ will be for internal use (no 3rd party clients), I'm the only one working with it.

I'm deciding between these two representations:

Flat

{  
   "types":[  
      {  
         "id":1,
         "text":"Utility"
      },
      {  
         "id":7,
         "text":"Lease Terms"
      },
   ],
   "tags":[
      {  
         "id":8,
         "text":"Water",
         "type":1
      },
      {  
         "id":9,
         "text":"Electricity",
         "type":1
      },
      {  
         "id":5,
         "text":"Minimum 12 month lease",
         "type":7
      },
      {  
         "id":17,
         "text":"lease negotiable/flexible",
         "type":7
      },
   ]
}

• It's somewhat modular. Can add another top layer such as "country" without breaking compatibility.

Nested

{  
   "1":{  
      "text":"Utility",
      "tags":{  
         "8":{  
            "text":"Water"
         },
         "9":{  
            "text":"Electricity"
         },
      }
   },
   "2":{  
      "text":"Lease Terms",
      "tags":{  
         "5":{  
            "text":"Minimum 12 month lease"
         },
         "17":{  
            "text":"lease negotiable/flexible"
         },
      }
   },
}

• It's already in a usable format. Don't need to loop through data before using it.
• Saves some bandwidth. Even after gzip, this is slightly smaller.

Which one should be used, and why? If this is a matter of personal preference, which representation would experienced developers prefer and why?

Answer 1

Depends on your use case.

When using JSON with statica typed languages, there is a huge bonus if your structure maps to your types. This means that all the names of the keys should be known in advance.

So, if you plan to use Java to consume the service, or if you plan to document it with JSON Schema, number one will be much cleaner (of course both will work).

Answer 2

Hard to say without more context. I have worked with both but progressively I started to lean to #1. In general, I have found simplicity more relevant than sophistication.

In #1, entities and relationships are clear and obvious, whereas #2 requires a different way of thinking. For some people, trees (as data structures) are not that self-descriptives. Think in junior developers who barely have seen a composition|aggregation deeper than Person > Address.

I could read #1 as:

• there's a collection of typed tags.

But, how could we describe #2 only in 7 words? If I were unfamiliar with tree structures I could read #2 as

• tags have two attributes 5 and 17, but I don't know their types. Whatever the type is, has one attribute, text.

Don't get me wrong, #2 could be a smart solution, but I would not sacrifice readability for cleverness (or efficiency) unnecessarily.

At the writing of this answer, I'm working on a project which needs to be integrated with a 3rd party service which responses are very similar to #2. The service is providing us with a calendar: year, months, days and hours of the day

 { "2017" : { "01": { "01" : ["00:00", "01:00", "02:00"] } } } 

As Java developer I am, the deserialization of the service response ended up in code that is anything but readable because there's no direct mapping to classes through getters|setters|constructors. Instead, I have had to traverse the document (getNode, getSiblings, getNodeName, getChildAsText, isNodeObject, isText, etc) and populate my hierarchy of classes manually. Finally, I managed to map the tree of numbers into a collection of timestamps! Which structure would you say is easier to read and deserialise? And which one would you like to get if you were on the client-side?

Answer 3

If you didn't want anything else, you could just use:

{
    "Utility": {
        "8": "Water",
        "9": "Electricity"
     },
     "Lease Terms": {
        "5": "Minimum 12 month lease",
        "17": "lease negotiable/flexible"
     }
}

Unfortunate here that JSON only allows strings as keys.