Notice: This is a draft of the JSONC Specification and is subject to change.

Introduction

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.

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

The following terms are used throughout this specification:

• 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 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. 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 continue until a line ending is encountered.

{
    // This is a single-line comment
    "name": "John Doe",
    "age": 30 // This is another single line comment
}

Multi-line Comments

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.

{
    /*
      This is a block comment
      that spans multiple lines
    */
    "name": "Jane Doe",
    "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:

{ 
/* OUTER start
  /* NESTED block comments are not supported.
      OUTER block comment will end here --> */
  OUTER end
*/
    "name": "John Doe",
    "age": 30
}

Trailing commas

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

Semantics

Comments in JSONC are ignored during parsing, allowing developers to annotate their JSON data without affecting its structure or content.

File extensions

The recommended file extension for JSONC documents is .jsonc.

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

For instance:

// -*- mode: jsonc -*-

or

// -*- jsonc -*-

Main Use Cases

• Configuration Files: JSONC is useful for configuration files where comments can provide explanations or instructions.
• Data Annotation: JSONC allows developers to annotate JSON data with comments for better understanding and maintenance.

Tools and Libraries

Several tools and libraries support JSONC, enabling developers to parse and generate JSONC data easily.

Here is a non-exhaustive list:

JavaScript/TypeScript:

• microsoft/node-jsonc-parser

C++

• stephenberry/glaze

Elixir

• massivefermion/jsonc

Go

• tidwall/jsonc

Python

• n-takumasa/json-with-comments

PHP

• otar/jsonc

Rust

• dprint/jsonc-parser

Swift

• steelbrain/JSONCKit

Java

• Jackson JsonFactory.enable(JsonReadFeature.ALLOW_JAVA_COMMENTS)

Kotlin

• kotlinx.serialization.json

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, 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).

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) 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]

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.