[model-15-DAV]

JSON as a data-format should not have comments. JSON as a file-format should allow comments. The problem is this conflation between the two.

[lolinder]

But they're not two different formats—they're two different jobs being done by the same format.

JSON as currently spec'd is honestly quite bad at both jobs, but the most rational defense of its use as a data format is that it's (mostly) human readable. Given that that's its main value proposition, what exactly is the reason for saying that JSON-as-data-format should not have comments? What do we lose if we allow them?

[throw0101d]

> Given that that's its main value proposition, what exactly is the reason for saying that JSON-as-data-format should not have comments? What do we lose if we allow them?

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...

[m463]

> but the most rational defense of its use as a data format is that it's (mostly) human readable

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.

[sophacles]

I think json should allow comments.

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.

[Kwpolska]

The problem is using JSON as a file format in the first place. It’s not designed for humans to edit. (Then again, it’s better than the Norway-sceptic YAML.)

[peterashford]

I disagree. At least in an ought vs is sense: it's entirely the kind of format that I would create as an editable format. As witnessed by the fact that my workmates and I did create very nearly JSON previously as a file format in the 90s (but for C code programs)

[Jare]

What example(s) of file format would you say are designed for humans to edit and still represent the kind of structured contents that json does?

[Cthulhu_]

But it happens. 'npm install' will edit your json file, but so can I.

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

[martin-adams]

Can I confirm that the reason it's not preferred to have comments in data-formats is because it's to be machine read only and as such should be as efficient as possible and not contain information that wont be used?

Seeing as I can only see the use case as a file format to be read/written by humans in the loop, then maybe the conversation should be about compiling the file format to a data format for compatibility outside of the user tooling.

[johannes1234321]

The argument is that comments are often used as an escape hatch from specified formats to carry further instructions. So you got a properly specified format and then want to do vendor&extensions but not break other implementations ... just make your extensions a comment. Then other parsers ignore it and you can do your thing.

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.

[ur-whale]

> is because it's to be machine read only

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

[burnished]

I think in the JSON case its because you can't have true comments, any comments are intrinsically part of the data structure, and you invite problems by including irrelevant information

[nivertech]

Thinking from the first principles:

1. comments are metadata (specifically Human/LLM-readable metadata vs machine-readable metadata)

2. general-purpose data formats should support metadata

[jimmaswell]

Disallow comments and now you just have {"comment": "the quick brown fox.."}, the worst of both worlds.

[hombre_fatal]

That's a harmless example and a tiny price to pay.

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)
    }

And who knows what deeper layers of hell we avoided.

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.

[codedokode]

> JSON as a file-format should allow comments.

JSON is awful for writing manually because it requires typing too many quotes, commas etc. I think JSON is meant to be machine-generated and machine-read and therefore doesn't need any comments.

[leptons]

You're a programmer and you're against writing quotes and commas? You must really hate coding. I've never found JSON to be too much typing.

[xnorswap]

If you're entirely machine writing and reading, but still want to be human-legible, then XML does a much better job while also allowing for schema.

[pjc50]

The only reason it became popular is that conflation!

[Someone]

I think it’s more “it would be nice if JSON intended to be read or written by humans allowed comments”.