Merge pull request #7 from DecimalTurn/tc

Author: DecimalTurn

index.markdown

@@ -9,6 +9,10 @@ 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`]) 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
 
 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 +46,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. For more information regarding trailing commas, refer to the [trailing commas information page](/trailingcommas).
 
 ## Semantics
 
@@ -91,8 +95,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))
-
 

trailingcommas.markdown

@@ -0,0 +1,27 @@
+---
+
+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](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.
+
+## Can a Parser That Chooses to Support Trailing Commas Still Be Considered a JSONC Parser?
+
+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
+
+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.
+
+
+