gjson

package module
v1.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 2, 2024 License: MIT Imports: 8 Imported by: 8,451

README

GJSON
GoDoc GJSON Playground GJSON Syntax

get json values quickly

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

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 the GetMany function to get multiple values at once, and 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 '\'.

{
  "name": {"first": "Tom", "last": "Anderson"},
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
    {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
    {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
    {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
  ]
}

"name.last"          >> "Anderson"
"age"                >> 37
"children"           >> ["Sara","Alex","Jack"]
"children.#"         >> 3
"children.1"         >> "Alex"
"child*.2"           >> "Jack"
"c?ildren.0"         >> "Sara"
"fav\.movie"         >> "Deer Hunter"
"friends.#.first"    >> ["Dale","Roger","Jane"]
"friends.1.last"     >> "Craig"

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.

friends.#(last=="Murphy").first    >> "Dale"
friends.#(last=="Murphy")#.first   >> ["Dale","Jane"]
friends.#(age>45)#.last            >> ["Craig","Murphy"]
friends.#(first%"D*").last         >> "Murphy"
friends.#(first!%"D*").last        >> "Craig"
friends.#(nets.#(=="fb"))#.first   >> ["Dale","Roger"]

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:

result.Exists() bool
result.Value() interface{}
result.Int() int64
result.Uint() uint64
result.Float() float64
result.String() string
result.Bool() bool
result.Time() time.Time
result.Array() []gjson.Result
result.Map() map[string]gjson.Result
result.Get(path string) Result
result.ForEach(iterator func(key, value Result) bool)
result.Less(token Result, caseSensitive bool) bool

The result.Value() function returns an interface{} which requires type assertion and is one of the following Go types:

boolean >> bool
number  >> float64
string  >> string
null    >> nil
array   >> []interface{}
object  >> map[string]interface{}

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:

"children|@reverse"           >> ["Jack","Alex","Sara"]
"children|@reverse|0"         >> "Jack"

There are currently the following built-in modifiers:

  • @reverse: Reverse an array or the members of an object.
  • @ugly: Remove all whitespace from a json document.
  • @pretty: Make the json document more human readable.
  • @this: Returns the current element. It can be used to retrieve the root element.
  • @valid: Ensure the json document is valid.
  • @flatten: Flattens an array.
  • @join: Joins multiple objects into a single object.
  • @keys: Returns an array of keys for an object.
  • @values: Returns an array of values for an object.
  • @tostr: Converts json to a string. Wraps a json string.
  • @fromstr: Converts a string from json. Unwraps a json string.
  • @group: Groups arrays of objects. See e4fc67c.
  • @dig: Search for a value without providing its entire path. See e8e87f2.
Modifier arguments

A modifier may accept an optional argument. The argument can be a valid JSON document or just characters.

For example, the @pretty modifier takes a json object as its argument.

@pretty:{"sortKeys":true}

Which makes the json pretty and orders all of its keys.

{
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
    {"age": 44, "first": "Dale", "last": "Murphy"},
    {"age": 68, "first": "Roger", "last": "Craig"},
    {"age": 47, "first": "Jane", "last": "Murphy"}
  ],
  "name": {"first": "Tom", "last": "Anderson"}
}

The full list of @pretty options are sortKeys, indent, prefix, and width. Please see Pretty Options for more information.

Custom modifiers

You can also add custom modifiers.

For example, here we create a modifier that makes the entire json document upper or lower case.

gjson.AddModifier("case", func(json, arg string) string {
  if arg == "upper" {
    return strings.ToUpper(json)
  }
  if arg == "lower" {
    return strings.ToLower(json)
  }
  return json
})

"children|@case:upper"           >> ["SARA","ALEX","JACK"]
"children|@case:lower|@reverse"  >> ["jack","alex","sara"]

JSON Lines

There's support for JSON Lines using the .. prefix, which treats a multilined document as an array.

For example:

{"name": "Gilbert", "age": 61}
{"name": "Alexa", "age": 34}
{"name": "May", "age": 57}
{"name": "Deloise", "age": 44}

..#                   >> 4
..1                   >> {"name": "Alexa", "age": 34}
..3                   >> {"name": "Deloise", "age": 44}
..#.name              >> ["Gilbert","Alexa","May","Deloise"]
..#(name="May").age   >> 57

The ForEachLines function will iterate through JSON lines.

gjson.ForEachLine(json, func(line gjson.Result) bool{
    println(line.String())
    return true
})

Get nested array values

Suppose you want all the last names from the following json:

{
  "programmers": [
    {
      "firstName": "Janet", 
      "lastName": "McLaughlin", 
    }, {
      "firstName": "Elliotte", 
      "lastName": "Hunter", 
    }, {
      "firstName": "Jason", 
      "lastName": "Harold", 
    }
  ]
}

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:

gjson.Parse(json).Get("name").Get("last")
gjson.Get(json, "name").Get("last")
gjson.Get(json, "name.last")

Check for the existence of a value

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

BenchmarkGJSONGet-10             17893731    202.1 ns/op      0 B/op     0 allocs/op
BenchmarkGJSONUnmarshalMap-10     1663548   2157 ns/op     1920 B/op    26 allocs/op
BenchmarkJSONUnmarshalMap-10       832236   4279 ns/op     2920 B/op    68 allocs/op
BenchmarkJSONUnmarshalStruct-10   1076475   3219 ns/op      920 B/op    12 allocs/op
BenchmarkJSONDecoder-10            585729   6126 ns/op     3845 B/op   160 allocs/op
BenchmarkFFJSONLexer-10           2508573   1391 ns/op      880 B/op     8 allocs/op
BenchmarkEasyJSONLexer-10         3000000    537.9 ns/op    501 B/op     5 allocs/op
BenchmarkJSONParserGet-10        13707510    263.9 ns/op     21 B/op     0 allocs/op
BenchmarkJSONIterator-10          3000000    561.2 ns/op    693 B/op    14 allocs/op

JSON document used:

{
  "widget": {
    "debug": "on",
    "window": {
      "title": "Sample Konfabulator Widget",
      "name": "main_window",
      "width": 500,
      "height": 500
    },
    "image": { 
      "src": "Images/Sun.png",
      "hOffset": 250,
      "vOffset": 250,
      "alignment": "center"
    },
    "text": {
      "data": "Click Here",
      "size": 36,
      "style": "bold",
      "vOffset": 100,
      "alignment": "center",
      "onMouseUp": "sun1.opacity = (sun1.opacity / 100) * 90;"
    }
  }
}

Each operation was rotated through one of the following search paths:

widget.window.name
widget.image.hOffset
widget.text.onMouseUp

**

These benchmarks were run on a MacBook Pro M1 Max using Go 1.22 and can be found here.

Documentation

Overview

Package gjson provides searching for json strings.

Index

Constants

This section is empty.

Variables

View Source 
var DisableEscapeHTML = false

DisableEscapeHTML will disable the automatic escaping of certain "problamatic" HTML characters when encoding to JSON. These character include '>', '<' and '&', which get escaped to \u003e, \u0026, and \u003c respectively.

This is a global flag and will affect all further gjson operations. Ideally, if used, it should be set one time before other gjson functions are called.

View Source 
var DisableModifiers = false

DisableModifiers will disable the modifier syntax

Functions

func AddModifier added in v1.2.0 

func AddModifier(name string, fn func(json, arg string) string)

AddModifier binds a custom modifier command to the GJSON syntax. This operation is not thread safe and should be executed prior to using all other gjson function.

func AppendJSONString added in v1.14.1 

func AppendJSONString(dst []byte, s string) []byte

AppendJSONString is a convenience function that converts the provided string to a valid JSON string and appends it to dst.

func Escape added in v1.17.0 

func Escape(comp string) string

Escape returns an escaped path component. 

json := `{
  "user":{
     "first.name": "Janet",
     "last.name": "Prichard"
   }
}`
user := gjson.Get(json, "user")
println(user.Get(gjson.Escape("first.name"))
println(user.Get(gjson.Escape("last.name"))
// Output:
// Janet
// Prichard

func ForEachLine added in v1.1.0 

func ForEachLine(json string, iterator func(line Result) bool)

ForEachLine iterates through lines of JSON as specified by the JSON Lines format (http://jsonlines.org/). Each line is returned as a GJSON Result.

func ModifierExists added in v1.2.0 

func ModifierExists(name string, fn func(json, arg string) string) bool

ModifierExists returns true when the specified modifier exists.

func Valid 

func Valid(json string) bool

Valid returns true if the input is valid json. 

if !gjson.Valid(json) {
	return errors.New("invalid json")
}
value := gjson.Get(json, "name.last")

func ValidBytes added in v1.1.1 

func ValidBytes(json []byte) bool

ValidBytes returns true if the input is valid json. 

if !gjson.Valid(json) {
	return errors.New("invalid json")
}
value := gjson.Get(json, "name.last")

If working with bytes, this method preferred over ValidBytes(string(data))

Types

type Result 

type Result struct {
	// Type is the json type
	Type Type
	// Raw is the raw json
	Raw string
	// Str is the json string
	Str string
	// Num is the json number
	Num float64
	// Index of raw value in original json, zero means index unknown
	Index int
	// Indexes of all the elements that match on a path containing the '#'
	// query character.
	Indexes []int
}

Result represents a json value that is returned from Get().

func Get 

func Get(json, path string) Result

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.

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 character can be escaped with '\'. 

{
  "name": {"first": "Tom", "last": "Anderson"},
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "friends": [
    {"first": "James", "last": "Murphy"},
    {"first": "Roger", "last": "Craig"}
  ]
}
"name.last"          >> "Anderson"
"age"                >> 37
"children"           >> ["Sara","Alex","Jack"]
"children.#"         >> 3
"children.1"         >> "Alex"
"child*.2"           >> "Jack"
"c?ildren.0"         >> "Sara"
"friends.#.first"    >> ["James","Roger"]

This function expects that the json is well-formed, and does not validate. Invalid 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 use the Valid function first.

func GetBytes 

func GetBytes(json []byte, path string) Result

GetBytes searches json for the specified path. If working with bytes, this method preferred over Get(string(data), path)

func GetMany 

func GetMany(json string, path ...string) []Result

GetMany searches json for the multiple paths. The return value is a Result array where the number of items will be equal to the number of input paths.

func GetManyBytes 

func GetManyBytes(json []byte, path ...string) []Result

GetManyBytes searches json for the multiple paths. The return value is a Result array where the number of items will be equal to the number of input paths.

func Parse 

func Parse(json string) Result

Parse parses the json and returns a result.

This function expects that the json is well-formed, and does not validate. Invalid 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 use the Valid function first.

func ParseBytes 

func ParseBytes(json []byte) Result

ParseBytes parses the json and returns a result. If working with bytes, this method preferred over Parse(string(data))

func (Result) Array 

func (t Result) Array() []Result

Array returns back an array of values. If the result represents a null value or is non-existent, 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.

func (Result) Bool 

func (t Result) Bool() bool

Bool returns an boolean representation.

func (Result) Exists 

func (t Result) Exists() bool

Exists returns true if value exists. 

 if gjson.Get(json, "name.last").Exists(){
		println("value exists")
 }

func (Result) Float 

func (t Result) Float() float64

Float returns an float64 representation.

func (Result) ForEach 

func (t Result) ForEach(iterator func(key, value Result) bool)

ForEach iterates through values. If the result represents a non-existent value, then no values will be iterated. If the result is an Object, the iterator will pass the key and value of each item. If the result is an Array, the iterator will only pass the value of each item. If the result is not a JSON array or object, the iterator will pass back one value equal to the result.

func (Result) Get 

func (t Result) Get(path string) Result

Get searches result for the specified path. The result should be a JSON array or object.

func (Result) Int 

func (t Result) Int() int64

Int returns an integer representation.

func (Result) IsArray 

func (t Result) IsArray() bool

IsArray returns true if the result value is a JSON array.

func (Result) IsBool added in v1.14.0 

func (t Result) IsBool() bool

IsBool returns true if the result value is a JSON boolean.

func (Result) IsObject 

func (t Result) IsObject() bool

IsObject returns true if the result value is a JSON object.

func (Result) Less 

func (t Result) Less(token Result, caseSensitive bool) bool

Less return true if a token is less than another token. The caseSensitive parameter is used when the tokens are Strings. The order when comparing two different type is: 

Null < False < Number < String < True < JSON

func (Result) Map 

func (t Result) Map() map[string]Result

Map returns back a map of values. The result should be a JSON object. If the result is not a JSON object, the return value will be an empty map.

func (Result) Path added in v1.11.0 

func (t Result) Path(json string) string

Path returns the original GJSON path for a Result where the Result came from a simple path that returns a single value, like: 

gjson.Get(json, "friends.#(last=Murphy)")

The returned value will be in the form of a JSON string: 

"friends.0"

The param 'json' must be the original JSON used when calling Get.

Returns an empty string if the paths cannot be determined, which can happen when the Result came from a path that contained a multipath, modifier, or a nested query.

func (Result) Paths added in v1.11.0 

func (t Result) Paths(json string) []string

Paths returns the original GJSON paths for a Result where the Result came from a simple query path that returns an array, like: 

gjson.Get(json, "friends.#.first")

The returned value will be in the form of a JSON array: 

["friends.0.first","friends.1.first","friends.2.first"]

The param 'json' must be the original JSON used when calling Get.

Returns an empty string if the paths cannot be determined, which can happen when the Result came from a path that contained a multipath, modifier, or a nested query.

func (Result) String 

func (t Result) String() string

String returns a string representation of the value.

func (Result) Time 

func (t Result) Time() time.Time

Time returns a time.Time representation.

func (Result) Uint 

func (t Result) Uint() uint64

Uint returns an unsigned integer representation.

func (Result) Value 

func (t Result) Value() interface{}

Value returns one of these types: 

bool, for JSON booleans
float64, for JSON numbers
Number, for JSON numbers
string, for JSON string literals
nil, for JSON null
map[string]interface{}, for JSON objects
[]interface{}, for JSON arrays

type Type 

type Type int

Type is Result type 

const (
	// Null is a null json value
	Null Type = iota
	// False is a json false boolean
	False
	// Number is json number
	Number
	// String is a json string
	String
	// True is a json true boolean
	True
	// JSON is a raw block of JSON
	JSON
)

func (Type) String 

func (t Type) String() string

String returns a string representation of the type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.