From 4c28b26e2b8183c77ce9dc3d9610816d3e7c42ba Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Sat, 28 Mar 2026 23:40:44 +0000 Subject: [PATCH 1/3] docs: clarify comment usage and whitespace terminology - add terminology for line endings and insignificant whitespace - state that comments are informational only and must not affect consumed JSON values clarify single-line comment behavior to end at line ending - expand single-line example to show case at the end of a line --- index.markdown | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/index.markdown b/index.markdown index e0b9a91..012ea65 100644 --- a/index.markdown +++ b/index.markdown @@ -19,23 +19,27 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S 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. +- **Insignificant Whitespace**: Any sequence of space characters, tabs or line endings that is not part of a string. It is generally ignored by parsers and is used to format JSONC documents for better readability. +- **Line ending**: Refers to the sequence of (often invisible) control characters that indicate the end of a line. In JSONC, this sequence can be represented by a line feed (LF) or a carriage return followed by a line feed (CRLF). In terms of Unicode, LF corresponds to U+000A and CR corresponds to U+000D. +- **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 sometimes 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. +- **Trailing comma**: A comma that appears after the last element in an array or the last member 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. +JSONC follows the same syntax rules as JSON with the addition of JavaScript style comments. Comments can be either single-line or multi-line. They can be placed anywhere insignificant whitespace is allowed in regular JSON. + +Comments provide context alongside the data, but they MUST NOT affect consumption. Removing all comments MUST yield the same data representation of the JSON values. ### Single-line Comments -Single-line comments start with `//` and extend to the end of the line. +Single-line comments start with `//` and continue until a line ending is encountered. ```jsonc { // This is a single-line comment "name": "John Doe", - "age": 30 + "age": 30 // This is another single line comment } ``` From 03b0dfde6fe9a47611523355236e24178123c73c Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Sun, 29 Mar 2026 00:11:08 +0000 Subject: [PATCH 2/3] docs: clarify multi-line comments Co-authored-by: hattesen --- index.markdown | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/index.markdown b/index.markdown index 012ea65..9b2948e 100644 --- a/index.markdown +++ b/index.markdown @@ -45,16 +45,31 @@ Single-line comments start with `//` and continue until a line ending is encount ### Multi-line Comments -Multi-line comments start with `/*` and end with `*/`. They can span multiple lines. +Multi-line comments (sometimes called block comments) start with `/*` and end with `*/`. They can span multiple lines, but can also be used on a single line. ```jsonc { /* - This is a multi-line comment + This is a block comment that spans multiple lines */ "name": "Jane Doe", - "age": 25 + "age": /* This is a single-line block comment */ 25 +} +``` + +Multi-line comments cannot be nested. The closing of the nested comment will be interpreted as the end of the outer comment. For instance, the following is invalid JSONC: + +```jsonc + +{ +/* OUTER start + /* NESTED block comments are not supported. + OUTER block comment will end here --> */ + OUTER end +*/ + "name": "John Doe", + "age": 30 } ``` From 50182ea0b8ac1fdcb09e56f119859bc750339619 Mon Sep 17 00:00:00 2001 From: Martin Leduc <31558169+DecimalTurn@users.noreply.github.com> Date: Sun, 29 Mar 2026 14:53:39 +0000 Subject: [PATCH 3/3] docs: add disambiguation section --- index.markdown | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/index.markdown b/index.markdown index 9b2948e..e0b05e0 100644 --- a/index.markdown +++ b/index.markdown @@ -151,6 +151,14 @@ The "JSON with Comments" mode in VS Code used to allow trailing commas without a 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. +## Appendix B: Disambiguation of JSONC + +Some other extensions of JSON that allow comments exist in the wild and might allow alternative syntax. This section is here make those differences explicit. + +### Comments starting with `#` + +Single-line comments that start with `#` are not supported. JSONC must remain a subset of JavaScript syntax and JavaScript does not support `#` comments. + ## References ### [RFC2119]