Comments in JSON

There is a interview with the inventor of JSON somewhere. In that interview he explained why he did not allow comments in JSON like in XML. He said - if I remember correctly - that it was intentional to not have comments in JSON. The reason way that comments could be misused to add additional information for a parser. For example in XML you could use comments and a special parser could use these comments to create code while parsing. He did not want that. He wanted every JSON parser to be a JSON parser and nothing more. If you wanted to have comments in JSON he said that you could simply make the comments inline and have a convention for the keys which are comments for example every key ending with _comment could have a value which is then seen as a comment by the application but not by the parser.

I&#x27;m sure there are counter points to what I&#x27;m about to bring up, but three observations:<p>1. In my experience JSON is frequently output programmatically, and taken in programmatically. Comments are not useful in these cases.<p>2. The only time comments could be perceived as useful then would be when parsing JSON by eye or hand. However, it is not difficult to parse JSON and understand it unless the keys have used obfuscated names. If key naming is obfuscated, comments aren&#x27;t really the correct solution.<p>3. &quot;An object is an unordered set of name&#x2F;value pairs&quot;, as mentioned by jasonlotito and others earlier. There is no guarantee that a JSON parser will give you the right value if there are two of the same keys in the same scope.

Given the RFC says &quot;The names within an object SHOULD be unique&quot;, there&#x27;s nothing stopping me from writing a parser that takes the first name&#x2F;value pair and throwing all the others on the floor. Or even better, picks a random name&#x2F;value pair when the same name appears. Both of these behaviours are allowed by the RFC, and would break this hack.<p>Putting comments into JSON in this way is a hack and shouldn&#x27;t be used by anybody who has any interest in writing maintainable software. Relying on ambiguities in an RFC and someone saying &quot;JSON parsers work the same way&quot; is a good way to end up with a really obscure bug in the future.

This is misguided. You don&#x27;t need comments in a JSON config file. Why? Because you don&#x27;t use JSON for config files that need comments.<p>JSON is like duc(k|t) tape. It&#x27;s really easy to stick two things together with it. That doesn&#x27;t mean you always should. It&#x27;s the simple thing that gets the job done so you can focus on what matters.<p>One shouldn&#x27;t pick JSON for your config files and then hold it up as good design. &quot;Look at me, I&#x27;m daring and _not using XML_!&quot; Using JSON is crap design, but good engineering means sometimes picking something crappy and not wasting effort on things that don&#x27;t matter in the end.<p>If your configuration files become both complicated and important enough that you need comments, then you should stop using JSON. If your duck tape job starts needing additional reinforcement, then you should probably just get rid of the duct tape and do it right.<p>If one of your requirements is a sufficiently trendy yet commentable config language, look into YAML. Also, gaffer tape. The white kind is easier to write on.

