JSON design for a web service - how to express attributes - json

Question

On my team there seem to be two schools of thought in designing our restful interface. This is a series of endpoints that themselves are a product we sell, so the customer interface is JSON. The question is how to express attributes of an object. My thoughts are to have attributes as explicit fields for a resource like this:
{
"myThing": [
{
"color": "blue",
"number": "212"
}
]
}
With this approach, you can understand the object by knowing its attributes, and it feels more elegant as well as explicit. Documentation is straight-forward for business people who are prospective customers.
However, there is a school of thought from some of our developers that the following is the preferred way to express attributes - I believe because we have a lot of attributes and it's easier to manage, though there may be other benefits. However, I don't see the architecture of this information as being as user-friendly or explicit, and requires cross-referencing documentation more extensively.
{
"myThing": [
{
"attribute": "color",
"value": "blue"
},
{
"attribute": "number",
"value": "212"
}
]
}
My question - aside from feeling the first approach is more intuitive, finding best practices or a persuasive argument for one approach over another is difficult. Can anyone point me to some best practice JSON design that would favor one over the other? Thanks!

Answer 1

Oh this is simple to qualify in some basic terms, however both can work.The trick is deciding which one is going to be more successful? It helps to think of successful vs unsuccessful, the whole right or wrong argument is very much based on personal opinions and is such a massive waste of time. Never argue this is the right way to do it with tech guys you will have an easier time herding cats.
So lets break down the model into Pro And Cons.
Approach one is a traditional model:
Pro:
Objects and attributes are well defined.
Attributes can be validated as they are known i.e. this a date.
Easier to understand and document.
Cons:
Attributes are static and expanding the attribute set will require us to update a code and potentially introduce problems with clients as they are aware of the attributes.
Approach two which is known as the Entity Attribute Value design pattern(a BIG no no in relation database design by the way).
Pro:
Adding attributes to an object does not require that much changes. Also its unlikely to break clients etc.
Cons:
Documentation is harder.
Data validation is much harder, the colour attribute in your example should it be a string like Blue? Or a HEX like #ffae12? Maybe CMYK? Its get harder to validate and document these type of things.
Requires developers/customers to understand the mechanism to set and get values i.e. it break the normal programming paradigms.
How to choose which model to use?
The principle here is to know your data. If the objects have loads of different attributes and they are pretty dynamic i.e. you add or remove attributes a lot of the time then approach 2 is better. Social media type data for example is a good fit.
If however you are dealing with financial transaction data i.e. debits, credits etc you want the highest validation possible and besides making payments and receiving payments have not changed it's unlikely that you would introduce a third account number to a credit transaction object. Not saying it is impossible but highly unlikely.
As always keep an open mind and use the most appropriate tool for the job when you need it. Don't blindly follow a school of thought. Understand your tools, your data and then it's rather easy to innovate.