JSON: better define a type of object inside or outside the object?

Question

Context

We are building a JSON API for web (HTML+JS) and mobile (iOS/Android/Windows).

Server needs to send data with a base structure and a variable structure. In our example, the base structure includes "name" and "description", the variable structure is called "template" and have different fields depending on its type. We figured out at least three ways to write it (there may be more):

A: variable structure type defined outside the object

{
  "id": "A001",
  "name": "My First Game",
  ...,
  "template_type": "BATTLE",
  "template": {
    ...
  }
}

In this scenario, the client should look at "template_type" in order to determine how to parse "template". The "template" object alone is not self-sufficient to know what it is.

B: variable structure type defined inside the object

{
  "id": "A001",
  "name": "My First Game",
  ...,
  "template": {
    "type": "BATTLE",
    ...
  }
}

In this scenario, the client should look at "type" inside "template" in order to determine how to parse "template". The "template" object alone is self-sufficient to know what it is.

C: variable structure type defined by the key of the object

{
  "id": "A001",
  "name": "My First Game",
  ...,
  "template_battle": {
    ...
  }
}

In this scenario, the client should look at all keys ("template_battle", "template_puzzle", ...) in order to determine which type of game we have. The "template_battle" object alone is self-sufficient to know what it is, because it would always be the "BATTLE" type.

Question

Any recommendation on which JSON solution is the most client friendly for web and mobile to parse and use? (you can propose other solutions)

Answer 1

Personally, I would put the type on the template itself for a simple reason, that is encapsulation. Imagine you want to separate the creation of the template and the outside object (remember separation of concerns and the single responsibility principle (https://en.wikipedia.org/wiki/Single_responsibility_principle)). If the type is on the outside object, you will always have to specify the type of the template, to be able to create it. That's a possibility, but it increases coupling and violates encapsulation.

For further reading I recommend https://en.wikipedia.org/wiki/SOLID_(object-oriented_design) for the beginning.

Answer 2

The approach B would be much better IMHO. That is simply because, it provides a generic approach for user to access the template's attributes without concerning about its type. In this manner, user can simply write his program for a generic template which include the type as an attribute of itself.

For example, imagine you have a object type named Template which maps the json definition of a template to a Java object.

Class Template{
  String type;
  String attribute1;
  String attribute2;

......
......
}

By using approach B, you can directly map the json definition of that template, to above template object.(In this case, it is a Java object but of course the concept works for any other programming language).

User does not need to have an prior knowledge of template type, before accessing the template's definition. That's why it is said to be a more generic approach.

Answer 3

I'd prefer your B variant over A and C.

However, you might also consider a structure like this:

{
   "longDesc": "The Long description and other(?)necessary hints here", 
   "type": "template",
   "ID": {
      "A001": {
         "name": "My First Game",
         "type": "BATTLE"
         /*more data here*/
      },
      "A002": {
         "name": "My 2nd Game",
         "type": "STRATEGY"
         /*more data here*/
      }
   }
};

It might give a better feel in everyday use.