Subject: [Json] JSON comments /* ... */ and // ...

From: jwilson <[email-masked]>
Date: Thu, 19 Sep 2013 21:29:28 -0400

Several popular JSON libraries I've used permit comments in messages.
Jackson supports comments with its Feature.ALLOW_COMMENTS flag, Gson
supports them with setLenient(true) and the org.json Java parser accepts
them by default.

Here's my best description of how comments work in practice:

There are two kinds of comments used by JSON:

/*multiline comment terminated by asterix slash*/

//single line comment terminated by \r\n or \r or \n

Zero or more comments may occur wherever ignorable whitespace occurs. The
processors ignore comments in the same way they do ignorable whitespace.
Comments do not nest.

Unlike many XML processors, JSON processors do not attempt to provide
character-for-character fidelity for modeled documents. The document model
does not typically retain or emit comments.

Comments are useful in manually edited documents. For example, here's a
JSON file for configuring an application:

{
  "country_whitelist": [
    "CA",
    "US",
    // Japan & France haven't launched yet
    // "JP",
    // "FR",
    "GB", // (United Kingdom)
    "BR"
  ]
}

Note that comments are used to both document the content as well as to
suppress it.

Can we include this in the new spec?

Thanks!

---

From: "Matt Miller (mamille2)" <[email-masked]>
Date: Fri, 20 Sep 2013 02:27:47 +0000

On Sep 19, 2013, at 7:29 PM, jwilson <[email-masked]>
 wrote:

> Several popular JSON libraries I've used permit comments in messages. Jackson supports comments with its Feature.ALLOW_COMMENTS flag, Gson supports them with setLenient(true) and the org.json Java parser accepts them by default.
> 
> Zero or more comments may occur wherever ignorable whitespace occurs. The processors ignore comments in the same way they do ignorable whitespace. Comments do not nest.
> 
> Unlike many XML processors, JSON processors do not attempt to provide character-for-character fidelity for modeled documents. The document model does not typically retain or emit comments.
> 
> Comments are useful in manually edited documents. For example, here's a JSON file for configuring an application:
> 
> {
>   "country_whitelist": [
>     "CA",
>     "US",
> Note that comments are used to both document the content as well as to suppress it.
> 

/me dons hat

Thank you for your contribution, but it cannot be accepted.  This contribution does not fit within the bounds of the Working Group charter, as it does not correct a significant error or inconsistency.

- m&m

Matt Miller < [email-masked] >
Cisco Systems, Inc.

---

From: jwilson <[email-masked]>
Date: Thu, 19 Sep 2013 22:46:24 -0400

Real JSON in the wild has comments. Real JSON processors handle these
comments.

The hypothetical JSON in draft-ietf-json-rfc4627bis-03 doesn‘t include the
word ’comment' or acknowledge that comments exist. This is not an
inconsistency? If it isn't, we may need a new document "Real world JSON"
that admits that comments exist and offers advice on how to handle them!

---

From: Paul Hoffman <[email-masked]>
Date: Fri, 20 Sep 2013 07:44:24 -0700

<hat on>

On Sep 19, 2013, at 7:46 PM, jwilson <[email-masked]> wrote:

> Real JSON in the wild has comments. Real JSON processors handle these comments.

Some python parsers probably implement the style of comments you give, even if they are not documented in RFC 4627 or ECMAScript.

Some clearly don't. My first attempt to validate your statement (Python) threw an error.

> The hypothetical JSON in draft-ietf-json-rfc4627bis-03 doesn‘t include the word ’comment' or acknowledge that comments exist. This is not an inconsistency?

Nope.

> If it isn't, we may need a new document "Real world JSON" that admits that comments exist and offers advice on how to handle them!

That could be considered later, certainly. Another thing that could be considered later are extensions to JSON that people have proposed over the years.

Having said that, I believe your view that comments are in "Real world JSON" is probably quite wrong, given that one of the most widely-used libraries doesn't handle what you say.

--Paul Hoffman

---

From: Tatu Saloranta <[email-masked]>
Date: Fri, 20 Sep 2013 08:21:42 -0700

On Fri, Sep 20, 2013 at 7:44 AM, Paul Hoffman <[email-masked]> wrote:

> Some python parsers probably implement the style of comments you give,
> even if they are not documented in RFC 4627 or ECMAScript.
>
> > The hypothetical JSON in draft-ietf-json-rfc4627bis-03 doesn‘t include
> the word ’comment' or acknowledge that comments exist. This is not an
> inconsistency?
>
> Nope.
>
> > If it isn't, we may need a new document "Real world JSON" that admits
> that comments exist and offers advice on how to handle them!
>
> That could be considered later, certainly. Another thing that could be
> considered later are extensions to JSON that people have proposed over the
> years.
>
> Having said that, I believe your view that comments are in "Real world
> JSON" is probably quite wrong, given that one of the most widely-used
> libraries doesn't handle what you say.
>
>
I can't really rank wide usage aspect to comment, but one thing worth
noting is that some libraries default to strict handling, but allow
explicit loosening of restrictions.
So using default settings could fail, while library would be able to accept
comments when explicitly enabled.

 I did that for Jackson (Java), since while I personally feel comments
should always have been in JSON, I also think deviations from standards
must be done explicitly, and only if user/dev indicates this is to be done.
I think that having such settings is common with Java libraries; perhaps
this is not done on other platforms.

I also only added this after getting multiple requests by users to support
this: so my data point (for what it is worth) is that there is enough such
usage that users do expect support.

So, I realize that such changes are not in scope of this update; but I hope
this issue is included in a list of possible future work. It is one of more
controversial subjects, mostly because JSON author feels strongly against
addition, but where there isn't consensus as far as I know, regarding where
inclusion itself would be right or wrong. Just that it may be impractical
after being excluded for so long.

-+ Tatu +-

---

From: "Matt Miller (mamille2)" <[email-masked]>
Date: Fri, 20 Sep 2013 16:45:51 +0000

On Sep 20, 2013, at 9:21 AM, Tatu Saloranta <[email-masked]> wrote:

> I can't really rank wide usage aspect to comment, but one thing worth noting is that some libraries default to strict handling, but allow explicit loosening of restrictions.
> So using default settings could fail, while library would be able to accept comments when explicitly enabled.
> 
>  I did that for Jackson (Java), since while I personally feel comments should always have been in JSON, I also think deviations from standards must be done explicitly, and only if user/dev indicates this is to be done. I think that having such settings is common with Java libraries; perhaps this is not done on other platforms.
> 
> I also only added this after getting multiple requests by users to support this: so my data point (for what it is worth) is that there is enough such usage that users do expect support.
> 
> So, I realize that such changes are not in scope of this update; but I hope this issue is included in a list of possible future work. It is one of more controversial subjects, mostly because JSON author feels strongly against addition, but where there isn't consensus as far as I know, regarding where inclusion itself would be right or wrong. Just that it may be impractical after being excluded for so long.
> 
> -+ Tatu +-

/me dons hat

The Working Group could decide to recharter to accomplish other goals; support for comments could be under consideration.  Others have suggested canonicalization, best practices, and profiles, et cetera.  The current charter already states additional proposals will be considered once -bis is "done".

The chairs and our venerable Area Director request the Working Group first complete its current milestone before trying to take on more work.  Bear with us!

- m&m