jsonpath

README

JSONPath

JSONPath defines a string syntax for selecting and extracting JSON (RFC 8259) values from within a given JSON value.

Overview

A brief overview of JSONPath syntax.

Syntax Element	Description
$	root node identifier
@	current node identifier (valid only within filter selectors)
[<selectors>]	child segment: selects zero or more children of a node
.name	shorthand for ['name']
.*	shorthand for [*]
..[<selectors>]	descendant segment: selects zero or more descendants of a node
..name	shorthand for ..['name']
..*	shorthand for ..[*]
'name'	name selector: selects a named child of an object
*	wildcard selector: selects all children of a node
3	index selector: selects an indexed child of an array (from 0)
0:100:5	array slice selector: start🔚step for arrays
?<logical-expr>	filter selector: selects particular children using a logical expression
length(@.foo)	function extension: invokes a function in a filter expression

References

• Gössner, S., Ed., Normington, G., Ed., and C. Bormann, Ed., "JSONPath: Query Expressions for JSON", RFC 9535, DOI 10.17487/RFC9535, February 2024, https://www.rfc-editor.org/info/rfc9535.

Documentation

Index

• type NodeList
• type Path
  • func New(query string) (*Path, error)
  • func (p Path) Apply(queryArgument any) NodeList
  • func (p Path) Query() string

Examples

• Path.Apply

Types

type NodeList

type NodeList []any

NodeList is a list of nodes.

type Path

type Path struct {
	// contains filtered or unexported fields
}

Path represents a JSONPath query.

func New

func New(query string) (*Path, error)

New creates a new JSONPath query from the given string.

func (Path) Apply

func (p Path) Apply(queryArgument any) NodeList

Apply applies the JSONPath query to the given argument.

Example

package main

import (
	"encoding/json"
	"fmt"
	"github.com/0x51-dev/jsonpath"
)

func main() {
	example := map[string]any{
		"store": map[string]any{
			"book": []any{
				map[string]any{
					"category": "reference",
					"author":   "Nigel Rees",
					"title":    "Sayings of the Century",
					"price":    8.95,
				},
				map[string]any{
					"category": "fiction",
					"author":   "Evelyn Waugh",
					"title":    "Sword of Honour",
					"price":    12.99,
				},
				map[string]any{
					"category": "fiction",
					"author":   "Herman Melville",
					"title":    "Moby Dick",
					"isbn":     "0-553-21311-3",
					"price":    8.99,
				},
				map[string]any{
					"category": "fiction",
					"author":   "J. R. R. Tolkien",
					"title":    "The Lord of the Rings",
					"isbn":     "0-395-19395-8",
					"price":    22.99,
				},
			},
			"bicycle": map[string]any{
				"color": "red",
				"price": 399,
			},
		},
	}

	// This is just to make the response more readable.
	marshal := func(v []any) string {
		var w any = v
		if len(v) == 1 {
			w = v[0]
		}
		raw, _ := json.Marshal(w)
		return string(raw)
	}

	q, _ := jsonpath.New("$.store.book[*].author")
	fmt.Println("The authors of all books in the store:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$..author")
	fmt.Println("All authors:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$.store")
	fmt.Println("All things in the store, which are some books and a red bicycle:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$.store..price")
	fmt.Println("Prices of everything in the store:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$..book[2]")
	fmt.Println("The third book:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$..book[2].author")
	fmt.Println("The third book's author:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$..book[2].publisher")
	fmt.Println("The third book's publisher:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$..book[-1]")
	fmt.Println("The last book on order:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$..book[0,1]")
	fmt.Println("The first two books:", marshal(q.Apply(example)))
	q, _ = jsonpath.New("$..book[:2]")
	fmt.Println("The first two books:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$..book[?@.isbn]")
	fmt.Println("All books with an ISBN number:", marshal(q.Apply(example)))

	q, _ = jsonpath.New("$..book[?@.price<10]")
	fmt.Println("All books cheaper than 10:", marshal(q.Apply(example)))

}

Output:

The authors of all books in the store: ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]
All authors: ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]
All things in the store, which are some books and a red bicycle: {"bicycle":{"color":"red","price":399},"book":[{"author":"Nigel Rees","category":"reference","price":8.95,"title":"Sayings of the Century"},{"author":"Evelyn Waugh","category":"fiction","price":12.99,"title":"Sword of Honour"},{"author":"Herman Melville","category":"fiction","isbn":"0-553-21311-3","price":8.99,"title":"Moby Dick"},{"author":"J. R. R. Tolkien","category":"fiction","isbn":"0-395-19395-8","price":22.99,"title":"The Lord of the Rings"}]}
Prices of everything in the store: [399,8.95,12.99,8.99,22.99]
The third book: {"author":"Herman Melville","category":"fiction","isbn":"0-553-21311-3","price":8.99,"title":"Moby Dick"}
The third book's author: "Herman Melville"
The third book's publisher: null
The last book on order: {"author":"J. R. R. Tolkien","category":"fiction","isbn":"0-395-19395-8","price":22.99,"title":"The Lord of the Rings"}
The first two books: [{"author":"Nigel Rees","category":"reference","price":8.95,"title":"Sayings of the Century"},{"author":"Evelyn Waugh","category":"fiction","price":12.99,"title":"Sword of Honour"}]
The first two books: [{"author":"Nigel Rees","category":"reference","price":8.95,"title":"Sayings of the Century"},{"author":"Evelyn Waugh","category":"fiction","price":12.99,"title":"Sword of Honour"}]
All books with an ISBN number: [{"author":"Herman Melville","category":"fiction","isbn":"0-553-21311-3","price":8.99,"title":"Moby Dick"},{"author":"J. R. R. Tolkien","category":"fiction","isbn":"0-395-19395-8","price":22.99,"title":"The Lord of the Rings"}]
All books cheaper than 10: [{"author":"Nigel Rees","category":"reference","price":8.95,"title":"Sayings of the Century"},{"author":"Herman Melville","category":"fiction","isbn":"0-553-21311-3","price":8.99,"title":"Moby Dick"}]

func (Path) Query

func (p Path) Query() string

Query returns the query string.