From fec52ad45312c5eff367a0dd466cec982ad98b77 Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Sun, 17 Aug 2025 21:27:37 +0000 Subject: [PATCH 1/6] Clarify goal of the spec and introduce trailing commas seperate information page. --- index.markdown | 8 +++----- trailingcommas.markdown | 29 +++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+), 5 deletions(-) create mode 100644 trailingcommas.markdown diff --git a/index.markdown b/index.markdown index 3d5b81f..3936cc9 100644 --- a/index.markdown +++ b/index.markdown @@ -9,6 +9,8 @@ layout: default JSONC (JSON with Comments) is an extension of JSON (JavaScript Object Notation) that allows comments within JSON data. This specification defines the syntax and semantics of JSONC. +The JSONC format was informally introduced by Microsoft to be used for VS Code's configuration files (settings.json, launch.json, tasks.json, etc.). Alongside the informal format, a publicly available parser ([jsonc-parser](https://www.npmjs.com/package/jsonc-parser)) was supplied to parse those configuration files. The goal of this specification is to formalize the JSONC format as what the jsonc-parser considers valid while using its default configurations. + ## Syntax JSONC follows the same syntax rules as JSON with the addition of JavaScript style comments. Comments can be either single-line or multi-line. @@ -42,7 +44,7 @@ Multi-line comments start with `/*` and end with `*/`. They can span multiple li ## Trailing commas -JSONC doesn't allow trailing commas; however, we encourage parsers to be lenient and handle trailing commas gracefully where possible to reduce the risk of human edits introducing parsing errors.[^1] +JSONC doesn't allow trailing commas. Indeed, the jsonc-parser doesn't support them while using default configurations since `allowTrailingComma` is an optional parameter that is false by default. For more information regarding trailing commas, please refer to the [trailing commas information page](/trailingcommas). ## Semantics @@ -91,8 +93,4 @@ Here is a non-exhaustive list: **Rust** - [dprint/jsonc-parser](https://github.com/dprint/jsonc-parser) ---- - -[^1]: In VS Code, "the [JSONC] mode also accepts trailing commas, but they are discouraged and the editor will display a warning." ([source](https://code.visualstudio.com/docs/languages/json#_json-with-comments)) - diff --git a/trailingcommas.markdown b/trailingcommas.markdown new file mode 100644 index 0000000..b242c1f --- /dev/null +++ b/trailingcommas.markdown @@ -0,0 +1,29 @@ +--- + +layout: default +--- + +# Trailing Commas and JSONC + +## Why Trailing Commas Aren't Part of the JSONC Specification? + +Trailing commas are not part of the JSONC Specification because the reference implementation, [jsonc-parser](https://www.npmjs.com/package/jsonc-parser), does not allow them unless explicitly configured. The `allowTrailingComma` option is set to `false` by default, so any trailing comma will result in a parsing error. + +The reason why this specification chose the default behavior of the parser as the reference for the standard is to ensure that JSONC remains compatible with the broader JSON ecosystem, which does not allow trailing commas. This decision helps maintain consistency and predictability across different parsers and implementations. Namely, the tsconfig and eslint config files, which are widely used in the JavaScript ecosystem, do not allow trailing commas in their JSONC files. + +The exclusion of trailing commas also facilitates the creation of tools and libraries that can parse JSONC without needing to handle additional syntax variations. This helps ensure that JSONC remains a lightweight and straightforward extension of JSON, primarily focused on adding comments without introducing significant complexity. + +## Can a Parser Choose to Support Trailing Commas? + +Yes, a parser can choose to support trailing commas in JSONC files for convenience. This is especially useful in configuration files or code where lists and objects are frequently edited. Allowing trailing commas can make adding, removing, or reordering items easier and reduce the likelihood of syntax errors. + +However, this is not part of the official JSONC specification and such support would be considered an extension or variation of the standard JSONC format. This means that while a parser may allow trailing commas, it may not be compatible with all JSONC parsers or tools that strictly adhere to the JSONC specification without trailing commas. + +## Trailing Commas in VS Code + +The "JSON with Comments" mode in VS Code used to allow trailing commas without any warnings by default, but this was eventually changed to discourage their use and promote better compatibility with other JSONC parsers ([source](https://github.com/microsoft/vscode/issues/102061)). + +At the time of writing this document, the "JSON with Comments" mode still accepts trailing commas, but it discourages their usage by displaying a warning ([source](https://code.visualstudio.com/docs/languages/json#_json-with-comments)) unless the file is one of the VS Code official configuration files. The exclusion of those configuration files comes from the JSON schema used. The schema for these files explicitly allow trailing commas, which is why they are accepted without warnings in that specific context. + + + From 2615c831eb8ddbc6098d4b7f21d0a76e99a0961a Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Sun, 31 Aug 2025 18:25:50 -0400 Subject: [PATCH 2/6] Update index.markdown Co-authored-by: John Gardner --- index.markdown | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/index.markdown b/index.markdown index 3936cc9..e22036e 100644 --- a/index.markdown +++ b/index.markdown @@ -9,7 +9,9 @@ layout: default JSONC (JSON with Comments) is an extension of JSON (JavaScript Object Notation) that allows comments within JSON data. This specification defines the syntax and semantics of JSONC. -The JSONC format was informally introduced by Microsoft to be used for VS Code's configuration files (settings.json, launch.json, tasks.json, etc.). Alongside the informal format, a publicly available parser ([jsonc-parser](https://www.npmjs.com/package/jsonc-parser)) was supplied to parse those configuration files. The goal of this specification is to formalize the JSONC format as what the jsonc-parser considers valid while using its default configurations. +The JSONC format was informally introduced by Microsoft to be used for VS Code's configuration files (`settings.json`, `launch.json`, `tasks.json`, etc). Alongside the informal format, a publicly-available parser ([`jsonc-parser`]) was supplied to parse those configuration files. The goal of this specification is to formalize the JSONC format as what [`jsonc-parser`] considers valid while using its default configurations. + +[`jsonc-parser`]: https://www.npmjs.com/package/jsonc-parser ## Syntax From d9bf045d052d30f39f59d17c56d371fb69777565 Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Sun, 31 Aug 2025 22:50:39 +0000 Subject: [PATCH 3/6] Add links to TSConfig and ESLint per @Alhadis' suggestion --- trailingcommas.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trailingcommas.markdown b/trailingcommas.markdown index b242c1f..5619b0e 100644 --- a/trailingcommas.markdown +++ b/trailingcommas.markdown @@ -9,7 +9,7 @@ layout: default Trailing commas are not part of the JSONC Specification because the reference implementation, [jsonc-parser](https://www.npmjs.com/package/jsonc-parser), does not allow them unless explicitly configured. The `allowTrailingComma` option is set to `false` by default, so any trailing comma will result in a parsing error. -The reason why this specification chose the default behavior of the parser as the reference for the standard is to ensure that JSONC remains compatible with the broader JSON ecosystem, which does not allow trailing commas. This decision helps maintain consistency and predictability across different parsers and implementations. Namely, the tsconfig and eslint config files, which are widely used in the JavaScript ecosystem, do not allow trailing commas in their JSONC files. +The reason why this specification chose the default behavior of the parser as the reference for the standard is to ensure that JSONC remains compatible with the broader JSON ecosystem, which does not allow trailing commas. This decision helps maintain consistency and predictability across different parsers and implementations. Namely, the [TSConfig](https://www.typescriptlang.org/tsconfig/) and [ESLint config](https://eslint.org/docs/latest/use/configure/configuration-files) files, which are widely used in the JavaScript ecosystem, do not allow trailing commas in their JSONC files. The exclusion of trailing commas also facilitates the creation of tools and libraries that can parse JSONC without needing to handle additional syntax variations. This helps ensure that JSONC remains a lightweight and straightforward extension of JSON, primarily focused on adding comments without introducing significant complexity. From 9ffa0a4f4eea7c62ae4fd9c7f87984dad84a9f96 Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Sun, 31 Aug 2025 22:54:55 +0000 Subject: [PATCH 4/6] Clarify question regarding parsers that support trailing commas --- trailingcommas.markdown | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/trailingcommas.markdown b/trailingcommas.markdown index 5619b0e..1f6689d 100644 --- a/trailingcommas.markdown +++ b/trailingcommas.markdown @@ -13,11 +13,9 @@ The reason why this specification chose the default behavior of the parser as th The exclusion of trailing commas also facilitates the creation of tools and libraries that can parse JSONC without needing to handle additional syntax variations. This helps ensure that JSONC remains a lightweight and straightforward extension of JSON, primarily focused on adding comments without introducing significant complexity. -## Can a Parser Choose to Support Trailing Commas? +## Can a Parser That Chooses to Support Trailing Commas Still Be Considered a JSONC Parser? -Yes, a parser can choose to support trailing commas in JSONC files for convenience. This is especially useful in configuration files or code where lists and objects are frequently edited. Allowing trailing commas can make adding, removing, or reordering items easier and reduce the likelihood of syntax errors. - -However, this is not part of the official JSONC specification and such support would be considered an extension or variation of the standard JSONC format. This means that while a parser may allow trailing commas, it may not be compatible with all JSONC parsers or tools that strictly adhere to the JSONC specification without trailing commas. +Yes, however this is not part of the official JSONC specification and such support would be considered an extension or variation of the standard JSONC format. This means that while a parser may allow trailing commas, it may not be compatible with all JSONC parsers or tools that strictly adhere to the JSONC specification without trailing commas. ## Trailing Commas in VS Code From ef4ec29c7103843d112f76dd8e3534bac3fa40d0 Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Sun, 31 Aug 2025 23:05:31 +0000 Subject: [PATCH 5/6] Remove extra details about trailing commas on the main page as suggested by @Alhadis --- index.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.markdown b/index.markdown index e22036e..793420d 100644 --- a/index.markdown +++ b/index.markdown @@ -46,7 +46,7 @@ Multi-line comments start with `/*` and end with `*/`. They can span multiple li ## Trailing commas -JSONC doesn't allow trailing commas. Indeed, the jsonc-parser doesn't support them while using default configurations since `allowTrailingComma` is an optional parameter that is false by default. For more information regarding trailing commas, please refer to the [trailing commas information page](/trailingcommas). +JSONC doesn't allow trailing commas. For more information regarding trailing commas, refer to the [trailing commas information page](/trailingcommas). ## Semantics From a699d2b613aa441123d7d699763583781ec83c3a Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Mon, 1 Sep 2025 00:17:09 +0000 Subject: [PATCH 6/6] Clarify which specification --- trailingcommas.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trailingcommas.markdown b/trailingcommas.markdown index 1f6689d..d2b098d 100644 --- a/trailingcommas.markdown +++ b/trailingcommas.markdown @@ -15,7 +15,7 @@ The exclusion of trailing commas also facilitates the creation of tools and libr ## Can a Parser That Chooses to Support Trailing Commas Still Be Considered a JSONC Parser? -Yes, however this is not part of the official JSONC specification and such support would be considered an extension or variation of the standard JSONC format. This means that while a parser may allow trailing commas, it may not be compatible with all JSONC parsers or tools that strictly adhere to the JSONC specification without trailing commas. +Yes, however this is not part of the JSONC.org specification and such support would be considered an extension or variation of the standard JSONC format. This means that while a parser may allow trailing commas, it may not be compatible with all JSONC parsers or tools that strictly adhere to the JSONC specification without trailing commas. ## Trailing Commas in VS Code