@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'constj=Jsonic.make().use(Jsonc)constresult=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"
)
funcmain() {
j:=jsonic.Make()
j.Use(jsonc.Jsonc)
result, err:=j.Parse(`{ "name": "app", /* version */ "version": "1.0" }`)
iferr!=nil {
panic(err)
}
fmt.Println(result)
// => map[name:app version:1.0]
}

How-to guides

Allow trailing commas

TypeScript:

constj=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:

constj=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'constj=Jsonic.make().use(Jsonc,{allowTrailingComma: true})constconfig=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

functionJsonc(jsonic: Jsonic,options?: JsoncOptions): voidtypeJsoncOptions={allowTrailingComma?: boolean// default: falsedisallowComments?: 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

funcJsonc(j*jsonic.Jsonic, pluginOptsmap[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.