JSON and JSON5 parsing for Go, strict by default.
Turn on comments, trailing commas, hex numbers and more, one at a time. Errors point to the line and column.
config := []byte(`{
// cache settings
"ttl": 300,
"hosts": ["a.example.com", "b.example.com"],
}`)
_, err := jsonvx.ParseObject(config, nil) // strict JSON by default
fmt.Println(err) // unexpected character in JSON input: "// cache settings…" at line 2, column 3
cfg := jsonvx.NewParserConfig(
jsonvx.WithAllowLineComments(true),
jsonvx.WithAllowTrailingCommaObject(true),
)
root, _ := jsonvx.ParseObject(config, cfg)
ttl, _ := root.GetInt("ttl") // 300go get github.com/bube054/jsonvxIt supports both strict JSON (as defined by ECMA-404) and up to a more relaxed variant such as JSON5. This makes it ideal for parsing user-generated data, configuration files, or legacy formats that don't fully comply with the JSON specification.
With a single ParserConfig struct, jsonvx gives you fine-grained control over how JSON is parsed. You can enable or disable features like:
- Hexadecimal numbers
(0xFF) NaNandInfinityas numeric values- Leading plus signs in numbers
(+42) - Decimal edge cases like
.5or5. - Unquoted object keys
({key: "value"}) - Single-quoted strings
('text') - Newlines inside strings
- Escape characters outside the standard set
- Raw control characters such as tabs inside strings
- Trailing commas in arrays or objects
- Line comments
(// comment)and Block comments(/* comment */) - Extra whitespace in unusual places
- Rejecting duplicate object keys
- Enable
JSON5
It also guards against hostile input with a nesting depth limit, on by default, so deeply nested data returns an error instead of crashing your program.
In its default strict mode, jsonvx passes every accept and reject case in JSONTestSuite, the standard conformance suite for JSON parsers; the cases run as part of go test.
jsonvx is designed for flexibility and correctness, not raw performance, making it a good fit for tools, linters, and config loaders where input may vary or include non-standard extensions.
Formatting coming soon: writing parsed data back out as valid
JSON(compact or indented, including convertingJSON5to standardJSON) is planned for an upcoming release.
How the same inputs fare in Go's standard library and two popular relaxed-JSON packages:
| jsonvx | encoding/json | tailscale/hujson | yosuke-furukawa/json5 | |
|---|---|---|---|---|
| Comments, trailing commas | each one a switch | no | yes | yes |
Single quotes, hex, NaN, unquoted keys… |
each one a switch | no | no | no, rejects single quotes and hex |
| Strict mode | the default, passes JSONTestSuite | always strict | no: always accepts comments | no: always relaxed |
| Error message gives | line and column | no position | line and column | no position |
| Decodes into structs | no: a tree with typed getters | yes | yes, through encoding/json | yes |
Choose encoding/json for strict JSON into structs, especially in hot paths: it's faster. On a 0.5 MB document, jsonvx took about 2.6x as long as decoding into a struct; for typical config files the difference is negligible.
Choose hujson if all you need is comments and trailing commas, decoded into structs.
Choose jsonvx when you need more of JSON5 than that, want to decide exactly which extensions to accept, want a strict mode that's tested against JSONTestSuite, or want to read values by path without defining structs.
To start using jsonvx, install Go 1.23 or newer and run:
go get github.com/bube054/jsonvxParse your JSON with ParseObject, then read each value in one call.
package main
import (
"fmt"
"github.com/bube054/jsonvx"
)
func main() {
// bube's favourite isekais, ranked.
data := []byte(`{
"fan": "bube",
"count": 3,
"genres": ["isekai", "fantasy", "comedy"],
"best.of.all": "Re:Zero",
"isekais": [
{"rank": 1, "title": "Re:Zero", "hero": {"first": "Subaru", "last": "Natsuki"}, "party": ["Emilia", "Rem", "Ram", "Beatrice"]},
{"rank": 2, "title": "Mushoku Tensei", "hero": {"first": "Rudeus", "last": "Greyrat"}, "party": ["Roxy", "Sylphiette", "Eris"]},
{"rank": 3, "title": "KonoSuba", "hero": {"first": "Kazuma", "last": "Satou"}, "party": ["Aqua", "Megumin", "Darkness"]}
]
}`)
root, err := jsonvx.ParseObject(data, nil)
if err != nil {
panic(err)
}
count, err := root.GetInt("count")
if err != nil {
panic(err)
}
fmt.Println(count) // 3
title, _ := root.GetString("isekais", "0", "title")
fmt.Println(title) // Re:Zero
party, _ := root.GetArray("isekais", "2", "party")
for i, member := range party.All() {
fmt.Println(i, member) // 0 Aqua, 1 Megumin, 2 Darkness
}
}Use ParseArray when the top-level value is an array, or Parse when it could be anything. The second argument is the parser config; nil means strict JSON.
*Object and *Array have one getter per type. Each takes a path and returns the value already converted:
| Method | Returns | Notes |
|---|---|---|
GetString(path...) |
string |
Escapes are decoded. |
GetInt(path...) |
int64 |
Exact. Errors on 1.5 or 1e3 (ErrNotInteger) and on numbers past int64 (ErrNumberOutOfRange). |
GetFloat(path...) |
float64 |
Very large integers may be rounded. |
GetBool(path...) |
bool |
|
GetNumber(path...) |
*Number |
For BigInt(), Raw() and other exact access. |
GetObject(path...) |
*Object |
To read several values from one place. |
GetArray(path...) |
*Array |
To loop with All() or Values(). |
hero, _ := root.GetObject("isekais", "1", "hero")
first, _ := hero.GetString("first") // Rudeus
last, _ := hero.GetString("last") // Greyrat
isekais, _ := root.GetArray("isekais")
rank, _ := isekais.GetInt("2", "rank") // 3Errors say what went wrong and where, and work with errors.Is:
_, err := root.GetString("count")
// wrong JSON type: expected string, got number at ["count"]
errors.Is(err, jsonvx.ErrWrongType) // true
_, err = root.GetString("isekais", "0", "villain")
// key not found: "villain" at ["isekais" "0" "villain"]
errors.Is(err, jsonvx.ErrKeyNotFound) // trueA getter called on a nil *Object or *Array, for example after ignoring an error from GetObject, returns an error instead of panicking.
A path is a list of strings, one per step: an object key, or an array index written as a string ("0"). Keys are used exactly as written, so a key with dots needs no escaping. Using the Quick Start data:
root.GetString("isekais", "0", "title") // "Re:Zero"
root.GetString("genres", "1") // "fantasy"
root.GetString("best.of.all") // "Re:Zero"
root.GetString("isekais", "1", "hero", "last") // "Greyrat"
root.GetString("isekais", "2", "party", "1") // "Megumin"
root.GetInt("isekais", "2", "rank") // 3
root.GetArray("genres") // [isekai, fantasy, comedy]
root.GetObject("isekais", "1") // {rank: 2, title: Mushoku Tensei, ...}On an array, the first step is an index: isekais.GetString("0", "title").
All()loops over key-value pairs,Values()over just the values, andKeys()returns the keys as a[]string. All three follow the order the keys were written in. Usesort.Strings(obj.Keys())for alphabetical order.Len()is the number of keys.- Duplicate keys: the last value wins, matching
encoding/json, JavaScript'sJSON.parseand theJSON5spec. To reject duplicates instead, useDisallowDuplicateKeys. Equalcompares objects by key, so key order does not affect it.
hero, _ := root.GetObject("isekais", "0", "hero")
for key, value := range hero.All() {
fmt.Println(key, value)
}
// first Subaru
// last Natsuki
for value := range hero.Values() {
fmt.Println(value)
}
// Subaru
// Natsuki
fmt.Println(hero.Keys()) // [first last]
fmt.Println(hero.Len()) // 2
dup, _ := jsonvx.ParseObject([]byte(`{"best_girl": "Emilia", "best_girl": "Rem"}`), nil)
bestGirl, _ := dup.GetString("best_girl") // Rem, the last value wins- In a path, an array index is written as a string:
"0"is the first item. All()loops over index and item,Values()over just the items, andLen()is the number of items.break,continueandreturnwork as in anyfor rangeloop.- Loop items are
jsonvx.JSONnodes. Printing one shows its value; to read inside one, cast it to*jsonvx.Objector*jsonvx.Array.
party, _ := root.GetArray("isekais", "0", "party")
fmt.Println(party.Len()) // 4
firstMember, _ := party.GetString("0") // Emilia
for i, member := range party.All() {
fmt.Println(i, member)
}
// 0 Emilia
// 1 Rem
// 2 Ram
// 3 Beatrice
for member := range party.Values() {
if member.String() == "Rem" {
fmt.Println("Found Rem")
break
}
}
// An array of objects: cast each item to read inside it.
isekais, _ := root.GetArray("isekais")
for item := range isekais.Values() {
show, _ := item.(*jsonvx.Object)
title, _ := show.GetString("title")
fmt.Println(title)
}
// Re:Zero
// Mushoku Tensei
// KonoSubaGetStringdecodes escape sequences:\n,\",\u00e9and emoji pairs like\ud83d\ude00become the characters they stand for. WithJSON5options,\',\v,\0,\xHHand line continuations are decoded too.- Keys are decoded the same way, so
{"caf\u00e9": 1}is read withroot.GetInt("café"). - To get a string exactly as written, escapes and all, use
Raw()on the node.
GetIntis exact for every whole number that fits in anint64.GetFloatreturns afloat64, which holds about 16 significant digits, so longer numbers are rounded:9007199254740993becomes9007199254740992.- For whole numbers of any size, or the number exactly as written, use
GetNumber:
root, _ := jsonvx.ParseObject([]byte(`{"adventurer_card_id": 9007199254740993}`), nil)
approx, _ := root.GetFloat("adventurer_card_id") // 9.007199254740992e+15 (rounded)
exact, _ := root.GetInt("adventurer_card_id") // 9007199254740993
id, _ := root.GetNumber("adventurer_card_id")
big, _ := id.BigInt() // 9007199254740993, any size
raw, _ := id.Raw() // "9007199254740993", as writtenGetBoolreadstrueandfalse.nullhas no value to return, so there is no getter for it. Check for it with a type assertion on the node:
root, _ := jsonvx.ParseObject([]byte(`{"finished": false, "season4": null}`), nil)
finished, _ := root.GetBool("finished") // false
node, _ := root.QueryPath("season4")
_, isNull := node.(*jsonvx.Null) // true- Comments are ignored.
- Input with only comments and no data is an error:
no meaningful content to parse.
By default, the parser is strict, matching the ECMA-404 specification. To allow relaxed formats, build a config with the options you want and pass it to Parse, ParseObject or ParseArray:
cfg := jsonvx.NewParserConfig(
jsonvx.WithAllowTrailingCommaArray(true),
jsonvx.WithAllowLineComments(true),
)
root, err := jsonvx.ParseObject(data, cfg)Allows extra whitespace characters that are not normally permitted by strict JSON, such as vertical tab and form feed.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowExtraWS(true))
jsonvx.Parse([]byte("{\"hero\":\v\"Subaru\"}"), cfg) // ok: vertical tab
jsonvx.Parse([]byte("{\"hero\":\f\"Subaru\"}"), cfg) // ok: form feedEnables hexadecimal numbers such as 0x1F. Upper and lower case work (0xff, 0XFF), as do negative numbers (-0x10) and, with AllowLeadingPlus, a leading plus.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowHexNumbers(true))
root, _ := jsonvx.ParseObject([]byte(`{"mana": 0xFF}`), cfg)
mana, _ := root.GetInt("mana") // 255Allows numbers like .5 or 5. without a digit before or after the decimal point.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowPointEdgeNumbers(true))
jsonvx.Parse([]byte(".5"), cfg) // ok
jsonvx.Parse([]byte("5."), cfg) // okEnables Infinity, -Infinity and +Infinity as numbers.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowInfinity(true))
jsonvx.Parse([]byte("Infinity"), cfg) // ok
jsonvx.Parse([]byte("-Infinity"), cfg) // ok
jsonvx.Parse([]byte("+Infinity"), cfg) // ok only with AllowLeadingPlusAllows NaN (Not-a-Number) as a number.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowNaN(true))
jsonvx.Parse([]byte("NaN"), cfg) // ok
jsonvx.Parse([]byte("-NaN"), cfg) // ok
jsonvx.Parse([]byte("+NaN"), cfg) // ok only with AllowLeadingPlusPermits a leading + in numbers.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowLeadingPlus(true))
jsonvx.Parse([]byte("+9999"), cfg) // ok (EXPLOSION!)Allows unquoted object keys. Values still need quotes.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowUnquoted(true))
jsonvx.Parse([]byte(`{hero: "Kazuma"}`), cfg) // ok
jsonvx.Parse([]byte(`{hero: Kazuma}`), cfg) // error: unquoted valueAllows strings in single quotes as well as double quotes.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowSingleQuotes(true))
jsonvx.Parse([]byte(`{'name': 'Megumin'}`), cfg) // okAllows a line break inside a string when it is escaped with a backslash.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowNewlineInStrings(true))
jsonvx.Parse([]byte(`"Starting life in \
another world"`), cfg) // okAllows escape sequences other than \", \\, \/, \b, \f, \n, \r, \t and \uXXXX.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowOtherEscapeChars(true))
jsonvx.Parse([]byte(`"another\qworld"`), cfg) // okAllows raw control characters (bytes 0x00-0x1F, such as a tab) inside strings, as JSON5 does. Strict JSON requires them to be escaped (\t). Raw line breaks are never allowed inside strings; use AllowNewlineInStrings for an escaped one.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowControlCharsInStrings(true))
jsonvx.Parse([]byte("\"Rem\tRam\""), cfg) // ok: raw tab
jsonvx.Parse([]byte("\"Rem\nRam\""), cfg) // error: raw line breakPermits a trailing comma in arrays.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowTrailingCommaArray(true))
jsonvx.Parse([]byte(`["Aqua", "Megumin", "Darkness", ]`), cfg) // okPermits a trailing comma in objects.
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowTrailingCommaObject(true))
jsonvx.Parse([]byte(`{"rank": 1,}`), cfg) // okAllows single-line comments (// ...).
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowLineComments(true))
jsonvx.Parse([]byte("// Kazuma's luck stat\n99"), cfg) // okAllows block comments (/* ... */).
cfg := jsonvx.NewParserConfig(jsonvx.WithAllowBlockComments(true))
jsonvx.Parse([]byte(`/* Explosions Megumin casts per day */ 1`), cfg) // okRejects objects that repeat a key with ErrJSONDuplicateKey, reporting where the duplicate is. Keys are compared after decoding escapes, so "a" and "\u0061" count as the same key. When disabled (the default), the last value for a repeated key wins. Useful for linters and validators, where a repeated key is usually a mistake.
cfg := jsonvx.NewParserConfig(jsonvx.WithDisallowDuplicateKeys(true))
jsonvx.Parse([]byte(`{"best_girl": "Rem", "best_boy": "Subaru"}`), cfg) // ok
jsonvx.Parse([]byte(`{"best_girl": "Rem", "best_girl": "Emilia"}`), cfg) // error: duplicate key in JSON object: "best_girl" at line 1, column 22JSON5Config() turns on every option above except DisallowDuplicateKeys, so you can read JSON5.
status, _ := jsonvx.ParseObject([]byte(`{
// Rudeus Greyrat's status window
name: 'Rudeus Greyrat',
title: 'Rudeus "the Quagmire"',
mana: 0xFF,
critChance: .25, luckMultiplier: 7.,
karma: +1,
spells: ['Stone Cannon', 'Quagmire',],
}`), jsonvx.JSON5Config())
name, _ := status.GetString("name") // Rudeus Greyrat
mana, _ := status.GetInt("mana") // 255Sets the maximum nesting depth of arrays and objects (default 1000, see jsonvx.DefaultMaxDepth). Deeper input fails with ErrJSONTooDeep instead of overflowing the stack and crashing the program. This applies to every config, including JSON5Config(). A value of 0 or less uses the default.
cfg := jsonvx.NewParserConfig(jsonvx.WithMaxDepth(2))
jsonvx.Parse([]byte(`[["loop 1"]]`), cfg) // ok: depth 2
jsonvx.Parse([]byte(`[[["loop 99"]]]`), cfg) // error: JSON nesting too deep (Return by Death can't save you here)When you don't know a value's type ahead of time, QueryPath returns the node itself, and a type switch tells you what it is. Every node type has a Value() method.
node, err := root.QueryPath("isekais", "0", "rank")
if err != nil {
panic(err)
}
switch v := node.(type) {
case *jsonvx.String:
s, _ := v.Value() // string
raw, _ := v.Raw() // as written, escapes kept
fmt.Println(s, raw)
case *jsonvx.Number:
n, _ := v.Value() // float64
fmt.Println(n)
case *jsonvx.Boolean:
b, _ := v.Value() // bool
fmt.Println(b)
case *jsonvx.Null:
fmt.Println("null")
case *jsonvx.Array:
fmt.Println(v.Len(), "items")
case *jsonvx.Object:
fmt.Println(v.Keys())
}See CHANGELOG.md for what changed in each release.
- bube054 - Attah Gbubemi David (author)
This project is licensed under the MIT. See the LICENSE file for details.