Take the 2-minute tour ×

Can I comment a JSON file? If so, how?

share|improve this question
@StingyJack -- I have a key algorithm for my product that must be implemented in three separate languages: Javascript, Objective-C, and Python. A lot of this algorithm can be abstracted away into configuration. And what configuration syntax turns out to be easiest for me to consume in all three cases? JSON, of course. But I'd love to be able to document and comment directly in the configuration files. I realize JSON was originally intended strictly for interchange... but like all things, its use cases grow... –  Dave Peck Aug 3 '09 at 23:57
Note that where your JSON ends up going is a big part of whether you can or can't comment it. If it's for configuration, then it's likely that you have control over all the parsers that will read it. Since a JSON parser is an extremely simple creature, extending one to allow comments should be very simple. Alternatively, you could use a YAML parser, and YAML does allow comments. (In some ways YAML is a lot more flexible for configuration purposes anyway.) –  Pointy Jun 30 '10 at 14:08
Y U NO allow comments –  Redsandro Jun 20 '13 at 11:44
who is StingyJack? –  fonzo-highway Feb 19 at 23:17

31 Answers 31

up vote 1067 down vote accepted

I don't believe you can have an actual comment. The JSON should all be data, and if you include a comment, then it will be data too.

You could have a designated data element called "_comment" (or something) that would be ignored by apps that use the json data.

You would probably be better having the comment in the processes that generate/receive the json, as they are supposed to know what the json data will be in advance, or at least the structure of it.

