The document seems to slightly contradict itself regarding trailing commas

[ell1e]

The document seems to slightly contradict itself regarding trailing commas, since the perhaps most popular user-facing use by VS Code supports them (as stated in a footnote after all). In fact, in the user config which to my knowledge is meant to be JSONC, and represents one of the main advantages JSONC has over JSON which is that it's nicer to write configs in as a human, it won't even warn about trailing commas:

Therefore, if you attempt to specify JSONC such that it includes the VS Code use of it, trailing commas should probably be included as allowed even if discourged.
For what it's worth, I wrote a specification of the VS Code JSONC format a while ago.

[DecimalTurn]

The document seems to slightly contract itself

I'm going to assume you meant "contradict" instead of "contract". I don't necessarily agree that there is a contradiction here, but the motivations and objectives of the specification would need to be clarified and I think you are raising a good point: Unlike what the VS Code documention says, the warning for trailing commas doesn't apply to VS Code configuration files.

However, it does apply to any other files recognized as JSONC by VS Code. For instance, the tsconfig.json file doesn't support trailing commas and is recognized as JSONC¹.

For what it's worth, I wrote a specification of the VS Code JSONC format a while ago.

I did see this while doing research for the current specification draft. I'm open to include elements of your specification to the one for jsonc.org, if that's something you wish to do.

Footnotes

1. As indicated in this comment. ↩

[ell1e]

Thanks, sorry for the typo.

The specs I wrote are similar, just more exhaustive, and notes on diverging implementations, and they allow trailing commas like seen in VS Code. And warning or not, by default if you create a .jsonc file in VS Code, it allows trailing commas.

[ell1e]

I have to admit, I also find this sentence confusing:

however, we encourage parsers to be lenient and handle trailing commas gracefully

As a reader, it makes me wonder what the intended difference is to e.g.:

trailing commas are allowed, but some implementations may implement a warning to discourage them

Not that I like the warning, I find VS Code's warning contradicting as well for various reasons. But that's besides the point of just documenting the format as-is.

[sahinf]

And warning or not, by default if you create a .jsonc file in VS Code, it allows trailing commas.

How do you verify that it allows it? The source code for node-jsonc-parser disables sets the option off, which suggests that it should not allow it.

[ell1e]

How do you verify that it allows it?

You save a file with .json and a file with .jsonc extension and see what it does:

1. .json file, trailing comma shows a clear error:

   

2. .jsonc file, trailing comma shows a warning which may mean it's discouraged but it's clearly not considered an error, hence it's clearly considered allowed:

   

3. User config file which is .jsonc, a super common use case for JSONC, it won't even warn:

   

Based on this, if you treat VS Code as the common JSONC implementation that should influence the specs, I don't think it makes sense to specify trailing commas as not allowed. Claiming trailing commas aren't allowed seems to be the exact opposite of how VS Code uses it.

[sahinf]

But if the parser VS Code uses disallows it by default and they even show a warning about it, then saying that it's allowed in the spec just because it doesn't show an error doesn't seem right and becomes even more confusing for people who don't use the same editor. Like I came here because vim disallows it while neovim allows it. Since there is no common spec, the source of truth should be the compiler's default shipped settings rather than the compiler's most common editor's implementation (which warns you not do it).

[ell1e]

While I can see where you're coming from I disagree, I think the source of truth should be the usage the user is facing most commonly. That'd be how VS Code handles it in the UI, which is allowing the commas.

There's also the question of the point of JSONC: Apparently VS Code invented it for their config files, where there isn't a warning. I came to JSONC myself using it for configs. There's no reason to ban trailing commas in configs, and clearly, VS Code's team thought the same since in their configs they don't show any type of warnings either.

Given the current spec you now make the spec say that trailing commas are usually forbidden, in my mind you would be basically saying the main use case of the format is wrong. This is why I keep coming back to this. (And I really think VS Code's warning is primarily because external tools may not always accept it.)

I hope my insistence now more sense. As I said above:

main advantages JSONC has over JSON which is that it's nicer to write configs in as a human

And I now suggested to the VS Code parser team to change the default.

[ell1e]

Additional note: and I continue to think this sentence just is confusing.

[DecimalTurn]

And I now suggested to the VS Code parser team microsoft/node-jsonc-parser#103.

If they change the default, I'd gladly update the current draft, but I doubt they will make that change based on previous discussions on the same topic like this one. Having support for trailing commas in eslint and tsconfig seem to be the key missing elements that would justify adding trailing commas to the default behavior.

Additional note: and I continue to think #5 (comment).

Do you have a better phrasing to suggest? To me the footnote is more informative than a justification of the position of the spec regarding trailing commas. Also, since this is the first version of the standard, I wanted to keep things simple. One goal of the spec is to be a reference for people building parsers, so they can determine what is needed to be JSONC compliant. Having the number of requirements to a minimum seems like a desirable feature of the spec. Gracefully handling trailing commas in this context would mean to still parse the JSONC and emit a warning in the console, but a parser that throws an error would still be considered JSONC compliant (for v1 at least).

[ell1e]

My recommendation would be to either always forbid it and not encourage implementations to allow it anyway, or to always allow it.

[sahinf]

Do you have a better phrasing to suggest?

I suggest rephrasing "JSONC doesn't allow trailing commas" to be something like "microsoft/node-jsonc-parser assumes trailing commas are not allowed; however, VS Code's implementation and some other jsonc compilers allow it."

[ell1e]

I would argue that's not useful for a standard either. I think a standard should either 1. allow it but explain what tools don't and why, or 2. disallow it but explain what tools do anyway and why.

[DecimalTurn]

To keep things clear, I'm considering keeping the original sentence "JSONC doesn't allow trailing commas" followed by a link saying "Read more". Then, we can have a seperate page to discuss trailing commas that would be seperate from the spec itself and it could discuss:

• Why trailing commas aren't supported (because of node-jsonc-parser's default configuration)
• Why some parsers may choose to support them
• Provide a list of parsers/programs that support trailing commas on top of JSONC's minimal requirements.

[ell1e]

Edit: After some thought, perhaps you could make it some type of formal extension? Like, if a parser provides "jsonc.org's JSONC", I assume people should understand what that implies. If it would be "jsonc.org's JSONC-C" for the comma extension, it would be unambiguous then.