JSON Doesn't Support Comments — On Purpose
Published 2026-09-14
A deliberate omission, not an oversight
If you've ever tried to add a helpful // note to a JSON config file and gotten a parse error, you've run into one of JSON's most debated design decisions. Douglas Crockford, who popularized and specified JSON in the early 2000s, has explained publicly that comments were left out on purpose, not forgotten.
The reasoning behind it
Crockford's stated reason is that JSON was designed as a strict, minimal data-interchange format — meant for machines to parse quickly and unambiguously — rather than a configuration language meant for humans to annotate. He's noted that comments are often abused by parsers as a place to embed processing directives, which would undermine JSON's goal of being a small, universally consistent format that behaves identically everywhere, with no parser-specific extensions creeping in.
How people work around it anyway
- A "comment" field: some tools just add a regular JSON key like
"_comment": "explanation here", which parses fine as ordinary data. - JSON5 and JSONC: extended, JSON-compatible formats that explicitly add comment support, used by tools like VS Code for its own settings files — but note these aren't standard JSON, and a strict JSON parser will reject them.
- Switching to YAML: for configuration files specifically (as opposed to API data interchange, where JSON remains dominant), many projects use YAML instead, partly because it natively supports comments.
Why this still matters today
JSON's strictness is exactly what makes it so reliably interoperable — a JSON parser in any programming language handles standard JSON identically, with no ambiguity about how comments should be stripped or interpreted. That predictability is a large part of why JSON became the dominant format for web APIs, even though it means config files sometimes need a separate "notes" field instead of an inline comment.
Format and validate your own JSON
Our JSON Formatter uses your browser's native, spec-compliant JSON parser, so if your JSON has a comment (or any other syntax issue), it'll tell you exactly why it's invalid rather than silently trying to guess your intent.