hjson: the relaxed JSON dialect and the repository that defines it

A repository whose primary language is HTML

The first thing to notice is that the language detected for this repository is HTML rather than Java, Rust, Go or Python. That is not a scraping mistake. It reflects what the project is: hjson.github.io is a documentation site and a specification, and the GitHub repository is where that site and that specification are written down.

The repository metadata is consistent with that reading. The description field is not a summary of a library but a phrase describing a role, `Hjson, a user interface for JSON`, and the listed topics are `hjson`, `human`, `json` and `spec`. That last topic is the one to hold onto. This is a spec project, and the default branch is named `master` rather than `main`, which fits a codebase that has been in place long enough for the convention to have settled and then not been renamed.

The top level of the tree tells the rest of the story: a `docs/` directory, a `pages/` directory, a `res/` directory for assets, an `rfc/` directory, and a `testCases/` directory. There is no `src`, no `lib`, no package manifest and no build configuration for a distributable artifact. If you came looking for a function to import, this is the wrong repository, and the README is honest about that in about fifteen words before sending you to the documentation site for details.

Three claims, and what they actually buy you

The whole format proposal fits into a single sentence of README prose: it adds comments, makes it nicer to read, and avoids comma mistakes. Three claims, and they are not equally important.

Comments are the one everybody notices. Configuration files carry explanations that JSON has nowhere to put, so the usual outcome is a parallel readme file that drifts out of sync within a month, or a convention of empty string keys that some parsers reject. Making the comment character legal removes the need for either workaround. The related searches around this project are full of `Hjson comment` and the neighbouring `jsonc` questions, which tells you how much of the demand is really about this one feature.

Forgiving syntax is the quieter win, and it is aimed at a specific failure: the human hand-edited diff. Strict JSON treats a trailing comma as a syntax error, so the last entry in every block of a file rewritten by a person is a landmine, and a merge conflict touching the end of an object is a broken build. Optional commas move that failure off the critical path entirely.

Readability is the third claim, and it is more debatable. Once comments and optional commas are in place, an hjson file is genuinely easier to scan than its strict equivalent, because the eye can skip over punctuation it knows is not load-bearing. Whether that is a large improvement depends on how much of the file is punctuation in the first place, which is another argument for applying the dialect selectively rather than converting a whole project.

Where the implementations actually live

The most informative block in the README is a stack of version badges, and reading it as a dependency list rather than decoration gives you the shape of the ecosystem. There is a package on npm, one on Maven Central, one on PyPI, two on nuget under the names Hjson and HjsonSharp, one on Packagist under the maintainer name laktak, two on crates.io named serde-hjson and deser-hjson, a release feed for a Go package called hjson-go, and a LuaRocks module published by cryi.

That is nine distinct distribution points across seven language ecosystems, which is an unusually broad reach for a syntax dialect nobody has heard of. It also shows how thin each implementation is. Two separate .NET packages means the community could not agree on one, and two separate Rust crates means the same thing there, with one positioned around serde and one standalone. A spec project that maintains a test suite can support exactly this pattern, because conformance is defined once, in one place, and each binding is a separate volunteer project.

The practical consequence for someone evaluating the format is that the choice of implementation is a choice of ecosystem, not of quality. If your stack is Python there is one obvious option and no choice at all. If it is .NET or Rust you have two, and the interesting question is which one plays better with the serializer you already use.

The test cases directory is the real artifact

A `testCases/` directory at the top level of a specification repository is a deliberate choice, and it is arguably the most useful thing here for anyone building a parser.

Text formats live or die on edge cases, and the edge cases in a relaxed JSON dialect are where implementations disagree. Does a comment run to the end of the line or to a terminator? Can a key be unquoted when its value is an array that starts on the next line? What happens to a string that spans lines? How is a value like a lone word distinguished from a bare unquoted key at the same nesting level? Each of those has a defensible answer, and each is a place where two conforming-looking parsers quietly diverge. A shared directory of cases converts those questions from folklore into a checklist that an implementation can run against, and it lets a bug report be expressed as a concrete disagreement about input and output rather than as a general claim that something parses wrongly.

