JSON parsers that can accept comments

either it's a data transfer format and comments should be stripped before transmission

or the comments are part of the data model

makes you have to think clearly whether the comments are just "notes to self" at authoring time, or something relevant to the consumer

OTOH of course there are plenty of 'greyer' cases

And Gruber wouldn’t give Jeff Atwood permission to call his variant <something> Markdown, or it seems anybody else, so we ended up with CommonMark, and GFM.

Json5 is good for JSON at rest, as others have mentioned already.

Because JSON originally did have comments, and people were putting pragmas into them, and so different parsers would act different depending on whether they understood them or not. Comments ended up being an anti-feature in JSON because people were abusing them.

Source:

> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't. […]

* https://web.archive.org/web/20190112173904/https://plus.goog...

I would call out portability instead, which is not dependent on the byte ordering or endianness issues of binary data formats.

sort of like: javascript is portable code, json is portable data.

But there are dangers there - look at how horribly comments get abused in code:

* doctests are nonsense, just write tests. (doctests like rusts that just validate example snippets are the closest thing to good I've seen so far, but still make me nervous).

* load bearing comments that code mangling/generation tools rely on (see a whole bunch of generated scripts in your linux systen - DO NOT EDIT BELOW THIS LINE)

* things like modelines in editors that affect how programs interact with the code

* things like html or xml comments that on parsing affect end user program logic.

Comments can be abused, and in something like JSON on the wire I can see systems which take additional info from the comments as part of the primary data input. Often a completely different format... and you end up with something like the front-matter on your markdown files as found in static site generators.

Point being, comments are not a purely benign addition.

That said, I don't like it as a config file read/written by humans.

The idea is that this forces better formats.

How well this works? Well, then I got an "x-comment" property or non-standard comments. Nonetheless. If people see the need to hack some extension in, they'll find a way.

Why did they bother making it text-only ASCII then ?

What no-comments saved us from was stuff like this in our data interchange:

    {  
        "count": 123 // bigint
        "price": 10.99 // @precision=2
        "date": "2024-08-12" // @format=YY-MM-dd
        "data": /* !transform(rot13) */ "uryyb" 
        "storage": 5 // Unit(TB)
    }

Frankly, VSCode shows that all this time people were complaining about no comments in JSON config and how hard it was to write config in JSON, they could have just written their apps to strip comments at read time.

So we do have the best of both worlds.

    - JS syntax compatibility (low cognitive overhead)
    - Decent balance between machine-readable and human-readable
    - High familiarity for developers (if they know JSON, which they likely do, they can work with JSON5 with near-0 learning curve)

Yet YAML, which is somewhat related to JSON, uses

    # This is a comment

const obj = JSON.parse(jsonText.replaceAll(/("(?:\\"|\\.|[^"])"|[^\/])|\/\/.|(\/)/g,"$1$2"));

The above should be multiline JSON safe and give you single-line comments to end-of-line, it matches first strings (and checks for escaped double-quotes and escapes to get them correctly) or all other characters except // sequences (outside of strings) and passes that straight through via group 1(anything outside of string not starting with /) or 2(single / even if it's outside of JSON spec), if a // sequence is found it's not passed through and disappears.

Yes, regexps can be abused. This one should be fine though but only use it for config files you control :), use as CC0 and keep an keen eye if translating to another language since escapes will differ if the regexp goes into a string instead of a regexp literal like in JS.

As has been pointed out multiple times in the thread so far, a random string that is ignored by the receiver is semantically equivalent to a comment, and people totally stuff random crap into strings to extend the data format in sometimes-horrifying ways. Banning comments doesn't stop us from abusing strings, it just means we don't have a good way to indicate that a part of the file should be ignored by the parser because it's not actually data.

There are parsers which allow for comments if one wants, so if someone wants to engineer an insane system no one is stopping them, provided they can ensure the parser on the other end of it.

This is a data format meant to be readable by humans. As such, it's natural to want to support things like configuration via end-user editing values in the text as a use case. Data is occasionally going to need comments to explain valid options or add context for people to edit. This is a reasonable thing to have.

   "like this"

   // Like this

We already have XML. Stop trying to make JSON another XML.

I'm now knee-deep in a gig that uses all sorts of w3c standards, which enforce json-ld, json-schema, json-whatnots and so on. It's a terrible mess of unreadable complexity that has LONG been solved in XML. Decades ago!

I keep thinking that if you need one of those "fancy" features, why not just use XML? Why bolt them onto JSON, a format that was deliberately (?) set up to not have all these features?

I think that if you don't need these features: by all means, use JSON. It's simpler, cleaner, easier. But that it's only simpler, cleaner, easier because it's not XML. And that all these attempts at making it XML, end up with a JSON that's harder, more complex and often messier than the XML that we had for decades and that JSON tried to "solve" by being simpler. So it's one step forward, two steps back.

I don’t think anyone proposes switching to YAML for your API endpoints

    {"data": 
    #include "/home/myservice/secrets.json"
    }

XML preserved whitespace, too! I dislike XML intensely, but there was a method to its madness. There’s a method to JSON, too: simplicity and usability.

You start adding things to JSON, you lose that.

It’s unfortunate how many APIs are documented with a single json example, but annotating them with comments (and maybe types?) would help immensely.

And they don't solve the core issue of async control flow that async/await solves, so it's not an alternative to async/await much less a superior one.

A classic example is when you want to conditionally do something asynchronously like B() in this case.

    function process(id, callback) {
      A(id, (result) => {
        if (result === 3) {
          B(() => {
            C(result, callback);
          });
        } else {
          C(result, callback);
        }
      });
    }

    async function process(id) {
      const result = await A(id);
      if (result === 3) {
        await B();
      }
      return C(result);
    }