Theory
One helpful note, one dead feed
A conscientious teammate opens events.json and, wanting to help future readers, adds:
// seat counts updated every evening by Priya
He saves. FestConnect's schedule page goes blank. The console reports JSON.parse throwing a SyntaxError at line 1.
In JavaScript, that comment is perfectly legal. In JSON, there is no such thing as a comment, and this lesson is the story of why that is a decision, not a gap.
Practical
See the rejection yourself (run it)
// This string contains JSON with a comment inside it:
const annotated = `{
// updated every evening by Priya
"name": "Garba Night",
"seats": 350
}`;
try {
JSON.parse(annotated);
} catch (e) {
console.log("Parser said: " + e.message); // SyntaxError
}
// The same data, uncommented, parses fine:
const clean = '{ "name": "Garba Night", "seats": 350 }';
console.log(JSON.parse(clean).name);
This example runs in Gri-Learn on the web, where you can edit it and see the output.
Theory
Absent by design
JSON's creator, Douglas Crockford, removed comments from the format deliberately, and his stated reasons are exam-friendly:
- Purity: JSON is a minimal DATA interchange standard; a data file should carry data, nothing else
- Abuse prevention: in early use, he observed comments being turned into parsing directives (instructions to specific parsers), which silently broke the promise that any JSON means the same everywhere
Simplicity is also what keeps every language's JSON parser small and identical in behaviour. The grammar stayed closed: no //, no /* */, nowhere.
Theory
What teams do instead
Real projects still need to explain their data. The 3 honest routes:
- Self-documenting names:
"seatsUpdatedDaily": trueexplains itself; good key names are the first documentation - External docs: the API documentation or a schema file describes every field: the professional standard
- A data field as a note:
"_comment": "seats updated evenings": legal, visible... and NOT a real comment: it travels with every copy, costs bytes, and consuming code must ignore it. Use sparingly, if at all
Quiz
What happens when JSON.parse meets a file containing // a note above valid data?
- The comment is skipped and the data parses normally
- It throws a SyntaxError: standard JSON has no comment syntax at all
- The comment is parsed into a special _comment property
- Only /* */ block comments are allowed; // line comments fail
Show the answer
It throws a SyntaxError: standard JSON has no comment syntax at all
The grammar simply has no production for comments, so the parser fails at the first slash: the teammate's blank-page bug from the hook. Option A describes JavaScript's own tolerance, the exact habit that plants this landmine. Option C inverts reality: _comment is a manual CONVENTION some teams adopt, never something parsers create. Option D invents a half-permission; both comment styles are equally illegal. Related exam row: XML DOES have real comments (<!-- -->), one of its genuine advantages in the Unit 3 comparison.
Think first
But VS Code's settings.json has comments...
You have probably SEEN comments working in a .json file: VS Code's settings, some config files. Before tapping: reconcile that sighting with everything this lesson claims.
Show the answer
Those files are not standard JSON: they are JSONC (JSON with Comments) or similar supersets like JSON5, which specific TOOLS choose to accept for human-edited configs. The file extension stayed .json; the format quietly did not. The boundary to hold: inside one tool's config, the tool makes the rules; in DATA INTERCHANGE (APIs, events.json, anything another program fetches), only standard JSON is safe, and comments will break real consumers. Exam sentence: supersets like JSONC allow comments, but standard JSON does not, and interchange must assume the standard.
Watch out
Where this bites in practice
Hand-editing live data files: the helpful-note reflex is strongest exactly where it is most fatal: shared .json feeds.
Copying config habits into APIs: a JSONC habit from tool configs breaks the moment a strict parser (which is all of them) meets it.
The _comment field in big data: 10000 records each carrying "_comment": "..." is documentation paid for in bandwidth, per request, forever.
Theory
Unit 3 closes: JSON is fully yours
You can now define JSON, argue it against XML, write objects with correctly typed strings and numbers, wield all 5 array shapes, and explain the one thing it refuses to contain. events.json is complete and documented the honest way (good names, notes kept outside). Unit 4 finally moves it: AJAX and the XMLHttpRequest, where the browser fetches this file from a server WITHOUT reloading the page, and everything since Unit 1 clicks together.
Summary
Key takeaways
- Standard JSON has NO comments: // and / / make JSON.parse throw a SyntaxError.
- The absence is Crockford's design: purity of data interchange, and preventing comment-abuse as parser directives.
- Document instead via self-explaining key names and external docs; "_comment" data fields are a legal but costly convention.
- JSONC/JSON5 supersets (VS Code configs) allow comments but are NOT standard JSON: never in APIs.
- XML has real comments; JSON does not: a standing comparison row.
- Data files carry data; explanations live in documentation.
- Memory hook: JSON carries facts, never footnotes.