This is also why conformance suites tend to survive the projects that inspired them. Language tooling changes, bindings get rewritten in new runtimes, and the format itself is stable enough that it changes rarely. The cases do not care which of those happened.

Proposals live in their own directory

Alongside `docs/` and `pages/` there is an `rfc/` directory, using the naming convention that long-lived open source projects borrow from standards bodies and large language model projects alike. The convention encodes a process rather than a folder: a change to the format gets written up as a proposal, argued over, and only then folded into the specification and the test cases.

For a syntax dialect that process matters more than it would for a library. A library change breaks callers who upgrade, and the break is visible and immediate. A change to a format's accepted syntax is different, because implementations in nine ecosystems have to be updated, and some of them will lag by years because the people who maintain them are not watching this repository. A proposal written down and settled before it reaches the spec is the only thing that makes such a lag survivable, since the prose stays available as the answer to the question of what the format actually intends.

The same reasoning explains the split between `docs/`, `pages/` and `res/`. Reference material, the rendered site and its assets are separate concerns, which is what lets the documentation be built from structured sources rather than maintained as loose HTML by hand.

Reading the project's current state

The repository is public, unarchived, MIT licensed and carries 2,857 stars, 59 forks and 26 open issues. The fork count against the star count is the number worth dwelling on, because it is roughly one fork per fifty stars. That is the profile of a specification rather than a codebase. People star a spec to bookmark it, they link to it from issues and documentation, and very few of them clone it to contribute code, because there is no code in it to contribute.

The 26 open issues on a project like this are worth reading differently than you would read an issue tracker for a library. A spec's issues tend to be syntax questions of the form of can this be written, and why does this parse differently in two implementations, and the answers frequently belong in the documentation or the test cases rather than in code. A maintainer response of here is the answer, put it on the syntax page is a perfectly good outcome.

Activity is recorded as a push on 2026-04-20, and there are no releases attached to the repository at all, which fits a project whose deliverable is a definition rather than an artifact. Nothing here needs to be published to npm on a schedule. When the specification changes, the change lands in the docs and the cases, and every implementation is free to follow at whatever pace its maintainer has.

When relaxing a format is the right call

There is a version of this decision that goes wrong, and it is worth naming. hjson earns its keep in files that humans edit directly: a service's development configuration, a build profile, a fixture in a repository that is read far more often than it is written. Those files have comments to carry and hand-edited tails that break.

It earns nothing in a file produced by a tool. A build artifact that a serializer writes and a parser reads has no human in the loop, no comments to preserve, and no trailing comma to worry about, so the dialect buys nothing while adding a dependency that every consumer must now be able to parse. The same goes for anything crossing a boundary where you do not control the reader, which in practice means most internal APIs and every boundary between organizations.

A useful rule is to treat the dialect as a source format and the strict form as the interchange format. Write `.hjson` where the editing happens, convert once at load time, and let everything downstream see ordinary JSON. That keeps the benefit, which is a file people can actually read and edit, without inheriting the risk, which is a file that only one family of parsers anywhere in your stack understands. The test cases directory is the reference if you need to confirm that a particular construct behaves the way you expect it to.

Editorial conclusion

hjson is a small decision with a long tail. Someone decides that a configuration file will be edited by humans, hands over a JSON parser, and then spends the next two years explaining why a missing comma broke a deploy. hjson removes that category of failure by making comments legal and commas optional, and the repository you land on is the specification rather than an implementation. Start at the documentation site linked from the README, read the syntax page, and decide per file whether the relaxed form is worth it. Keep the file machine-readable in the strict sense anyway: if anything other than the Hjson loader ever needs to consume it, convert to standard JSON before it gets there, because a `.hjson` extension is a promise only the dialect keeps. For tooling work, the test cases directory is the more valuable artefact than any single binding, since it is the closest thing the format has to a conformance suite.

Frequently asked questions

Official sources

1. hjson/hjson on GitHub
2. Issues
3. License: MIT
4. Project website
5. README