JSON is a data interchange format, you dont want comments in data that is interchanged. HTTP headers dont have comments. Put your comments in your doc explaining your json data format... which sucks for json, cause json doesnt have a formal schema language, ok json-schema, but thats sucky.

It is easy to create a json-schema by conversion in current json. How about { scheme: {}, instance: {} } ?

Not really... just add a "comment" key and then ignore it when processing.

That's pretty ugly in practice.

A better solution is to use YAML for things like configuration files. It's more pleasant for a human than JSON would be even if it supported comments, and there are nice parsing libraries available for every popular language.

That's an ugly workaround, not a solution. It helps breed half-baked "solutions" like the "pipe through jsmin" Crockford himself suggests.

Ultimately, it makes JSON unsuitable for configuration files (there are other reasons for that, to be fair, like over-verboseness)

Not necessarily. If you're naming your keys nicely, and using an easily-understandable structure, for simple config files, you shouldn't really need comments.

"simple config files" implies an optimist. Good for you, sir.

Yes, that solution OBVIOUSLY removes the need to spend an extra minute adding comments to the spec.

Also, I hope, trailing commas and binary types.

Shoving binary into JSON is rather silly--base 64 encode it, or consider using a binary format better suited to your need.

As for adding comments to the spec--again, the idea is to prevent shadow information showing up that isn't obvious to a conformant parser.

If you give people the ability to smuggle data in comments, that's exactly what they'll do. At least this way people know that what they're doing isn't "to spec" and that their sneaky parsers are not following the rules.

I mean, JSON itself is rather silly in that it's a horrible serialization language. Its main boon is its C-style syntax, which is why it's so readable to all of us who read similar syntaxes all day. Even just a syntactical change noting which strings were base64 encoded would be nice.

It takes a minute to add anything to a spec. It increases the cost of implementing the spec a lot more than a minute though.

That's such a terrible response. "Use JSON, but then use another parser first." Sorta defeats the purpose.

The reasoning is also incredibly short-sighted.

That's the syntax equivalent of removing guardrails from a dangerous mountain pass to scare drivers into slowing down.

This is probably going to sound like asking someone to catch sunlight in a teacup, but wouldn't it have been more productive to stress the importance of syntax adherence and consistency rather than remove it altogether? There's really nothing stopping someone from abusing the rest of JSON for silly things so leaving comments out seems a bit redundant.

That's pretty laughable. What exactly prevents people from putting parsing directives in a special object key or list entry at the beginning of the file?

that would be valid JSON, so it's not a problem. Standard tools can still parse it and reliably turn it into native objects. The same is not at all true when comments exist. People will start putting /* @annotations */ that can only be ready by certain tools which breaks the whole point of JSON - it's a data interchange format.

That sounds smart on first pass, but doesn't really help. If people were going to use /* @annotations / and instead put them in keys, either way, the other side gets a document that isn't the one intended*. So regardless if it parses or not, it doesn't really help.

Let's assume JSON supports comments, and `foo` is a JSON document with comments, what should happen here?

    JSON.stringify(JSON.parse(foo))

Presumably you'd say that it should return a plain JSON object without comments, right? However, with the current implementation this will return a JSON document that is identical to the input, modulo whitespace. This makes it easy to write tools that can, for example, increment the version number in a nodejs package.json file programatically. Doing this in a world where comments exist becomes extremely awkward or at the very least annoying, because either you have to write your own JSON parser that preserves comments, or you have to simply discard the comments when you're writing the file.

If you go with the first option, you'll inevitably run into a scenario where you have a document like this contrived example:

    {
      // this is the first ever version!
      "version": "1.0.0"
    }

And your tool goes off and increments the version number, so you end up with:

    {
      // this is the first ever version!
      "version": "2.0.0"
    }

and now your comment is a lie.

If you go with the second option, you destroy all comments whenever you write data back to the file, so they can be deemed temporary at best.

What benefit do you actually get from having comments in either scenario?

Comments are appropriate in JSON which is written by humans. If it's written by a machine, of course comments are irrelevant. Situations where you need to automatically make changes to JSON which is primarily maintained by humans are a bit of a special case that I don't think is worth optimizing for; if you feel putting comments in object fields is a better choice in this situation, you can still do that even if comments are supported.

Supporting comments makes JSON more convenient to use in more situations, and it doesn't prevent you from doing anything you can do now.

At least you can inspect the document you got with normal tools. Not so if you include comments.

And this may even encourage people into separating the data payload from the metadata, who knows?

That sounds like a "no true scotsman" argument. If comments were added to the spec then normal tools would support them just fine.

Besides, JSON has already become a common format for config files. Config files that don't allow comments are truly a step backward.

> That sounds like a "no true scotsman" argument.

I don't see how this is a "no true scotsman". Maybe a non-true "no true scotsman"?

> If comments were added to the spec then normal tools would support them just fine.

Plain comments, sure. Comments with custom annotations in them, not so much.

> Besides, JSON has already become a common format for config files. Config files that don't allow comments are truly a step backward.

Maybe this wasn't such a good idea in the first place?

How not? Comments with annotations would be ignored, just like a special annotation key. Either way, you'd end up with a parsed document that isn't what the original creator intended.

If you had /* @annotations */ and JSON allowed comments, it would still be valid JSON to do so. Using "special" keys is identical then - both require special parsers / post-processors to properly reconstruct the data.