package module
Version: v0.0.0-...-6fcdcc9 Latest Latest

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

Go to latest
Published: Mar 21, 2018 License: MIT Imports: 8 Imported by: 0



jsonpath is used to pull values out of a JSON document without unmarshalling the string into an object. At the loss of post-parse random access and conversion to primitive types, you gain faster return speeds and lower memory utilization. If the value you want is located near the start of the json, the evaluator will terminate after reaching and recording its destination.

The evaluator can be initialized with several paths, so you can retrieve multiple sections of the document with just one scan. Naturally, when all paths have been reached, the evaluator will early terminate.

For each value returned by a path, you'll also get the keys & indexes needed to reach that value. Use the keys flag to view this in the CLI. The Go package will return an []interface{} of length n with indexes 0 - (n-2) being the keys and the value at index n-1.

go get github.com/JumboInteractiveLimited/jsonpath/cli/jsonpath
cat yourData.json | jsonpath -k -p '$.Items[*].title+'
-f, --file="": Path to json file  
-j, --json="": JSON text  
-k, --keys=false: Print keys & indexes that lead to value  
-p, --path=[]: One or more paths to target in JSON
Go Package

go get github.com/JumboInteractiveLimited/jsonpath

paths, err := jsonpath.ParsePaths(pathStrings ...string) {
eval, err := jsonpath.EvalPathsInBytes(json []byte, paths) 
// OR
eval, err := jsonpath.EvalPathsInReader(r io.Reader, paths)


for {
	if result, ok := eval.Next(); ok {
		fmt.Println(result.Pretty(true)) // true -> show keys in pretty string
	} else {
if eval.Error != nil {
	return eval.Error

eval.Next() will traverse JSON until another value is found. This has the potential of traversing the entire JSON document in an attempt to find one. If you prefer to have more control over traversing, use the eval.Iterate() method. It will return after every scanned JSON token and return ([]*Result, bool). This array will usually be empty, but occasionally contain results.

Path Syntax

All paths start from the root node $. Similar to getting properties in a JavaScript object, a period .title or brackets ["title"] are used.

Syntax Meaning Examples
$ root of doc
. property selector $.Items
["abc"] quoted property selector $["Items"]
* wildcard property name $.*
[n] Nth index of array [0] [1]
[n:m] Nth index to m-1 index (same as Go slicing) [0:1] [2:5]
[n:] Nth index to end of array [1:] [2:]
[*] wildcard index of array [*]
+ get value at end of path $.title+
?(expression) where clause (expression can reference current json node with @) ?(@.title == "ABC")


  • paths (that start from current node @)
  • numbers (integers, floats, scientific notation)
  • mathematical operators (+ - / * ^)
  • numerical comparisos (< <= > >=)
  • logic operators (&& || == !=)
  • parentheses (2 < (3 * 5))
  • static values like (true, false)
  • @.value > 0.5

Example: this will only return tags of all items that match this expression. $.Items[*]?(@.title == "A Tale of Two Cities").tags


				"title": "A Midsummer Night's Dream",  
				"title": "A Tale of Two Cities",  

Example Paths:

jsonpath --file=example.json --path='$.Items[*].tags[*]+' --keys

"Items" 0 "tags" 0 "comedy"
"Items" 0 "tags" 1 "shakespeare"
"Items" 0 "tags" 2 "play"
"Items" 1 "tags" 0 "french"
"Items" 1 "tags" 1 "revolution"
"Items" 1 "tags" 2 "london"

... "A Midsummer Night's Dream"
... "A Tale of Two Cities"

... ["comedy","shakespeare","play"]
... ["french","revolution","london"]

... "comedy"
... "shakespeare"
... "play"
... "french"
... "revolution"
... "london"

... = keys/indexes of path




View Source
const (
	BadStructure         = "Bad Structure"
	NoMoreResults        = "No more results"
	UnexpectedToken      = "Unexpected token in evaluation"
	AbruptTokenStreamEnd = "Token reader is not sending anymore tokens"
View Source
const (
	JsonObject = iota


View Source
var EXPRESSION = lexExprText
View Source
var JSON = lexJsonRoot
View Source
var PATH = lexPathStart


func NewReaderLexer

func NewReaderLexer(rr io.Reader, initial stateFn) *readerLexer

func NewSliceLexer

func NewSliceLexer(input []byte, initial stateFn) *sliceLexer


type Eval

type Eval struct {
	Error error
	// contains filtered or unexported fields

func EvalPathsInBytes

func EvalPathsInBytes(input []byte, paths []*Path) (*Eval, error)

func EvalPathsInReader

func EvalPathsInReader(r io.Reader, paths []*Path) (*Eval, error)

func (*Eval) Iterate

func (e *Eval) Iterate() (*Results, bool)

func (*Eval) Next

func (e *Eval) Next() (*Result, bool)

type Item

type Item struct {
	// contains filtered or unexported fields

type Path

type Path struct {
	// contains filtered or unexported fields

func ParsePaths

func ParsePaths(pathStrings ...string) ([]*Path, error)

type Pos

type Pos int

type Result

type Result struct {
	Keys  []interface{}
	Value []byte
	Type  int

func (*Result) Pretty

func (r *Result) Pretty(showPath bool) string

type Results

type Results struct {
	// contains filtered or unexported fields

func (*Results) Pop

func (q *Results) Pop() *Result

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL