HRON (Hierarchical Reference Object Notation) is a structured text format designed to provide an efficient balance between human readability, compactness, and high-performance parsing. It is suitable for configuration files, data transport, and machine-generated data while still remaining easy to read and write manually.
HRON was developed to address limitations found in formats such as JSON, XML, YAML, and TOON. The key advantages of HRON include:
HRON removes unnecessary punctuation and avoids overly complex structural rules with the concept of pre-defined keys. The format is clean, predictable, and far less error-prone.
HRON is optimized for rapid serialization and deserialization. Based on benchmark tests, HRON outperforms formats like TOON in both encoding and decoding speed.
Its concise notation produces smaller output files, making it suitable for network transmission, caching, and storage of large datasets.
Unlike YAML, which allows ambiguous and context-dependent interpretation, HRON enforces deterministic syntax, making it safe for both machines and humans.
HRON avoids verbose, tag-based syntax while maintaining clarity and structure.
Assume the following data:
{
"data": {
"users": [
{ "id": 1, "name": "Alice", "role": "admin", "verified": false, "hobbies": [ "sport", "run", "game" ] },
{ "id": 2, "name": "Bob", "role": "user", "verified": false, "hobbies": [ "swim", "travel", "code" ] }
]
}
}The following comparison shows how the same data structure is represented by different formats.
JSON displays data structures in the form of explicit objects and arrays and is very commonly used.
{
"data": {
"users": [
{ "id": 1, "name": "Alice", "role": "admin", "verified": false, "hobbies": [ "sport", "run", "game" ] },
{ "id": 2, "name": "Bob", "role": "user", "verified": false, "hobbies": [ "swim", "travel", "code" ] }
]
}
}YAML presents data structures with a more concise syntax but relies on indentation to define hierarchy.
data:
users:
- id: 1
name: Alice
role: admin
verified: false
hobbies:
- sport
- run
- game
- id: 2
name: Bob
role: user
verified: false
hobbies:
- swim
- travel
- codeXML uses pairs of opening and closing tags to form a very explicit and verbos data structure.
<?xml version="1.0" encoding="UTF-8" ?>
<data>
<users>
<id>1</id>
<name>Alice</name>
<role>admin</role>
<verified>false</verified>
<hobbies>sport</hobbies>
<hobbies>run</hobbies>
<hobbies>game</hobbies>
</users>
<users>
<id>2</id>
<name>Bob</name>
<role>user</role>
<verified>false</verified>
<hobbies>swim</hobbies>
<hobbies>travel</hobbies>
<hobbies>code</hobbies>
</users>
</data>TOON combines YAML and JSON styles with a denser structure and type-based annotation support.
data:
users[2]:
- id: 1
name: Alice
role: admin
verified: false
hobbies[3]: sport,run,game
- id: 2
name: Bob
role: user
verified: false
hobbies[3]: swim,travel,code
HRON expresses data structures through separate key and value declarations, ensuring data remains compact yet structured.
# List of application users and their attributes
data{users[{id,name,role,verified,hobbies[]}]}: {
[
{1,'Alice','admin',false,['sport','run','game']},
{2,'Bob','user',false,['swim','travel','code']}
]
}
This section provides a basic examples of how the HRON CLI tool is used. You can try the HRON CLI tool instantly with npx.
# Encode JavaScript objects into HRON string
npx hron-format --encode data.json data.hron
# or by using pipe from stdin
cat data.json | npx hron-format --encode
# Decode HRON string into JavaScript objects
npx hron-format --decode data.hron data.json
# or by using pipe from stdin
cat data.hron | npx hron-format --decodeThis section provides an installation guide and basic examples of how HRON is used in a JavaScript or TypeScript environment.
# Installation using NPM
npm install hron-format
# Installation using yarn
yarn add hron-format
# Installation using bun
bun add hron-formatThe following example shows how to read and parse an HRON file into a JavaScript object.
import { hron } from "hron-format";
const data = `
# List of application users and their attributes
data{users[{id,name,role,verified,hobbies[]}]}: {
[
{1,'Alice','admin',false,['sport','run','game']},
{2,'Bob','user',false,['swim','travel','code']}
]
}
`
console.log(hron.parse(data));
// {
// data: {
// users: [
// [Object ...], [Object ...]
// ],
// },
// }The following example shows how JavaScript object can be converted into an HRON representation.
import { hron } from "hron-format";
const data = {
data: {
users: [
{ id: 1, name: "Alice", role: "admin", verified: false, hobbies: [ "sport", "run", "game" ] },
{ id: 2, name: "Bob", role: "user", verified: false, hobbies: [ "swim", "travel", "code" ] }
]
}
}
console.log(hron.stringify(data));
// data{users[{id,name,role,verified,hobbies[]}]}: {
// [
// {
// 1,'Alice','admin',false,[
// 'sport','run','game'
// ]
// },{
// 2,'Bob','user',false,[
// 'swim','travel','code'
// ]
// }
// ]
// }Note
Input must contain a single root object that holds all nested data.
This section displays the performance test results of HRON compared to other formats in terms of decoding, encoding, and file size.
HRON : 0.218 ms
TOON : 0.424 ms
JSON : 0.006 ms
YAML : 0.023 ms
XML : 0.339 msHRON : 0.118 ms
TOON : 0.380 ms
JSON : 0.002 ms
YAML : 0.016 ms
XML : 0.077 msHRON : 176 B
TOON : 222 B
JSON : 620 B
YAML : 273 B
XML : 511 BNote
JSON and YAML are faster because they rely on highly optimized, native parsing and serialization routines built directly into widely used runtime libraries.
Summary: HRON is faster at encoding and decoding than some other formats, and produces smaller output compared to other formats.
This project is distributed under the MIT License.
See the LICENSE file for full details.