Why JSON keeps data separate from instructions

JSON was designed as a format for exchanging structured data: objects, arrays, strings, numbers, and a few other basic values. A comment may look like harmless prose to a person, but software still has to decide what to do with it. One program might discard it; another might preserve it or treat it as a directive—a note that changes how data should be read.

That difference can make the same file behave differently across tools. JSON’s creator, Douglas Crockford, said he left comments out after seeing developers use them to carry parsing directives. Allowing that practice, he argued, would undermine interoperability: the ability of separate programs to exchange the same data and interpret it consistently.

The tradeoff for people editing JSON

Without comments, a JSON file cannot include ordinary explanatory notes alongside its data. That can be inconvenient in settings such as configuration files, where a person may want to explain why a value is present. But strict syntax gives each parser a clearer job: read the data, rather than guess whether extra text is disposable or meaningful.

The practical consequence is simple: JSON favors predictable exchange over built-in annotation. When an explanation matters, it needs to live outside the JSON data—or in a format designed to support comments.