The JSON RFC (<a href="http://www.ietf.org/rfc/rfc4627.txt?number=4627" rel="nofollow">http:&#x2F;&#x2F;www.ietf.org&#x2F;rfc&#x2F;rfc4627.txt?number=4627</a>) says<p><pre><code> The names within an object SHOULD be unique. </code></pre> SHOULD is defined (<a href="http://www.ietf.org/rfc/rfc2119" rel="nofollow">http:&#x2F;&#x2F;www.ietf.org&#x2F;rfc&#x2F;rfc2119</a>) as<p><pre><code> 3. SHOULD This word, or the adjective &quot;RECOMMENDED&quot;, mean that 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. </code></pre> Salient point is that you would need to ensure that you are only using JSON parsers that tolerate duplicate names (and use the last value)

This hack, while nice, is still just a work around. I highly recommend that if you can, in as many places as possible use YAML instead of JSON.<p>JSON works great for on the fly communication with frontends that are running JavaScript, or for communication between JavaScript processes like Node.js servers. But for configuration files and other things that need comments YAML is many times better, both for it&#x27;s clean, Markdown reminiscent structure, and its native comment support.<p>Node.js has a great module called js-yaml (<a href="https://github.com/nodeca/js-yaml" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;nodeca&#x2F;js-yaml</a>) which automatically registers handlers for .yml and .yaml files, allowing you to require them in your Node.js code just like you can with JSON files.<p>It also comes with a YAML parser for the browser side of things, so if you want you could even communicate YAML directly from the server to the client side, although frankly I don&#x27;t see much advantage to sending YAML over the wire instead of JSON. (And as others have mentioned below untrusted YAML sources could insert malicious objects in YAML, so I wouldn&#x27;t recommend this technique.)<p>You can even use YAML for your package.json in a Node program: (<a href="https://npmjs.org/package/npm-yaml" rel="nofollow">https:&#x2F;&#x2F;npmjs.org&#x2F;package&#x2F;npm-yaml</a>)

This would completely break any event driven (streaming) parser.

My first thought in seeing this was that objects aren&#x27;t guaranteed to maintain order: &quot;An object is an unordered set of name&#x2F;value pairs&quot; - <a href="http://www.json.org" rel="nofollow">http:&#x2F;&#x2F;www.json.org</a>

This definitely qualifies for a Zen style thwack over the head with a stick and a reprimand of &quot;stop being clever!&quot;

This sounds great until some parser uses the comment definition instead of the value. Is it defined in the spec that parsers need to use the last defined value for a key?

Can we all just agree, as a community, to add comment support to our JSON parsers? Hell, I&#x27;d do a PR on V8 if I knew C++.<p>It&#x27;s ridiculous that I can&#x27;t document notes on dependencies in my NPM package.json, or add a little reminder to my Sublime Text configuration as to why I set some value, because we&#x27;re using JSON parsers that can&#x27;t handle the concept of ignoring a line with a couple slashes prefixing it.<p>IMO - either we add comments to JSON, or we stop using it for hand-edited configuration.

Funny story. JSLint[1] does not approve of this technique. I asked Crockford to implement the duplicate check in April 2009 via email. 20 minutes later, out of nowhere, he was done implementing that check and wrote back &quot;Please try it now.&quot;<p>This guy is fast. Especially nice considering we do not know each other at all.<p>[1] <a href="http://www.jslint.com/" rel="nofollow">http:&#x2F;&#x2F;www.jslint.com&#x2F;</a> - JS checking tool from the inventor of JSON

Note that these comments would disappear the second you use a JSON-aware tool to manipulate one of these files.

Instead of using tricks that rely on parser implementation behaviors, why not just put an actual comment field in the object?<p><pre><code> { &quot;myvalue_comment&quot;: &quot;This is a comment&quot;, &quot;myvalue&quot;: 42 }</code></pre>

Terrible spec-violating hack aside, the idea of the author soliciting upvotes on StackOverflow doesn&#x27;t sit well with me. I&#x27;d hate for SO solutions to become diluted by answers from users who are &#x27;marketing&#x27; for upvotes.

It is a &#x27;hack&#x27; as discussed in the article and I will probably never use it. JSON should be either self explanatory or documented, I don&#x27;t see any reason why you would add this unnecessary clutter to these messages.<p>It is already hard to read as is and it&#x27;s making it worse to read and confusing, if some big service would start using this, you would have to know about this &#x27;hack&#x27; otherwise he would have to look up what the hell is going on.<p>Also, this is the same information for each call and thus redundant, makes your messages larger when an advantage of JSON is that it&#x27;s generally a small message.

This, to me, looks like an example of relying on a nondeterministic implementation. To my knowledge, the standard doesn&#x27;t prescribe that parsers take the second&#x2F;last of a duplicate key. As a result, this is relying on implementation-specific choices which can lead to a terrible upgrade process.<p>Switch to a different JSON parser, does it still work? probably. but I wouldn&#x27;t bet that much.<p>If I were implementing a JSON parser, might I throw an error on a duplicate key? maybe. Maybe I would just print a warning?<p>If I were every going to give someone advice it would be to never do this.

You should use standard JS comments and process them out. Douglas Crockford&#x27;s offical answer on comments, <a href="https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr" rel="nofollow">https:&#x2F;&#x2F;plus.google.com&#x2F;118095276221607585885&#x2F;posts&#x2F;RK8qyGVa...</a>. Essentially just process them out beforehand with something like jsmin, pretty straightforward.

This is a horrible hack. You should use JSON-LD [1] to describe the fields of your JSON. It&#x27;s a W3C standard!<p>Also, it&#x27;s <i>not</i> defined in the JSON standard in which order an implementation needs to parse the JSON fields&#x2F;keys. So you could end up with potentially wrong results!<p>1. <a href="http://json-ld.org/" rel="nofollow">http:&#x2F;&#x2F;json-ld.org&#x2F;</a>

This is a nice trick, but probably only should be used in systems where the set people touching the code is a limited, rarely-changing set of people and anything using the JSON is strictly going to treat the last defined value as the value to use. Dragons lurk elsewhere!

&gt; Believe it or not, it turns out JSON parsers work the same way<p><i>Please</i> don&#x27;t do this. There&#x27;s almost certainly some parsers out there currently that don&#x27;t work like this, and if not, there likely will be one day.

I do something else that is a lot more readable:<p><pre><code> { &quot;#&quot;: &quot;this is a comment for the next line&quot;, &quot;url&quot;: &quot;http:&#x2F;&#x2F;foo.bar&quot; } </code></pre> Simple.

if I ever saw this in a project, I would remove those comments in a heartbeat. The behavior here is specific to the json parser. JavaScript is not the entirety of programming.<p>It does break the json parser in the Go standard library, in a totally nonobvious way: <a href="http://play.golang.org/p/BsDd47vWna" rel="nofollow">http:&#x2F;&#x2F;play.golang.org&#x2F;p&#x2F;BsDd47vWna</a><p>I would be surprised if it doesn&#x27;t break many parsers, especially json parsers in static languages. If you want that sort of behavior, don&#x27;t use json.

This is a celebration of programmers&#x27; ability to generate unmaintainable code by exploiting implementation dependencies. People get <i>fired</i> for pulling this horseshit every day!

A common practice in config files is to comment out whole sections e.g. optional proxy server settings. This sort of multi-line comment is not addressed by this hack

Well, here we go: <a href="https://github.com/kgabis/parson/issues/7" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;kgabis&#x2F;parson&#x2F;issues&#x2F;7</a>

Don&#x27;t use them, there is no such thing. Make your comments first class citizens in the data.

Nice hack but fails JSHint.<p>[1] <a href="http://jshint.com/" rel="nofollow">http:&#x2F;&#x2F;jshint.com&#x2F;</a>

JSON has comments already. It just requires you to decide what the comment marker is.

I thought JSON is mainly for machine to machine consumption.. who reads comments?

This is a recipe for disaster.

Neat trick! Not sure I&#x27;d trust it, and might be confusing for anyone reading who didn&#x27;t know this.

That seems pretty fragile.