Using json key to store value, is it a good approach?

Question

I am writing a rest api and I am quite new to the json serialization.

I know that a json object consists of pairs of <key>:<value>.

I have an object "channels" which contains multiple channel objects which consist of an id and some other attributes like "x", "y" and "z".

In our team we found two ways to represent the object "channels", the usual way that I see people implement is like this:

{
"channels":
    [
        {
            "id":0,
            "x":0,
            "y":0,
            "z":0
        },
        ...
    ]
}

There is also this version, which uses the id as key:

{
"channels":
    {
        "0":
        {
            "x":0,
            "y":0,
            "z":0
        },
        ...
    }
}

Please note that the first implementation explicitily uses an array while the second relies on the <key> to access the specific channel directly.

What is the best way to represent this object? Is it ok to represent a key as value (like the id of the previous case)?

Right now there are only two channels (always with id 0 and 1), but in the future we may add more.

Answer 1

You should prefer the first approach, because it is much easier and more intuitive to consume the JSON that way. If someone wanted to use your API, they would likely create model classes to deserialize into. With the first approach this is easy:

public class RootObject
{
    public List<Channel> channels { get; set; }
}

public class Channel
{
    public int id { get; set; }
    public int x { get; set; }
    public int y { get; set; }
    public int z { get; set; }
}

In fact, you can just take the JSON and dump it into a generator tool like http://json2csharp.com/ to get these classes (that is what I did here).

In contrast, with the second approach, the keys in the JSON representing the IDs are dynamic, which a generator won't recognize as such. So you'll get something like this, which needs to be manually corrected:

public class RootObject
{
    public Channels channels { get; set; }
}

public class Channels
{
    public __invalid_type__0 __invalid_name__0 { get; set; }
}

public class __invalid_type__0
{
    public int x { get; set; }
    public int y { get; set; }
    public int z { get; set; }
}

I've seen some people try to fix it like this, which will work for your one-channel example, but obviously won't scale:

public class RootObject
{
    public Channels channels { get; set; }
}

public class Channels
{
    [JsonProperty("0")]
    public Data Item0 { get; set; }
}

public class Data
{
    public int x { get; set; }
    public int y { get; set; }
    public int z { get; set; }
}

To consume the JSON properly with the dynamic keys, the classes actually need to look like this:

public class RootObject
{
    public Dictionary<string, Channel> channels { get; set; }
}

public class Channel
{
    public int x { get; set; }
    public int y { get; set; }
    public int z { get; set; }
}

However, the fact that you need to use a Dictionary here is not always intuitive to the casual user. In fact, I have lost count of the number of times some flavor of the question, "How can I handle dynamic keys in JSON?" is asked on StackOverflow. Do your users a favor and don't make them have to think about it.

Over and above just deserializing the JSON, the first model is also superior because the Channel object contains all the data about the channel: the id is inside the object itself. It is easy to pass around and use that way. Also it is trivial to convert a List<Channel> into a Dictionary<int, Channel> later if you need to do a key lookup:

var dict = rootObject.channels.ToDictionary(ch => ch.id);

With the second approach, the id is separate from rest of the channel data, so if you wanted to pass the channel to a method which needed both, you would either have to pass two parameters or create a new model class to wrap everything together. In other words, it is more awkward to use.

Bottom line, I see no real upside to using the second approach at all. Go with the first.