[Json] On flat vs nested JSON encoding style

[Phillip Hallam-Baker <[e-mail]>]

I think it would be helpful to have a style guide to encourage styles
of JSON use that impose the fewest constraints on
serialization/deserialization design.

For example, lets say that we have a protocol that has two types of
request, A and B. There are two common ways that this can be
represented in JSON:

Nested style:

{ "A" :
   { "field1" : "value1", "field2" : "value2", "field3" : "value3" } }

Flat style:

{ "Type" :"A" ,  "field1" : "value1", "field2" : "value2", "field3" : "value3" }

They both look similar, the only difference is that there is an extra
layer of nesting in the first case which means that the label "A" will
always precede the data it describes. This isn't the case for the
second which can also be written :

{ "field1" : "value1", "field2" : "value2",  "Type" : "A" , "field3" :
"value3" }

While the issue comes up with requests, it isn't limited to requests,
it can happen anywhere that you have a need to tag an object to
describe the type.

If you are using a scripting language, you parse the data to a DOM
tree and which is the in-memory representation of the data.

But those of us who use strongly typed languages like C# and Java
don't work of DOM trees. We map the data to objects in our
implementation language. and we type check and validate all our inputs
before we begin processing. Because that is best practice for
minimizing attack surface from an invalid input.


Nested style allows us to build fast, single pass deserialization
tools that require no additional buffering. A constrained device can
build the parse tree on the fly without buffering a whole message
before it starts processing.

Flat style requires us to buffer the data and do a two pass approach.
It is very much less efficient as a result.


Comments?