The things you don’t notice

I recently ran into a chunk of JSON data that kept being rejected by JSON.parse but worked as expected if I used eval (nasty, but this is local data so livable-ish).

I had looked at the raw data and saw nothing out of the ordinary. At first I suspected the quickly tossed together code I was working with. When I finally pasted the document into a JSON validator it immediately pointer to the ‘//’ comments that someone had inserted.

Standards always tell the tale

A quick refresher look at the JSON Specification reminded me that the spec is very lightweight and has nothing beyond the minimum needed to do the job. Comments are definitely not in there. The two formal standard are rfc7159.pdf and ECMA 404.

The discussion

It is no surprise that people would like to add them. JSON has become popular as both a message passing serialization format and as a format for storing structured data over the longer term.

Being able to add comments to a configuration file or saved bunch of settings would be convenient. One of the prime benefits of JSON over something like GPB or other pure binary serialization format is the human readability of the resultant data set.

Humans can not only look at the data but in many cases can (with relative safety) make changes using a simple text editor and some caution. Comments would provide helpful sign-posts along the way.

My conclusions

With all of the above being said, the standard does not allow comments in well formed JSON data sets. The fact that many people would like them there can not change this.

My first thoughts on the reason for this omission centered around the genesis of JSON itself. From what I understand, it started as chunks of JavaScript code run through eval. This permitted data structures to be passed around, but also permitted malicious code to be passed around. The formal JSON standard seems to have been a response to that problem. It tightly constrains what is allowed and I expect the folks who wrote it didn’t want to add anything that wasn’t directly required to get the jobs done as any extra ‘surface area’ was just another spot that errors could creep in and let hackers through.

After a bit of thought I also realized that with XML technologies, comments can be preserved through transformations as there is a DOM representation of comment elements. In JSON as the ‘target’ for a chunk of JSON data is nominally a JavaScript object. Since JavaScript objects don’t preserve comment information from the source code that generated them, there is no reasonable way to round-trip JSON with comments. To me this is the most convincing argument against using comments in JSON (even if some parsers will allow it).