Hi! I have a // comment on json

[hackedpassword]

I've only been actively using json for the last year, full disclosure there. My current primary use (not only) is modding for the community-built game Unciv.

tldr; version is that non-automated construction and maintenance of json files greatly benefits from commenting, just as python code or any scripted/coded language, or modern config file. I will show (subjective) evidence of this here with json configs for my actively in-development mod (that could be in any state when you read this!).

As I have been made aware, json generally does not support commenting as a schema standard. Over in Unciv, the engine ignores // and /* */ comments placed in json files. When it was clear that this was an unusual allowance, I then paid attention to the actual necessity of json commenting.

Example 1: https://github.com/hackedpassword/Z2/blob/main/jsons/Terrains.json
Here, generally, you will find a flourishing environment of notes/comments/story elements even, for myself, readers, other modders, or guiding support requests.

• Without these comments, intent is sterilized
• Looking elsewhere to correlate intent increases documentation overhead substantially
• Comments are updated and pruned as-needed while development continues

Example 2:
https://github.com/hackedpassword/Z2/blob/main/jsons/Units.json#L488

In this example, there is a significant amount of commenting for the game unit. Is it prettified? Certainly not as you see, but at this stage getting the comments in far outweigh aesthetics. As time goes on, I iron out what was prototyped on-the-fly construction. This is not an example fit for production environments! In such an environment, there would most assuredly be more attention to form. Python, for example, uses code and comment nomenclature that essentially blends to make it most readable. What if the next version stated comments were no longer allowed, use companion documentation instead? Unthinkable!

In json, character delimitation substitutes bulky and rigid tabs and quoted elements as assumptions of intent. Sure, in the example there is a block (called civopedia) that takes much of the json commenting and story elements turning it into in-game documentation formatted for players. Individual elements would have no reasoning, no life, no justification for their existence or any value of other presumed associate key-pairs being plainly stated as cold config. Scroll much further down and casually determine why any unit has whatever stat, why the unit designer felt this vs that. Like a developer knowing their current project, better grab some history books to postulate those unit values (those are unmodded game defaults fyi).

Decoding a dump of Hangouts chat spanning numerous years, also for example, is very challenging. Without reference specs, it's all assumptions. In this case, the json is automatically generated, but wouldn't even that benefit from block comments? Is it absolutely critical to instead produce another key-pair of data to be processed rather than cost-saving ignored?

I don't know, and maybe there is very good reason for why json is built without commenting as part of the schema. As I move forward on my mod, and other projects, like an Android Studio project with lots of config files, it seems unthinkable in modern times that commenting in a config file is frowned upon or simply disallowed.

Thank you for reading :)

[awwright]

You're discussing the syntax of JSON, which is a different thing than JSON Schema: JSON Schema lets you define a subset of JSON documents, but alas, it does not define JSON itself, you cannot use it to specify a superset of documents (e.g. JSON as defined, plus comments).

You can leave your remarks about the syntax of JSON with the authorities who defined it (RFC 8259, ISO/IEC 21778:2017, and maybe one other), but from my participation, it's unlikely the syntax is changing for any reason: partly because it's jointly defined by multiple standards organizations and they'd all have to get on board, but mostly because it would just make more sense to define a new media type entirely. The examples you've posted aren't strictly speaking JSON, but a superset of JSON that has a direct mapping to JSON—and such a media type deserves its own name. Along these lines, in my opinion, JSON is better suited for bulk data transfer of native data structures, and you should look to other file formats for using configuration: Ini, TOML, YAML, XML, etc.

You should google around for the reasons JSON was defined without comments, even hough I'm not sure you'll be persuaded any more than I was. Sometimes I think it may be for the best, comments do add some amount of complexity, and even with comments, you could still design a better format for the needs of configuration files (instead of bulk data transfer).