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.

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.

Single-line Comments

Single-line comments start with // and extend to the end of the line.

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

Multi-line Comments

Multi-line comments start with /* and end with */. They can span multiple lines.

{
    /*
      This is a multi-line comment
      that spans multiple lines
    */
    "name": "Jane Doe",
    "age": 25
}

Trailing commas

JSONC doesn’t allow trailing commas. For more information regarding trailing commas, refer to the trailing commas information page.

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 is supported if a mode line is present at the start of the file:

For instance:

// -*- mode: jsonc -*-

or

// -*- jsonc -*-

Main Use Cases

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:

C++

Elixir

Go

Python

Rust