Could you find me some deeper studies comparing JSON and HJSON? Are there any other "JSON which can be used by humans" alternatives?
It appears that formal, "deeper studies" in the academic sense (like peer-reviewed research papers) specifically comparing JSON and HJSON are rare. However, the design rationales, feature breakdowns, and formal specifications serve as the most detailed comparisons available.
Here is a synthesis of the key differences and an overview of other "human-friendly JSON" alternatives.
HJSON (Human JSON) is a configuration file format designed to be easier for humans to read, write, and edit than strict JSON, which is primarily optimized for machine parsing. It is generally considered a superset of JSON (meaning valid JSON is usually valid HJSON, though HJSON's features make its syntax broader).
| Feature | Standard JSON | HJSON (Human JSON) | Rationale for HJSON |
|---|---|---|---|
| Comments | Not Allowed | Allowed (using #, //, or /*...*/) |
Essential for configuration files where context and notes are needed. |
| Key Quotes | Mandatory (double quotes) | Optional for keys that are valid identifiers. | Reduces clutter and makes data look more like standard programming objects. |
| Trailing Commas | Not Allowed | Allowed | Prevents diffs on a single line when reordering or adding new properties at the end of an object/array. |
| Value Quotes | Mandatory (double quotes) | Optional (Quoteless Strings) | Text values can often be written without quotes, further reducing visual noise. |
| Root Braces | Mandatory | Optional | Allows the file to be a simple list of key-value pairs for root objects. |
| Multiline Strings | Uses escaping (\n) |
Supports triple-quoted multi-line strings. | Easier for humans to manage long blocks of text. |
Several other data serialization formats exist that aim to retain JSON's simplicity while improving human readability, especially for configuration files.
JSON5 is often cited as the closest alternative to HJSON. It is a proposed extension of JSON that aims to be a stricter superset than HJSON, aligning closely with ECMAScript 5.1 (ES5) syntax.
| Key Features of JSON5 | How it Improves Readability |
|---|---|
| Comments | Supports single-line (//) and multi-line (/*...*/) comments. |
| Unquoted Keys | Allows object keys to be unquoted if they are valid JavaScript identifiers. |
| Trailing Commas | Permits trailing commas in objects and arrays. |
| Single Quotes | Allows strings to be enclosed in single quotes ('...'). |
YAML Ain't Markup Language is a well-established, highly human-readable format, but it is not a direct superset of JSON. It is structurally very different, relying heavily on indentation for structure.
| Key Characteristics of YAML | Use Case |
|---|---|
| Indentation-based | Uses spaces (not tabs) for structure instead of braces ({}) and brackets ([]). |
| Comments | Uses # for comments. |
| Data Types | Supports a wide variety of data types, including dates and custom types, which can sometimes lead to ambiguity. |
Tom's Obvious, Minimal Language is explicitly designed to be a simple configuration file format. It uses a very clear key-value pair structure.
| Key Characteristics of TOML | Use Case |
|---|---|
| Simple Syntax | Primarily uses key = value syntax. |
| Tables | Structures are defined using table headers enclosed in brackets (e.g., [server]). |
| Data Types | Supports native types like dates and times. |
Human-Optimized Config Object Notation is a configuration file format developed by Lightbend. It is a superset of JSON but adds features like path substitutions, type conversions, and the ability to omit quotes, commas, and the root object braces, similar to HJSON.
JSON with Comments is a format popularized by Microsoft's Visual Studio Code, where it is used for configuration files (like settings.json). It is not a formal standard but is widely supported by tools. It is generally standard JSON but allows single-line (//) and multi-line (/*...*/) comments. It is often considered a subset of JSON5.
So, OK, and some articles comparing HJSON and JSON5?
That's an excellent next step. While both HJSON and JSON5 aim to make JSON more human-friendly, they approach this goal with slightly different philosophies, which leads to their key distinctions.
The core difference lies in their relationship to the JavaScript (ECMAScript) language.
Here is a side-by-side comparison of the two formats:
| Feature | JSON5 (JSON for Humans) | HJSON (Human JSON) | Key Distinction |
|---|---|---|---|
| Primary Goal / Philosophy | To be a strict subset of ECMAScript 5.1 (JavaScript syntax). | To be as relaxed and un-cluttered as possible for configuration files. | JSON5 prioritizes JS syntax compatibility; HJSON prioritizes maximum readability. |
| JS Compatibility | High - A valid JSON5 document is also valid JavaScript code. | Lower - Features like quoteless strings and line-feed separators are not valid JavaScript syntax. | JSON5 can sometimes be loaded or used directly in JS environments; HJSON requires its own parser/converter. |
| Quoteless Strings (Values) | Not Supported (requires quotes) | Supported (strings can be quoteless until a line break or structural character) | HJSON allows for less "syntax noise" on simple string values. |
Root Braces ({}) |
Mandatory | Optional (root can be a list of key-value pairs) | HJSON allows a flatter, more config-file-like structure at the top level. |
| String Quotes | Allows Double (") and Single (') quotes. |
Allows Double (") and Single (') quotes, and triple-quoted multi-line strings. |
HJSON offers an easier syntax for managing very long strings across multiple lines. |
| Comments | Supports // and /*...*/ |
Supports #, //, and /*...*/ |
Both formats successfully address the main drawback of standard JSON. |
| Trailing Commas | Supported | Supported (and line-feed/newline can also act as a separator) | Both formats prevent common version control merge headaches. |
| Numeric Literals | Adds NaN, Infinity, +Infinity, 0x hex notation. |
Primarily standard JSON numbers. | JSON5 brings in more JavaScript number features. |
The choice generally boils down to your primary context:
-
Choose JSON5 if:
- JavaScript Compatibility is Critical: You work in a Node.js or browser environment and want a format that is as close to valid JavaScript syntax as possible for easier parsing, validation, or integration with existing tools.
- You need a well-defined superset: It has a more formal specification that is a strict subset of ES5.
-
Choose HJSON if:
- Maximum Readability is Critical: You are primarily creating human-edited configuration files and want the fewest quotes, commas, and structural characters possible.
- You prefer the look of quoteless values and the option to omit root braces for simpler, flat-looking config files.
Would you like to see a short example of the same data written in Standard JSON, JSON5, and HJSON to visually compare the differences?
I am thinking about filing an issue for replacing JSON with some "human-friendly" superset of JSON in Gitea (https://github.com/go-gitea/gitea/), which is written in Go language. Are there any good and well-established libraries for either of these supersets (JSON5 and HJSON) in Go?
That's a great question, as library stability and ecosystem maturity are crucial for an established project like Gitea.
Yes, there are established and actively maintained Go libraries for both HJSON and JSON5, though HJSON's official Go implementation is generally more established and easier to recommend.
The Go implementation for HJSON is well-established, maintained by the same group that created HJSON, and is designed to integrate cleanly with Go's standard library.
- Package:
github.com/hjson/hjson-go/v4 - Establishment: This is the official Go implementation of the HJSON format, which suggests better long-term support and compliance with the HJSON specification.
- Integration: It provides
hjson.Marshalandhjson.Unmarshalfunctions that are direct analogs to the standardencoding/jsonfunctions, making it relatively straightforward to integrate into a Go codebase. - Features: It supports all HJSON features (comments, quoteless strings/keys, optional commas, multi-line strings).
- Round-Trip Support: The library offers functionality using the
hjson.Nodetype to read and write HJSON documents while preserving comments and layout, which is a key feature for configuration files where human edits matter.
JSON5 has several community-driven implementations in Go, but none are the single, definitive "official" implementation maintained by the central JSON5 organization in the same way HJSON is.
| Library | Status & Note |
|---|---|
github.com/titanous/json5 |
Most Referenced/Starred: This is one of the more recognized libraries. It focuses on being a decoder (parser) and is based on the standard encoding/json package. It appears actively used by many in the community. |
barney.ci/go-json5 |
Feature Focused: This library specifically notes that it translates the JSON5 document to standard JSON on the fly, making it easy to feed into the standard json.Decoder. It supports all features except Infinity and NaN (due to limitations in converting to standard JSON). |
github.com/shoobyban/json5 |
Parser/Tokenizer: A simpler implementation that also supports marshaling and unmarshaling. |
Verdict on JSON5 in Go: While JSON5 is very popular in the JavaScript ecosystem, the Go libraries are more fragmented. You would need to vet one of the community libraries to ensure it meets Gitea's performance and stability needs.
For a Go project, HJSON offers a slightly safer choice due to its single, well-maintained, official library (github.com/hjson/hjson-go).
If Gitea's primary goal is to provide end-users with a highly flexible config format that minimizes punctuation (quoteless strings and optional root braces), HJSON is the more natural fit and has the most mature Go library.
If the goal is simply to allow comments and trailing commas while staying as close as possible to the core JSON/JS standard (prioritizing JavaScript compatibility), then JSON5 is the philosophical fit, but you would need to select a community Go library and ensure its long-term maintenance is acceptable.
Would you like me to draft a summary of the pros and cons of using HJSON vs. JSON5 (based on the library maturity and features) specifically for a configuration change in Gitea?
What's the difference between HJSON and HuJSON?
That is an insightful question that brings up an alternative that is much more minimal than HJSON.
The key difference between HJSON and HuJSON lies in their philosophy of extension. HuJSON is a highly minimal extension, whereas HJSON is a comprehensive one.
HuJSON is an acronym for "Human JSON," but the format it implements is formally called JWCC (JSON With Commas and Comments). It was developed and is maintained by Tailscale for their own configuration needs in Go.
Here is a side-by-side comparison:
| Feature | HuJSON (JWCC) | HJSON (Human JSON) | Key Difference |
|---|---|---|---|
| Parsing Philosophy | Strictly Minimal. Aims to be as close to RFC 8259 (Standard JSON) as possible. | Highly Relaxed. Aims to remove all boilerplate punctuation. | HuJSON is minimalist; HJSON is maximalist in human-friendly features. |
| Comments | Supported (// and /*...*/) |
Supported (#, //, and /*...*/) |
Both support comments, solving the biggest JSON frustration. |
| Trailing Commas | Supported | Supported | Both allow trailing commas in arrays and objects. |
| Quoteless Keys | Not Supported (Keys must be double-quoted) | Supported (Keys can be unquoted if they are identifiers) | HJSON offers more syntax reduction here. |
| Quoteless Strings (Values) | Not Supported (Strings must be double-quoted) | Supported (Strings can be quoteless on a single line) | HJSON is far more relaxed on string values. |
Root Braces ({}) |
Mandatory | Optional (Root can be a list of key-value pairs) | HuJSON retains the standard JSON structure; HJSON allows for a flatter style. |
| Go Library Status | Excellent. Maintained by Tailscale (github.com/tailscale/hujson). Highly stable for Go environments. |
Excellent. Maintained by the HJSON team (github.com/hjson/hjson-go). |
Both have mature Go libraries, but HuJSON's smaller scope makes it simpler to reason about. |
- Scope: HuJSON is a minimalist preprocessor. It strips comments and allows trailing commas, then converts the result to pure standard JSON that can be consumed by the Go standard library's
encoding/json. HJSON has a much broader, custom grammar that necessitates its own full parsing engine. - Compatibility: HuJSON offers higher compatibility with existing JSON tools, as the only thing you change is the file's syntax; the core data structure is virtually identical to what you get from strict JSON.
- Ambiguity & Security: HuJSON's minimal feature set reduces the risk of parsing ambiguity and security concerns, as it avoids complex features like quoteless strings and line-feed separators, which often complicate the grammar and introduce edge-case bugs.
For Gitea, HuJSON is essentially JSONC (JSON with Comments) + Trailing Commas. It would be a strong, low-risk alternative to HJSON, especially given its origin in a security-conscious Go-based company (Tailscale).
OK, that sounds more like JSON5, what’s the difference between HuJSON and JSON5?
You are correct that HuJSON is much closer to the minimal feature set of JSON5 than HJSON, but there is one critical difference between them, particularly when viewed from a Go development perspective.
The difference lies in their approach to unquoted keys and other structural relaxations.
| Feature | HuJSON (JWCC) | JSON5 | Core Difference |
|---|---|---|---|
| Unquoted Keys | NO. Keys must be quoted (double quotes "..."). |
YES. Keys can be unquoted if they are valid JavaScript identifiers. | HuJSON is stricter. It avoids one of the features that increases parser complexity and potential ambiguity (e.g., is true a boolean value or an unquoted key?). |
| Single-Quoted Strings | NO. Strings must be double-quoted ("..."). |
YES. Strings can be single-quoted ('...'). |
JSON5 includes this JavaScript feature for convenience; HuJSON avoids it to stay closer to core JSON's string definition. |
| Additional Data Types | NO. Limited to the six JSON standard types (string, number, object, array, true, false, null). | YES. Adds non-standard number types like Infinity, NaN, and explicit + signs for numbers. |
JSON5 imports more from JavaScript's full feature set, adding complexity and potential cross-language interoperability issues. |
| Implementation Goal (Tailscale) | Minimal extension to solve the two biggest human annoyances (comments & trailing commas) with the least risk. | Comprehensive extension to make JSON feel more like modern JavaScript object literals. | HuJSON's conservatism is by design to minimize parser bugs and security surface area. |
For your Go project, HuJSON is arguably the most pragmatic and safest choice among all the JSON supersets because it requires the absolute minimum changes to the parser logic.
- Lowest Risk: By supporting only comments and trailing commas, HuJSON (JWCC) minimizes the new grammar rules, reducing the surface area for the security vulnerabilities (like DoS) seen in more complex parsers.
- Go Integration: The
github.com/tailscale/hujsonlibrary provides a.Standardize()method which strips out the comments and trailing commas, leaving pure, valid JSON that can be consumed directly by the robust, existing standard Go parser (encoding/jsonor your currentgoccy/go-json). This is the cleanest integration model.
The philosophical reason HuJSON exists is that its creator believed JSON5 introduced too many new concepts (unquoted keys, new number formats) that increase ambiguity and complexity without offering commensurate benefit for simple configuration files.