GJSON: High-Performance JSON Retrieval for Go

While . and | are often interchangeable, they behave differently when used after array/query operators (# or #( )):

• Dot (.): Processes the path on each element of the preceding array before returning the results (mapping).
• Pipe (|): Processes the path on the result of the previous operation as a single entity (chaining).

If the previous result is an array, | treats that array as the new target, whereas . treats the elements inside the array as the targets.

// If friends.#(last="Murphy")# returns an array of objects:

friends.#(last="Murphy")#.first     // Returns an array of 'first' names: ["Dale", "Jane"]
friends.#(last="Murphy")#|first     // Returns <non-existent> because it looks for 'first' on the array itself
friends.#(last="Murphy")#|0         // Returns the first object in that array

The # character is used to interact with JSON arrays:

• Use # alone to get the length of an array.
• Use #.key to get an array of values for a specific key from all objects in the array.

friends.#              // Returns the length of the array
friends.#.age         // Returns an array of all 'age' values: [44, 68, 47]

Multipaths allow you to join multiple selected values into a new JSON document. You can wrap comma-separated paths in [...] to create a new array or {...} to create a new object.

• If a key is provided (e.g., "key":path), that key is used.
• If no key is provided, the original field name is used.
• If a name cannot be determined, _ is used.

// Creates a new object with specific fields
{name.first,age,"the_murphys":friends.#(last="Murphy")#.first}

// Results in:
// {"first":"Tom","age":37,"the_murphys":["Dale","Jane"]}

You can use wildcard characters to match keys within a JSON structure:

• *: Matches any zero or more characters.
• ?: Matches exactly one character.

child*.2               // Matches any key starting with 'child' and returns its 3rd element
c?ildren.0             // Matches 'children' with one character variation

GJSON uses a dot-separated path syntax to navigate JSON.

Basic Navigation

• Dot notation: name.last accesses nested keys.
• Array index: children.1 accesses the second element of an array.
• Wildcards: * and ? can be used for pattern matching.
• Array length/Child access: Use # to get the number of elements in an array or to access a child path.
• Escaping: Use \ to escape dots or wildcards in keys (e.g., fav\.movie).

Advanced Queries

Use #(...) to query an array:

• First match: friends.#(last=="Murphy").first returns the first match.
• All matches: friends.#(last=="Murphy")#.first returns all matching elements.

Supported Operators:

• Comparison: ==, !=, <, <=, >, >=
• Pattern matching: % (like) and !% (not like)

Starting with v1.12.0, you can use JSON literals within multipaths to construct static blocks of JSON. A literal begins with the ! character.

// Constructing a document with static values
{name.first,age,"company":!"Happysoft","employed":!true}

// Results in:
// {"first":"Tom","age":37,"company":"Happysoft","employed":true}

Use gjson.Get(json, path) to search a JSON document for a specific value. The path uses dot syntax (e.g., name.last or age). When the value is found, it is returned immediately as a gjson.Result.

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())
}

To use GJSON in your Go project, install the library using the following command:

$ go get -u github.com/tidwall/gjson

Special characters like ., *, and ? can be escaped using a backslash \.

Important: When hardcoding paths in source code, you must account for the language's own string escaping rules. In Go and Rust, you must escape the backslash itself if using standard double-quoted strings.

// Go: must escape the slash for the string literal
val := gjson.Get(json, "fav\\.movie") 

// Go: no need to escape the slash when using raw string literals
val := gjson.Get(json, `fav\.movie`) 

// Rust: must escape the slash
let val = gjson::get(json, "fav\\.movie")

// Rust: no need to escape the slash with raw strings
let val = gjson::get(json, r#"fav\.movie"#)

To avoid allocating a new byte slice when accessing result.Raw from a gjson.GetBytes call, you can use the result.Index field to create a sub-slice of the original JSON. This is a best-effort approach to achieve zero allocations. Note that if result.Index is 0, you must fall back to converting result.Raw to a []byte.

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)
}