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.
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?
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.
I don't see anything intrinsically wrong with doctests. I also can't see a better way to do "load bearing comments," and I'm not eager to go back to "Step 2: Edit your .bashrc to include foo."
these are mostly a warning sign for humans, to be read as "if you need to modify the script below this line, a) you gotta be knowing what you're doing, we are not held liable for support if you change stuff around there b) please contact us to make sure we didn't miss a legitimate need or c) you're trying to do something in a bad way and there's better ways to do so".
Why are doctests not tests?
> doctests like rusts that just validate example snippets are the closest thing to good I've seen so far
Rust's doctests don't seem to be fundamentally different from Python doctests, which is the language I've seen most commonly make use of doctests.
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.
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...
> Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
Doesn't seems he is that against the idea
That said, I don't like it as a config file read/written by humans.
Also languages with some progrommatic capabilities like cue, dhall, jsonnet, nickel etc.
Non of them are perfect, and some are less suitable for certain use cases than others. But IMO pretty much all of them are better for human editing than json, and in many cases yaml.
- doesn't require to quote everything
- has lists/dictionaries
- uses indentation and new lines instead of commas and brackets
- doesn't have 1000 unnecessary features like YAML
Also, you don't need all types from JSON.
JSON has a very minimal set of types and I regularly use all of them. I guess you could argue that integers and numbers could be combined, but I think that's it.
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.
Why did they bother making it text-only ASCII then ?
JSON is notable for making UTF-8 encoding a hard requirement.
…which was pretty ballsy back in the mid-2000s. We were still fighting with Shift-JIS and Windows-1252. Excel didn’t add proper support for UTF-8 until depressingly recently.
I don’t remember when I started pushing for utf-8 everywhere but it was “early” by most people’s standards, so I know what you mean.
And one of the things that makes me dislike MySQL is that they have a field type called utf-8 that isn’t. And they didn’t fix it, they introduced a new type instead. So that footgun was still there for all to trigger. So mad.
> Previous specifications of JSON have not required the use of UTF-8 when transmitting JSON text. However, the vast majority of JSON-based software implementations have chosen to use the UTF-8 encoding, to the extent that it is the only encoding that achieves interoperability.
I like to solve problems - or at least bringing them to me doesn’t result in a loss of status for either party. People notice this about me and bring me problems. Someone recently described to people what is essentially my process: the likelihood of the cause divided by the difficulty of verification. Partially sort and just start checking off assumptions.
A lot of cheap but low probability options get shuffled higher, and just sending the wrong data is a common enough problem, especially with caching. And if it’s nearly free to look at the payload, it’ll get checked. If it isn’t people will try everything else to avoid it.
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.
1. comments are metadata (specifically Human/LLM-readable metadata vs machine-readable metadata)
2. general-purpose data formats should support metadata
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.
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.