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.

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; however, we encourage parsers to be lenient and handle trailing commas gracefully where possible to reduce the risk of human edits introducing parsing errors.

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++

Elexir

Go

Python

Rust