@jsonic/jsonc

This plugin allows the Jsonic JSON parser to parse JSONC format files (JSON with Comments).

JSONC is a strict superset of JSON that adds single-line (//) and block (/* */) comments. Trailing commas in objects and arrays can be optionally enabled.

| | This open source module is sponsored and supported by Voxgig. | | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |

The documentation below is organized along the Diátaxis quadrants:

• Quick start — tutorial
• How-to guides — task recipes
• Reference — API surface
• JSONC format — explanation

Quick start

TypeScript

Install:

npm install @jsonic/jsonc @jsonic/jsonic-next

Parse:

import { Jsonic } from '@jsonic/jsonic-next'
import { Jsonc } from '@jsonic/jsonc'

const j = Jsonic.make().use(Jsonc)

const result = j('{ "name": "app", /* version */ "version": "1.0" }')
// => { name: 'app', version: '1.0' }

Go

Install:

go get github.com/jsonicjs/jsonc/go

Parse:

package main

import (
    "fmt"
    jsonic "github.com/jsonicjs/jsonic/go"
    jsonc "github.com/jsonicjs/jsonc/go"
)

func main() {
    j := jsonic.Make()
    j.Use(jsonc.Jsonc)

    result, err := j.Parse(`{ "name": "app", /* version */ "version": "1.0" }`)
    if err != nil {
        panic(err)
    }
    fmt.Println(result)
    // => map[name:app version:1.0]
}

How-to guides

Allow trailing commas

TypeScript:

const j = Jsonic.make().use(Jsonc, { allowTrailingComma: true })
j('{ "debug": true, "verbose": false, }')
// => { debug: true, verbose: false }

Go:

j := jsonic.Make()
j.Use(jsonc.Jsonc, map[string]any{"allowTrailingComma": true})
result, _ := j.Parse(`{ "debug": true, "verbose": false, }`)

Parse strict JSON (disable comments)

TypeScript:

const j = Jsonic.make().use(Jsonc, { disallowComments: true })
j('{ "foo": /* not allowed */ true }') // throws

Go:

j := jsonic.Make()
j.Use(jsonc.Jsonc, map[string]any{"disallowComments": true})

Handle parse errors

TypeScript — parse errors throw:

try {
  j('{ "bad": }')
} catch (err) {
  console.error(err.message)
}

Go — errors are returned:

if _, err := j.Parse(`{ "bad": }`); err != nil {
    fmt.Println(err)
}

Parse a file

TypeScript:

import { readFileSync } from 'node:fs'
const j = Jsonic.make().use(Jsonc, { allowTrailingComma: true })
const config = j(readFileSync('tsconfig.json', 'utf8'))

Go:

src, _ := os.ReadFile("tsconfig.json")
j := jsonic.Make()
j.Use(jsonc.Jsonc, map[string]any{"allowTrailingComma": true})
config, _ := j.Parse(string(src))

Reference

TypeScript

function Jsonc(jsonic: Jsonic, options?: JsoncOptions): void

type JsoncOptions = {
  allowTrailingComma?: boolean  // default: false
  disallowComments?: boolean    // default: false
}

Register with jsonic.use(Jsonc, options?). After registration, invoke the jsonic instance as a function on a source string; it returns the parsed value or throws on syntax errors.

| Option | Type | Default | Effect | |--------|------|---------|--------| | allowTrailingComma | boolean | false | Permit a trailing comma before } and ] | | disallowComments | boolean | false | Reject // and /* */ comments (strict JSON) |

Go

func Jsonc(j *jsonic.Jsonic, pluginOpts map[string]any) error

Register with j.Use(jsonc.Jsonc) or j.Use(jsonc.Jsonc, opts) where opts is a map[string]any. Parse then returns (any, error) — map[string]any for objects, []any for arrays, float64 for numbers, string, bool, or nil.

| Key | Type | Default | Effect | |-----|------|---------|--------| | allowTrailingComma | bool | false | Permit a trailing comma before } and ] | | disallowComments | bool | false | Reject // and /* */ comments (strict JSON) |

JSONC format

JSONC follows RFC 8259 (JSON) with these extensions:

• Line comments: // to end of line
• Block comments: /* */ (non-nesting)
• Trailing commas: optional, in objects and arrays

All other JSON rules apply:

• Strings must be double-quoted
• Standard escapes only: \" \\ \/ \b \f \n \r \t \uXXXX
• Numbers: integer, decimal, scientific notation (no hex, octal, binary)
• Keywords: true, false, null (case-sensitive)
• Property names must be double-quoted strings

Conformance notes

The plugin layers JSONC rules on top of jsonic, which is intentionally lenient in some places vs. strict RFC 8259. The test suite runs the nst/JSONTestSuite corpus in strict mode (disallowComments: true) and pins the known-lenient cases in test/jsontestsuite.test.ts (see N_KNOWN_LENIENT). Examples of accepted-but-non-RFC input include numbers with leading zeros and unquoted object keys. Use an RFC-strict parser if byte-perfect RFC 8259 rejection is required.

Acknowledgments

Conformance testing uses third-party corpora under MIT License:

• nst/JSONTestSuite by Nicolas Seriot — vendored at test/JSONTestSuite/ (the test_parsing/ corpus).
• microsoft/node-jsonc-parser — parse-level test cases ported into test/jsonc.test.ts.

See THIRD_PARTY_NOTICES.md for details.

License

MIT. Copyright (c) 2021-2025 Richard Rodger and contributors.