JSON normally does not support that. JSON5 would be an alternative solution.

Personally I don't think this is a good idea in general.

JSON normally does not support that. JSON5 would be an alternative solution.

I've looked into JSON5 for package.json and found this discusion discussing: package.yml and package.js. An example of package.yaml and the package.yaml issue. Also hjson is discussed. I realise I've opened the can of worms again, however I also realise I'm not alone requesting comments in package.json.

I will look into json5 and see if I can make something work. Currently I have no new arguments for this issue/change-request.

Can you elaborate and motivate your thoughts why you think it is not a good idea to support comments?

JSON already supports comments:

{
  "foo": "the foo field is for storing valuable information",
  "foo": "the real value of foo"
}

JSON already supports comments:

Not native / real comments but a workaround which is also shown in the blogpost which the reporter linked afaik.

The blog post talks about making parallel keys in a "comments" sub-object. I'm saying that JSON natively allows duplicate keys, so as long as the last one is the actual value, you can use the duplicates for anything you like, including comments.

Your example would throw linting errors in some cases (duplicate key) and could throw parsing errors in a few cases probably.

Douglas Crockford did not add any support for comments in the original specs (only specific JS types) and does not intend to.

As far as I understand the request is very specific (annotation @comment)- or special field.

And how it's displayed in IDEs (differently).

Anything that errors on duplicate keys in JSON is violating the JSON spec (short of a linter rule that could be disabled, of course). Crockford has not influenced the JSON spec in many years, and TC39 (which does) certainly has no intention of changing it :-)

True. But I would suggest adding HJSON or JSON5 support as this makes more sense (readability, ecosystem support and features) than such a "workaround". Just my opinion.

Can you elaborate and motivate your thoughts why you think it is not a good idea to support comments?

• if this is done and agreed in this context, I can follow through and talk to IDE's repos

That would be a huge effort.

Vv

Douglas Crockford did not add any support for comments in the original specs (only specific JS types) and does not intend to.

I don't think that's accurate. He said:

A JSON encoder MUST NOT output comments. A JSON decoder MAY accept and ignore comments.

Comments were initially allowed, and were only removed to prevent people from adding parsing directives. There's no reason that decoders can't allow and ignore them, and some do.

npm init shouldn't _add_ any comments, but npm install etc don't need to _remove_ ones that a developer has intentionally added either.

There's lots of potential workarounds, but they all suck in various ways. Developers are always going to want to add comments, and fighting that causes a lot of wasted time and frustration.

Of course, if supporting JSON5 is a more practical solution, that'd be just as good.

I wish we had this for Christmas 2020.

Honestly, whether it's JSON 5 or another standard, it'd be better than what we got at the moment.
Comments are so important in anything non-trivial. I don't understand why JSON5 isn't compatible with package.json file already, it's not like this file is going to be fetched from a browser or something alike. It's only used by node.js and it would be possible to use a JSON5 loader for this particular file in a backward-compatible way.

The first step would have to be adding native support in node itself for loading another format, so that every tool in the ecosystem could switch to using it to read package.json. Once all of them switched, then it'd be reasonable to suggest npm supporting that format for package manifests.