Duplicate Keys in JSON Objects

We came across a strange problem when building a new RESTful API recently. If we sent duplicate keys in our JSON request, how should the API handle it? Shouldn’t that request be rejected straight away as invalid JSON? Are duplicate keys even allowed in JSON? I did a bit of digging around to clear up this debate, and this is what I found...

RFC-7159, the current standard for JSON published by the Internet Engineering Task Force (IETF), states "The names within an object SHOULD be unique". Sounds pretty clear, right? However, according to RFC-2119 which defines the terminology used in IETF documents, the word "should" in fact means "... there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course." So, things just got a bit more confusing. What this essentially means is that while having unique keys is recommended, it is not a must. We can have duplicate keys in a JSON object, and it would still be valid.

// Despite the firstName key being repeated, this is still valid JSON
{
  "id" : 001,
  "firstName" : "John",
  "firstName" : "Jane", 
  "lastName" : "Doe"
}

The validity of duplicate keys in JSON is an exception and not a rule, so this becomes a problem when it comes to actual implementations. In the typical object-oriented world, it’s not easy to work with duplicate key value pairs, and the standard does not define how a deserializer/parser should handle such objects. An implementation is free to choose its own path, and the behaviour is completely unpredictable from one library to another.

For example, a parser may take only the last value present in the object for a particular key and ignore the previous ones. It could also return all the key-value pairs, or it may even reject the JSON with a parsing error, and all of these behaviours would be valid. That said, most popular implementations (including the ECMAScript specification which is implemented in modern browsers) follow the rule of taking only the last key-value pair, but there is always the possibility of another library handling it in a different way. In our case, we went with the last key option, but there may be use cases where that is not acceptable and you may want to disallow duplicate keys altogether.

This kind of difference in behaviour can be problematic particularly in modern polyglot architectures, where the behaviour of different services should ideally be as consistent as possible. It may be unlikely that such a scenario would actually occur, but if and when it does, it would definitely help to know how your applications behave and have it documented as such for your consumers and fellow developers.