Adjust trailing comma recommendation using RFC2119's terminology

[DecimalTurn]

Considering that:

• Important JSONC files that used to be a concern when allowing trailing commas are no longer a concern.
  • tsconfig.json files officially support trailing commas (tsconfig.json actually supports trailing commas #12)
  • .eslintrc.json files are now depreciated.

This spec needs to soften its position against trailing commas. Hence, a new wording is proposed using RFC2119's terminology.

New stance on trailing commas:

JSONC parsers MAY support trailing commas. For more information regarding trailing commas, refer to Appendix A.

There is still something to be said about JSONC emitters, formatters and editors. This is only a first step and the other cases should be reflected on further.

[Timmmm]

LGTM - I think it might be worth mentioning why VSCode changed its stance. IIRC it's because they use the JSONC mode for some files whose parsers don't support trailing comments. I think tsconfig.json.

[DecimalTurn]

Indeed, the main reason for warning against trailing commas was for the exact 2 files I mentioned above: microsoft/vscode#102061 (comment)

There might be other reasons that were not expressed yet, so I don't want to write about the VS Code Team's motivation for the current behavior, but if people want to know they can find it.

[ell1e]

I would rather suggest a "should" than a "may", otherwise it feels pretty much like before in practice. (As you would probably expect me to suggest with my prior argument, that most user-facing uses of JSONC will have them enabled.)

[ell1e]

The extension .json SHOULD be avoided, but is supported if a mode line is present at the start of the file:

This seems a little unclear, since the second sentence doesn't use any of the RFC2119 terms. Perhaps it could be something like:

The extension .json SHOULD be avoided, but if it is used, there SHOULD be a mode line is present at the start of the file to indicate that it's actually a JSONC file:

Reasoning: it seems like the tsconfig.json file is introduced here: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html and it accepts comments and now apparently trailing commas, and they use the .json extension with no mode line. So I don't think a MUST requirement makes sense when a popular tool doesn't follow it.

[Timmmm]

I mentioned above

Oh yeah sorry, I can't read apparently!

[Timmmm]

are no longer a concern

Although I dunno if I would go this far because quite a few parsers still support comments but not trailing commas unfortunately.

[ell1e]

I'm sure there will always be some feature differences remaining, sadly, e.g. for comment styles too.

[github-actions]

PR Preview Action v1.6.3
🚀 View preview at https://DecimalTurn.github.io/JSONC/pr-preview/pr-14/
Built to branch main at 2025-12-14 01:21 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[ell1e]

The diff view seems confused so I can't see if anything else changed. I would be curious about the two points I brought up, and your thoughts on them. Sorry for taking up your time.

[DecimalTurn]

I would rather suggest a "should" than a "may", otherwise it feels pretty much like before in practice. (As you would probably expect me to suggest with my prior argument, that most user-facing uses of JSONC will have them enabled.)

@ell1e - Yeah, I expected that and it could be argued that a future version should take that stance, but it felt wrong going directly all the way to "SHOULD". Also, this wording is indeed close to what it was before, but at least it's less ambigous hopefully. This wording is basically what is currently applied in practice. If it can be demonstrated that the majority of parsers support trailing commas, then it could become an official recommendantion.

This seems a little unclear, since the second sentence doesn't use any of the RFC2119 terms.

That's fair, I've adressed this issue in 840c623

Although I dunno if I would go this far because quite a few parsers still support comments but not trailing commas unfortunately.

@Timmmm - I'm only referring to parsers for theses 2 files in that case, not for all parsers.

I'm sure there will always be some feature differences remaining, sadly, e.g. for comment styles too.

@ell1e - What do you mean by comments styles? Is that something that should be specified in the spec you think?

[ell1e]

but it felt wrong going directly all the way to "SHOULD"

I just feel like the JSONC ecosystem is moving toward this trailing comma thing, and you know my conceptual points too. Edit: but I'm glad you expected my input 😊 and I agree the current wording is considerably more clear.

What do you mean by comments styles? Is that something that should be specified in the spec you think?

Pretty sure I've seen JSONC variants that support e.g. # comments, and some support ' instead of " for quotes, and so on. My point was, I don't think turning the trailing comma into a "SHOULD" should depend on all major actors moving there, but I would suggest doing that change as soon as most major tools seem to be heading there.

There's never going to be a point where all tools match the spec exactly, especially since there used not to be one.

[ell1e]

After some more thought, an obvious alternative might be:

JSONC parsers MAY support trailing commas, but SHOULD require a user opt-in to enable that feature.

I like that less, of course. But it would answer whether a user can expect a trailing comma in a file to work in most parsers, or not. The "MAY" alone doesn[...]

I guess the user just can't expect it, I brainfarted.