Adjust trailing comma recommendation using RFC2119's terminology

Author: DecimalTurn

_config.yml

@@ -20,8 +20,6 @@
 
 title: JSONC
 email: [email protected]
-description: >- # this means to ignore newlines until "baseurl:"
-  JSONC Specification
 baseurl: "" # the subpath of your site, e.g. /blog
 url: "https://jsonc.org" # the base hostname & protocol for your site, e.g. http://example.com
 github_username:  DecimalTurn

index.markdown

@@ -3,6 +3,8 @@
 layout: default
 ---
 
+# Specification
+
 **Notice:** This is a draft of the JSONC Specification and is subject to change.
 
 ## Introduction
@@ -13,6 +15,16 @@ The JSONC format was informally introduced by Microsoft to be used for VS Code's
 
 [`jsonc-parser`]: https://www.npmjs.com/package/jsonc-parser
 
+## Conventions and Terminology
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](#rfc2119)
+
+The following terms are used throughout this specification:
+
+- **Mode line**: A special comment at the beginning of a file that specifies the file type or mode, following conventions used by text editors like Emacs or Vim.
+- **Parser**: A software component that reads and interprets JSONC documents.
+- **Trailing comma**: A comma that appears after the last element in an array or the last property in an object, before the closing bracket or brace.
+
 ## 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.
@@ -46,7 +58,7 @@ Multi-line comments start with `/*` and end with `*/`. They can span multiple li
 
 ## Trailing commas
 
-JSONC doesn't allow trailing commas. For more information regarding trailing commas, refer to the [trailing commas information page](/trailingcommas).
+JSONC parsers MAY support trailing commas. For more information regarding trailing commas, refer to [Appendix A](#appendix-a-trailing-commas-and-jsonc).
 
 ## Semantics
 
@@ -56,7 +68,7 @@ Comments in JSONC are ignored during parsing, allowing developers to annotate th
 
 The recommended file extension for JSONC documents is `.jsonc`.
 
-The extension `.json` should be avoided, but is supported if a mode line is present at the start of the file:
+The extension `.json` SHOULD be avoided, but is supported if a mode line is present at the start of the file:
 
 For instance:
 ```jsonc
@@ -100,3 +112,24 @@ Here is a non-exhaustive list:
 
 **Kotlin**
 - [kotlinx.serialization.json](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/allow-comments.html)
+
+
+## APPENDIX A: Trailing Commas and JSONC
+
+### Why Trailing Commas Are Not a Requirement?
+
+Trailing commas are not a requirement 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.
+
+Mandatory trailing commas support might be added to future versions of the jsonc.org Specification when trailing commas reaches sufficient adoption in the Javascript ecosystem.
+
+### 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 ([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.
+
+## References
+
+### [RFC2119]
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

trailingcommas.markdown

@@ -3,25 +3,16 @@
 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.
-
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="refresh" content="0; url=https://jsonc.org/#appendix-a-trailing-commas-and-jsonc">
+  <link rel="canonical" href="https://jsonc.org/#appendix-a-trailing-commas-and-jsonc">
+  <title>Redirecting...</title>
+</head>
+<body>
+  <p>Redirecting...</p>
+</body>
+</html>