But if you decided to...

   "glossary": {
      "title": "example glossary",
      "GlossDiv": {
         "title": "S",
         "GlossList": {
            "GlossEntry": {
               "ID": "SGML",
               "SortAs": "SGML",
               "GlossTerm": "Standard Generalized Markup Language",
               "Acronym": "SGML",
               "Abbrev": "ISO 8879:1986",
               "GlossDef": {
               "GlossSee": "markup"
share|improve this answer
@Alex - are you sure that's valid JSON? I don't see anywhere in the docs where it allows for comments, c-block or otherwise... –  Eli Jan 5 '11 at 23:40
+1 all around. While the program should know how to deal with the json, sometimes json files are edited by hand, and comments are nice :) –  Olie Jul 28 '11 at 20:10

No, comments in JSON are not allowed. This answer is based on:

share|improve this answer
Meta-comment: this are the kind of answers I like most. Short, to the point and undeniable. Keep that attitude going! –  silviot Jun 7 '12 at 11:01
... and not specific enough –  Full Decent Apr 24 at 16:48
@FullDecent/: "No" is a perfectly specific answer to a 6 word yes or no question. The fact that details are provided makes it far more specific than needed. The OP did not also ask "If not, why not?" or "If not, is there a common work-around? If so, what?" –  lilbyrdie Sep 24 at 13:09







share|improve this answer
Just what I was looking for! Google V8 used to ignore comments, now it doesn't... –  hplbsh Sep 21 '10 at 17:44
In my opinion, this is a great approach, and very welcome indeed. What happens, @MarnenLaibow-Koser, when you need to talk about the data-packet interchange format? I need a way to present a JSON packet to someone, and have it annotated for understanding -- supporting commenting in JSON itself is a very convenient and powerful way to accomplish that goal. Using JSON itself to demonstrate JSON means I can apply JSON tooling to my examples! –  Viktor Haag Mar 6 '12 at 16:01

Comments were removed from JSON by design.



Source: Public statement by Douglas Crockford on G+

share|improve this answer
That is the lamest reason for making an important decision, ever! –  Chris Nash Oct 12 '12 at 20:42
@ChrisNash let's just say that Crockford is a man of strong opinions ;) –  Artur Czajka Oct 14 '12 at 8:38
I thought JSON was to supposed to be more human readable than, say, XML? Comments are for readability. –  Chris Nash Oct 14 '12 at 13:00





It appears that when declaring an object literal you can specify two values with the same key, and the last one takes precedence. Believe it or not, it turns out JSON parsers work the same way. So we can use this to create comments in the source JSON that will not be present in parsed object representation.

({a: 1, a: 2});
// => Object {a: 2}
// => 1


  "api_host" : "hodorhodor.com",

  "retry_interval" : 10,

  "auth_token" : "5ad0eb93697215bc0d48a7b69aa6fb8b",

  "favorite_numbers": [19, 13, 53]

The above code is valid JSON. If you parse it you'll get an object like this:

    "api_host": "hodorhodor.com",
    "retry_interval": 10,
    "auth_token": "5ad0eb93697215bc0d48a7b69aa6fb8b",
    "favorite_numbers": [19,13,53]


Happy hacking!

share|improve this answer

You can't. At least that's my experience from quick glance to json.org

Json has its syntax visualized on that page. No note from comments.

share|improve this answer


share|improve this answer
Not an answer to the question asked. –  NateS Mar 28 at 10:35

You should write a JSON schema instead. JSON schema is currently a proposed internet draft specification. Besides documentation, the schema can also be used for validating your json data.


"description":"A person",
    "age" : 

You can provide documentation by using the description schema attribute.

share|improve this answer

Sorry, We cant use comments in JSON... See the syntax diagram for JSON in JSON.org

Douglas Crockford says "why he removed comment in json and providing alternate way to do that"



share|improve this answer

If your text file, which is a JSON string, is going to be read by some program, how difficult would it be to strip out either c or c++ style comments before using it? Answer: It would be a one liner. If you do that then JSON files could be used as configuration files.

share|improve this answer




Cf: Douglas Crockford, author of JSON spec.

share|improve this answer










share|improve this answer

Just encountering this for config files. I don't want to use XML (verbose, graphically, ugly, hard to read), or "ini" format (no hierarchy no real standard etc) or java "Properties" format ( like .ini )

JSON can do all they can do but way less verbose and more human readable - and parsers are easy and ubiquitous in many languanges. It's just a tree of data. But out of band comments are a necessity often to document "default" configurations and the like. Configs are never to be "full documents" but trees of saved data that can be human readable when needed.


share|improve this answer

The Dojo javascript toolkit (at least as of version 1.4), allows you to include comments in your JSON. The comments can be of /* */ format. Dojo consumes the JSON via the dojo.xhrGet() call.

Other javascript toolkits may work similarly. If anybody finds one, please edit this response and include it.


share|improve this answer

Comments are not an official standard. Although some parsers support c-style comments. One that I use is JsonCpp. In the examples there is this one:

// Configuration options
    // Default encoding for text
    "encoding" : "UTF-8",

    // Plug-ins loaded at start-up
    "plug-ins" : [

    // Tab indent size


share|improve this answer

Depends on your json library, Json.net supports javascript style comments /* commment */.
See another SO question.

share|improve this answer



Then you can have comments like this:

  key: "value" // comment

But in general (as answered before) the spec does not allow comments.

share|improve this answer


If you follow the link, you will see

/* May 2006 */

Since I had a similar file in my local folder, there were no issues with the Same-origin policy, so I decided to use pure JSON... and, of course, $.getJSON was failing silently because of the comments. Eventually I just sent a manual HTTP request to the address above and realized that the content-type was text/javascript since, well, JSONP returns pure Javascript. In this case comments are allowed. But my application returned content-type application/json, so I had to remove the comments.

share|improve this answer

I wrote an Hjson parser after facing a similar problem.

Hjson allows you to write human readable JSON as

  # look, no quotes or commas!
  foo: Hello World!
  bar: Hello Hjson!

  # don't bother with escapes
  html: <div class="hello">world</div>
  # also good to copy & paste paths in configuration files on windows
  path: c:\program files\etc

instead of:

  "foo": "Hello World!",
  "bar": "Hello Hjson!",
  "html": "<div class=\"hello\">world</div>",
  "path": "c:\\program files\\etc"

For JavaScript:

For C#:


CLI Hjson - JSON converter:

If you need a parser in another language you should be able to modify an existing JSON parser because the syntax is very close.

@comments: There seems to be a misunderstanding about the goal of Hjson - in no way should it replace JSON as a protocol. Only use it for configuration files or debug dumps (when the machine is communicating with a human).

share|improve this answer
This is not json –  Full Decent Jun 10 at 15:56
Downvoted. Inventing an alternate scheme that's close to (yet completely incompatible with) a well-defined standard is a mark of a terrible developer. The fact that you chose to include 'json' in the name just makes it worse. –  adelphus Jun 12 at 14:16




Have a look at the JSON website for more detail.

share|improve this answer


  "param" : "This is the comment place",
  "param" : "This is parameter place",

So JSON will understand this as:

  "param" : "This is parameter place",


share|improve this answer
This method may cause some troubles if anybody will loop through the object. On the first iteration the program will have no information that the entry is a comment. –  Tomas Feb 12 at 20:24
RFC says: "The names within an object SHOULD be unique". See this error reported at: stackoverflow.com/questions/4912386/… –  Full Decent Jun 10 at 15:59

What I do to cut a Json into parts is adding "dummy comment" lines :



"data1"             : "value1",
"data2"             : "value2",


"data4"             : "value3",
"data3"             : "value4"

share|improve this answer

If you are using Newtonsoft.Json library with ASP.Net to read/deserialize you can use comments in the json content

//"name": "string"

//"id": int


/* This is a

comment example */

PS: single line comments only supported with 6+ versions of Newtonsoft Json

Additional Note for People Who Can't Think Out of The Box: I use JSON format for basic settings in an ASP.Net web application I made. I read the file, convert it into the settings object with Newtonsoft library and use when necessary.

I prefer writing comments about each individual setting in the JSON file itself and I really don't care, integrity of JSON format as long as the library I use ok with it.

I think this is an 'easy to use/understand' way than creating a separate 'settings.README' file and explaining the settings in it.

If you have a problem with this kind of usage; sorry, the genie is out of the lamp. People would find other usages for JSON format and there is nothing you can do about it.

share|improve this answer

Sigh. Why not just add fields, e.g.

    "note1" : "This demonstrates the provision of annotations within a JSON file",
    "field1" : 12,
    "field2" : "some text",

    "note2" : "Add more annotations as necessary"

Just make sure your "notex" names don't conflict with any real fields.

share|improve this answer
Just make sure your "notex" names don't conflict with any real fields. is the problem. This is not an arbitrary solution. –  Full Decent May 14 at 14:42

The author of JSON wants us to include comments in the JSON, but strip them out before parsing them (see link provided by Michael Burr.) If JSON should have comments, why not standardize them, and let the JSON parser do the job? I don't agree with the logic there, but, alas, that's the standard. Using YAML solution as suggested by others is good, but requires library dependency.




Another way to achieve JSON parsing, stripping of comments, and no extra library, is to evaluate the JSON in a JS interpreter. The caveat with that approach, of course, is that you would only want to evaluate untainted data (no untrusted user-input.) Here is an example of this approach in node.js -- another caveat, following example will only read the data once and then it will be cached:

data = require(fs.realpathSync(doctree_fp));
share|improve this answer




But if you want a way of inserting and extracting arbitrary side-channel data to a valid JSON, here is an answer. We take advantage of the non-unique representation of data in a JSON encoding. This is allowed in section two of the RFC under "whitespace is allowed before or after any of the six structural characters".

First, canonicalize your JSON by minifying it:

$jsonMin = json_encode(json_decode($json));

Then encode your comment in binary:

$commentBinary = base_convert($value[1], 16, 2);

Then steg your binary:


Here is your output:

$jsonWithComment = $steg . $jsonMin;
share|improve this answer


 * Description 
    // rainbows
    "unicorn": /* ❤ */ "cake"


//=> {unicorn: 'cake'}
share|improve this answer

I just found "grunt-strip-json-comments".

“Strip comments from JSON. Lets you use comments in your JSON files!”

    // rainbows
    "unicorn": /* ❤ */ "cake"
share|improve this answer

Yes, you can, but your parse will probably fail (there is no standard).

To parse it you should remove those comments, or by hand, or using a regex exp:

Replaces any comments like:

 * Hey


Replaces any comments like:

// Hey


In javascript, you could do something like this:

jsonString = jsonString.replace(/\/\*([^*]|[\r\n]|(\*+([^*/]|[\r\n])))*\*\/+/, "").replace(/\/\/.*/,"")
var object = JSON.parse(jsonString);
share|improve this answer

If your context is Node.js configuration, you might consider JavaScript via module.exports as an alternative to JSON:

module.exports = {
    "key": "value",

    // And with comments!
    "key2": "value2"

The require syntax will still be the same. Being JavaScript, the file extension should be .js.

share|improve this answer

protected by Brad Larson Oct 18 '11 at 14:40


Would you like to answer one of these unanswered questions instead?
