HuJSON: JSON that lets you write comments and leave the trailing comma

Two additions to JSON, and nothing else

The scope of the extension is small enough to state in full. The package implements the JWCC extension of standard JSON, and the format permits two things over standard JSON. First, C-style line comments and block comments intermixed with whitespace. Second, trailing commas after the last member or element in an object or array. There is no third addition, and that restraint is what makes the format usable. The critical property is stated in one line and it is the thing that separates this from a new format: all JSON is valid JWCC. A document that parses as standard JSON parses as HuJSON, so there is no need to decide at read time which dialect a file is in, and a tool that only understands plain JSON will fail on a commented file rather than misread it. The extension is defined in a specification written by Nigel Tao, and the readme links both that description and the JSON RFC, which tells you this is an implementation of a published proposal rather than a private convention, and the package documentation badge points at the Go reference pages for the exported API.

Why comments and trailing commas are worth a format

It is easy to dismiss both additions as conveniences, and they are conveniences, but they remove two specific sources of friction in a JSON file. Trailing commas are the thing you want when you add an entry to an array or an object and then have to go back and delete the comma from the line above, which is exactly the edit that produces a conflict when two people add entries to the same list on the same branch. Comments are what you want when a configuration file has a value that needs explaining, because the alternative in strict JSON is a key named after the reason, or a separate documentation file that immediately goes stale. Neither of those is a technical problem, and both cost a small amount of attention every time the file is read. The cost of the format is equally small and equally concrete, since the file is no longer valid standard JSON, and anything that reads it with a strict parser will fail. That is a decision about who reads your files, and it is why the format is a good fit for a project that owns both the writer and the reader, and a poor fit for a file that other people's tooling will consume.

The pipeline stages are visible in the file layout

The repository is a single Go module with the work split across files whose names describe the stages. There is a parse file, a pack file, a patch file, a format file, a find file, a standard file and a types file, along with the top level find, format, pack, parse, patch, standard and types source files. Reading those names as a pipeline is the most useful thing a newcomer can do, because the order is the obvious one. Parsing produces a tree that retains the comments and the trailing commas, packing turns that tree back into text, and formatting is the step that normalises the output. The find file is the one whose purpose is not obvious from its name alone, and it is the piece that makes the format more than a parser, since it suggests searching within a document while keeping the rest of the file intact. The types file is what a typed Go audience will care about, since it defines what the parsed tree looks like to the compiler, and the presence of a separate standard file suggests the library keeps plain JSON handling distinct from the extended handling. The test layout backs this up, with a test file for each stage plus a dedicated fuzz test file, which is a good sign for a parser.

Formatting with hujsonfmt, and a single install command

The formatter is a separate program, which is how Go distributes command line tools, and installing it is one command:

go install github.com/tailscale/hujson/cmd/hujsonfmt@latest

The command lives in a cmd subdirectory of the module, so the binary name follows the directory rather than the module, and the at-latest suffix means you take whatever the repository currently ships. A formatter for a config format is not a toy, because the alternative to formatting a file is a diff that shows every line changed because someone reformatted it by hand. Running the formatter on a file that already has comments and trailing commas should be a no-op, and that property is what makes it safe to put in a pre-commit hook, since a formatter that reorders your comments on every run is worse than no formatter. The readme does not document the flags, and the behaviour of the formatter on a file with unusual whitespace is not described, so the sensible thing is to run it once on a copy and look at the diff before adding it to a hook.

Patching a document without rewriting it

The presence of a patch file next to the parse and pack files is the most interesting signal in the layout, because patching a configuration file is the case where a comment-aware format earns its keep. A tool that reads a JSON document, changes one value and writes it back has to preserve everything it did not intend to change, and in standard JSON that means the comments are gone the moment the file is rewritten, because they are not part of the data model. In HuJSON the comments are part of the parsed tree, so a patch that changes one key can leave the surrounding comments in place. That turns the format from a convenience into a tool for automated edits, whether those edits come from a person running a command or from a program applying a default. The same reasoning explains the find file, because locating a value in a document while keeping the rest intact is the same problem as patching it, and both are much easier when the tree remembers what was between the values.

The editor side needs two settings, not one

The readme handles the editor integration, and the detail worth catching is that a file association alone is not enough. Visual Studio Code supports a similar jsonc format, JSON with comments, and to treat all files with the hujson extension as jsonc with trailing commas allowed you add a snippet to the Visual Studio Code configuration:

"files.associations": {
    "*.hujson": "jsonc"
},
"json.schemas": [{
    "fileMatch": ["*.hujson"],
    "schema": {
        "allowTrailingCommas": true
    }
}]

There are two blocks and they do different jobs. The association tells the editor which language mode to use for the files, and the schema entry tells the JSON language service to accept trailing commas, which the editor would otherwise flag as an error in every file you write. The second one is the setting people miss, because without it the comments work and the trailing comma is underlined in red. The upstream format specification is by the same author as the extension description, and the readme links the blog post that defines the JWCC rules, which is where to look if you want the precise grammar rather than the summary.

Editorial conclusion

HuJSON is a good fit for a Go project that keeps configuration or fixtures in JSON and finds the strict grammar fights with the people who write them, because comments and trailing commas remove the two most common sources of merge conflicts and edit churn. It is the wrong choice if you need the output to be consumed by a strict JSON parser, since the format is only valid where the reader understands the extension, and it is the wrong choice if you want the comments to survive into a consumer that strips them, which standard tooling will not do. It is also the wrong choice if you already have a configuration format that allows comments, since then there is nothing to fix. Before adopting it, read the JWCC documentation linked from the readme, because the extension has a precise definition and the library implements that rather than inventing a dialect, and check the trailing comma handling in your editor, since the Visual Studio Code association needs a schema setting as well as a file association. The project is BSD-3-Clause licensed, the last push was on 2026-07-27, and the repository publishes no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. tailscale/hujson on GitHub