What JSON structure to use for key value pairs?

Question

What JSON format is a better choice for key value pairs and why?

[{"key1": "value1"}, {"key2": "value2"}]

Or:

[{"Name": "key1", "Value": "value1"}, {"Name": "key2", "Value": "value2"}]

Or:

{"key1": "value1", "key2": "value2"}

The first variant seems more compact and more "semantically meaningful". The second variant seems more evenly structured which might help processing it. The 3rd variant seems even more semantic.

The key value pairs will be used to attach arbitrary data to some other item. The data must be serialized as JSON to round-trip it through a system.

Answer 1

Whether you choose the first or the third option depends on your use case. If you are modeling many different instances of the same type of thing, choose the first. For example, you have a list of people. If you are modeling many different attributes of one thing, choose the third. You can have repeated keys in the first format, but not in the third.

The second option is terrible, and I've yet to find an appropriate use case for it. The reason it's terrible, in addition to being more verbose, is that for single-level JSON, it breaks most libraries' automatic conversion to a dictionary/map. For deeply-nested JSON, it breaks the XPath-like query interface.

This makes it a pain to work with. And if you don't know your keys at compile time, you will want a dictionary or XPath interface, because you won't be able to convert it to a class. It may not seem like a big deal now, but the longer you have a data format, the harder it will be to change.

Answer 2

You say these are key / value pairs. In that case, use #3: dictionary of key / value pairs.

If these are not key / value pairs, then don't call them "keys" and "values" and use #2, an array of dictionaries with arbitrary contents.

Structure #1 is just daft unless you need key / value pairs but also their order. Which you rarely do.

Answer 3

The 3rd format is in general the best. However, here's an example of something suitable for the 1st format:

[{
  "username": "foo",
  "id": 1
}, {
  "username": "bar",
  "id": 2
}, {
  "username": "baz",
  "id": 3
}]

Here each object refers to a separate thing (and each object uses the same keys as the others, so they couldn't be merged). However, each object in the list is stored as { "username": "foo", "id": 1 } rather than [{ "username": "foo" }, { "id": 1 }] because 1) it's shorter and 2) it's referring to one thing with a username and an id, not one thing with a username and another thing with an id.

The problem with the second option is that it becomes very verbose both as JSON and to work with. However, it could be used if you need to store meta-information about the property. An example:

{
  "key": "foo",
  "value": 1,
  "mutable": true
}

Here mutable refers to a hypothetical case of whether you can modify the property itself, not the parent object. Meta-information like this is similar to JavaScript's Object.defineProperty, which stores "configurable", "enumerable", and "writable" information about a property.

Answer 4

Put your self in the shoes of the person receiving the json. If i don't know the key name how am i supposed to retrieve it with the first or the last format? You can loop through the json of course but since all three formats achieve the same result it's just a question of syntax. I think this is the only meaningful question: if you know the key names the first or last option are more compact, if not the second choice is more understandable.