tidwall / gjson

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 : 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. This will print: *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 , , , and . Arrays and Objects are returned as their raw json types. The type holds one of these: To directly access the value: There are a variety of handy functions that work on a result: The function returns an which requires type assertion and is one of the following Go types: The 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 and calls are capable of reading all 64 bits, allowing for large JSON integers. 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 modifier on the above json document, we'll get array and reverse the order: There are currently the following built-in modifiers: • : Reverse an array or the members of an object. • : Remove all whitespace from a json document. • : Make the json document more human readable. • : Returns the current element. It can be used to retrieve the root element. • : Ensure the json document is valid. • : Flattens an array. • : Joins multiple objects into a single object. • : Returns an array of keys for an object. • : Returns an array of values for an object. • : Converts json to a string. Wraps a json string. • : Converts a string from json. Unwraps a json string. • : Groups arrays of objects. See e4fc67c. • : 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 modifier takes a json object as its argument. Which makes the json pretty and orders all of its keys. *The full list of options are , , , and . 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. JSON Lines There's support for JSON Lines using the prefix, which treats a multilined document as an array. For example: The function will iterate through JSON lines. Get nested array values Suppose you want all the last names from the following json: You would use the path "programmers.#.lastName" like such: You can also query an object inside an array: Iterate through an object or array The 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 from an iterator will stop iteration. Simple Parse and Get There's a function that will do a simple parse, and that will search a result. For example, all of these will return the same result: Check for the existence of a value Sometimes you just want to know if a value exists. Validate JSON The and 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. Unmarshal to a map To unmarshal to a : Working with Bytes If your JSON is contained in a slice, there's the GetBytes function. This is preferred over . If you are using the function and you want to avoid converting to a , then you can use this pattern: This is a best-effort no allocation sub slice of the original json. This method utilizes the field, which is the position of the raw data in the original json. It's possible that the value of equals zero, in which case the is converted to a . Performance Benchmarks of GJSON alongside encoding/json, ffjson, EasyJSON, jsonparser, and json-iterator JSON document used: Each operation was rotated through one of the following search paths: ** *These benchmarks were run on a MacBook Pro M1 Max using Go 1.22 and can be found here.*