Indexed by TopGit from live GitHub metadata: tidwall/gjson has 15.6k stars, written primarily in Go. Get JSON values quickly - JSON parser for Go
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
GJSON is a Go package that provides a fast and simple way to get values from a json document.
It has features such as one line retrieval, dot notation paths, iteration, and parsing json lines.
Also check out SJSON for modifying json, and the JJ command line tool.
This README is a quick overview of how to use GJSON, for more information check out GJSON Syntax.
GJSON is also available for Python and Rust
The official Git repository is at Codeberg.
Getting Started
Installing
To start using GJSON, install Go and run go get:
$ go get -u github.com/tidwall/gjson
This will retrieve the library.
Get a value
Get searches json for the specified path. A path is in dot syntax, such as "name.last" or "age". When the value is found it's returned immediately.
package main
import "github.com/tidwall/gjson"
const json = `{"name":{"first":"Janet","last":"Prichard"},"age":47}`
func main() {
value := gjson.Get(json, "name.last")
println(value.String())
}
This will print:
Prichard
There's also GetBytes for working with JSON byte slices.
Path Syntax
Below is a quick overview of the path syntax, for more complete information please
check out GJSON Syntax.
A path is a series of keys separated by a dot.
A key may contain special wildcard characters '*' and '?'.
To access an array value use the index as the key.
To get the number of elements in an array or to access a child path, use the '#' character.
The dot and wildcard characters can be escaped with '\'.
You can also query an array for the first match by using #(...), or find all
matches with #(...)#. Queries support the ==, !=, <, <=, >, >=
comparison operators and the simple pattern matching % (like) and !%
(not like) operators.
Please note that prior to v1.3.0, queries used the #[...] brackets. This was
changed in v1.3.0 as to avoid confusion with the new
multipath syntax. For backwards compatibility,
#[...] will continue to work until the next major release.
Result Type
GJSON supports the json types string, number, bool, and null.
Arrays and Objects are returned as their raw json types.
The Result type holds one of these:
bool, for JSON booleans
float64, for JSON numbers
string, for JSON string literals
nil, for JSON null
To directly access the value:
result.Type // can be String, Number, True, False, Null, or JSON
result.Str // holds the string
result.Num // holds the float64 number
result.Raw // holds the raw json
result.Index // index of raw value in original json, zero means index unknown
result.Indexes // indexes of all the elements that match on a path containing the '#' query character.
There are a variety of handy functions that work on a result:
The result.Array() function returns back an array of values.
If the result represents a non-existent value, then an empty array will be returned.
If the result is not a JSON array, the return value will be an array containing one result.
64-bit integers
The result.Int() and result.Uint() calls are capable of reading all 64 bits, allowing for large JSON integers.
result.Int() int64 // -9223372036854775808 to 9223372036854775807
result.Uint() uint64 // 0 to 18446744073709551615
Modifiers and path chaining
New in version 1.2 is support for modifier functions and path chaining.
A modifier is a path component that performs custom processing on the
json.
Multiple paths can be "chained" together using the pipe character.
This is useful for getting results from a modified query.
For example, using the built-in @reverse modifier on the above json document,
we'll get children array and reverse the order:
You would use the path "programmers.#.lastName" like such:
result := gjson.Get(json, "programmers.#.lastName")
for _, name := range result.Array() {
println(name.String())
}
You can also query an object inside an array:
name := gjson.Get(json, `programmers.#(lastName="Hunter").firstName`)
println(name.String()) // prints "Elliotte"
Iterate through an object or array
The ForEach function allows for quickly iterating through an object or array.
The key and value are passed to the iterator function for objects.
Only the value is passed for arrays.
Returning false from an iterator will stop iteration.
result := gjson.Get(json, "programmers")
result.ForEach(func(key, value gjson.Result) bool {
println(value.String())
return true // keep iterating
})
Simple Parse and Get
There's a Parse(json) function that will do a simple parse, and result.Get(path) that will search a result.
For example, all of these will return the same result:
Sometimes you just want to know if a value exists.
value := gjson.Get(json, "name.last")
if !value.Exists() {
println("no last name")
} else {
println(value.String())
}
// Or as one step
if gjson.Get(json, "name.last").Exists() {
println("has a last name")
}
Validate JSON
The Get* and Parse* functions expects that the json is well-formed. Bad json will not panic, but it may return back unexpected results.
If you are consuming JSON from an unpredictable source then you may want to validate prior to using GJSON.
if !gjson.Valid(json) {
return errors.New("invalid json")
}
value := gjson.Get(json, "name.last")
Unmarshal to a map
To unmarshal to a map[string]interface{}:
m, ok := gjson.Parse(json).Value().(map[string]interface{})
if !ok {
// not a map
}
Working with Bytes
If your JSON is contained in a []byte slice, there's the GetBytes function. This is preferred over Get(string(data), path).
var json []byte = ...
result := gjson.GetBytes(json, path)
If you are using the gjson.GetBytes(json, path) function and you want to avoid converting result.Raw to a []byte, then you can use this pattern:
var json []byte = ...
result := gjson.GetBytes(json, path)
var raw []byte
if result.Index > 0 {
raw = json[result.Index:result.Index+len(result.Raw)]
} else {
raw = []byte(result.Raw)
}
This is a best-effort no allocation sub slice of the original json. This method utilizes the result.Index field, which is the position of the raw data in the original json. It's possible that the value of result.Index equals zero, in which case the result.Raw is converted to a []byte.
Performance
Benchmarks of GJSON alongside encoding/json,
ffjson,
EasyJSON,
jsonparser,
and json-iterator
No homepage URL was recorded for tidwall/gjson in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
How active is development on tidwall/gjson?
The most recent commit recorded on tidwall/gjson was 3 months ago, based on the GitHub push timestamp. The repository has 910 forks — one of the better signals of community interest.
How many stars does tidwall/gjson have?
tidwall/gjson has 15.6k GitHub stars — refresh the page for the live number, or check github.com/tidwall/gjson. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What language is tidwall/gjson written in?
tidwall/gjson is written primarily in Go. GitHub's language field is based on the largest share of bytes in the default branch.
What license does tidwall/gjson use?
tidwall/gjson is released under the MIT license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
What topics is tidwall/gjson associated with?
GitHub's repository topics for tidwall/gjson: "golang", "json", "json-parser". TopGit's editorial category is Backend.
Where do I read more about tidwall/gjson?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/tidwall/gjson is the definitive source.
Read full README in the tab above.
Curious whether gjson is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about gjson.
/gjson
