Guide · Open source
How to use gjson: get JSON values in Go with paths
Updated · written with AI from the project's own documentation and checked against our catalogue data
gjson is a Go package that pulls values out of a JSON document using a short path string such as "name.last" or "age". This guide is for Go developers who need a few fields from a JSON response without writing struct definitions. After reading it you will be able to install gjson, look up values, query arrays, and chain simple modifiers.
GJSONtidwall/gjson · ★ 15.6k · MIT Install options & downloads Quick start
- 1Install the library. Install Go, then run go get -u github.com/tidwall/gjson in your project.
- 2Import the package. Add import "github.com/tidwall/gjson" to the Go file that reads JSON.
- 3Call Get with your JSON and a path. Pass the JSON text and a dot path such as "name.last" to gjson.Get.
- 4Read the value. Call String(), Int() or another helper on the result to get a typed value.
- 5Query arrays when needed. Use #(...) or #(...)# inside a path to match array elements by field value.
- 6Chain modifiers. Add a pipe and a modifier such as |@reverse to transform the result.
Install gjson with go get
gjson is installed with Go. Make sure Go is set up on your machine, then run go get to retrieve the library.
$ go get -u github.com/tidwall/gjsonGet a value with a path
Get searches the JSON for the path you give it. A path uses dot syntax, such as "name.last" or "age". When the value is found it is returned immediately. For byte slices, use GetBytes instead.
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())
}Learn the path syntax
A path is a series of keys separated by a dot. Keys may contain the wildcard characters '*' and '?'. To read an array element, use its index as the key. Use '#' to count array elements or to reach a child path. The dot and wildcard characters can be escaped with a backslash.
- "name.last" returns "Anderson" in the README example
- "children.#" returns 3 for a three-item array
- "children.1" returns "Alex"
- "friends.#.first" returns ["Dale","Roger","Jane"]
- "fav\.movie" returns "Deer Hunter" because the dot is escaped
Query arrays for matching elements
Use #(...) to get the first matching element and #(...)# to get all matches. Queries support the ==, !=, <, <=, >, >= operators, plus % (like) and !% (not like) for simple pattern matching.
- friends.#(last=="Murphy").first returns "Dale"
- friends.#(last=="Murphy")#.first returns ["Dale","Jane"]
- friends.#(age>45)#.last returns ["Craig","Murphy"]
- friends.#(first%"D*").last returns "Murphy"
Read the result value
A result has a Type, plus Str, Num and Raw fields. Helper methods such as Int, Float, String, Bool and Time convert it. Result.Value() returns an interface{} that you must type-assert. Int and Uint read all 64 bits, so large integers are safe.
- Types: String, Number, True, False, Null, or JSON
- Arrays and objects are returned as their raw JSON
- Result.Exists() tells you whether the path matched
Use modifiers and path chaining
Join paths with the pipe character to chain steps. Modifiers are built-in functions that process the JSON, such as @reverse. A modifier can take an optional argument. You can also register your own with gjson.AddModifier.
- @reverse reverses an array or object members
- @pretty formats JSON; options are sortKeys, indent, prefix and width
- @keys and @values return an object's keys or values
- @flatten flattens an array
- @dig searches for a value without its full path
"children|@reverse|0" >> "Jack"What people use it for
- Pulling a few fields from a large API response without defining structs
- Filtering array elements, such as friends older than 45, with a short query
- Reading JSON Lines input one record at a time
- Reshaping output with built-in modifiers like @pretty or @keys
Frequently asked questions
How do I install gjson?
Install Go, then run go get -u github.com/tidwall/gjson. The README says this retrieves the library for use in your Go project.
Is gjson free to use?
gjson is released under the MIT licence, as stated in its project information. Check the LICENSE file in the repository for the full terms.
Can gjson modify JSON?
No. gjson focuses on reading values. The README points to the separate SJSON project for modifying JSON.
Can I use gjson outside Go?
The README mentions Python and Rust ports, but those are maintained separately and are not this Go package.
Does gjson validate a JSON schema or map to structs?
No. gjson is built around path-based lookups, not full schema validation or typed mapping of whole documents. Use encoding/json or a similar tool for those needs.
What is the difference between gjson and encoding/json?
encoding/json decodes a whole document into Go types. gjson reads specific values by path without struct definitions, which suits simple lookups on large payloads.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use gjson if you are a Go developer who needs a few values from JSON quickly and does not want to write structs. Pick something else if you need to modify JSON (look at SJSON), need full schema validation, or work in a language other than Go.
Install options & downloads