jsonpath

JSONPath

A Go implementation of RFC 9535 JSONPath with compliance-suite coverage, located results, and typed filter function extensions

Features

• RFC 9535 JSONPath: Parses and evaluates standard JSONPath expressions against Go JSON values.
• Compiled paths: Reuse Path values safely across documents and goroutines.
• Go-native selection: Query decoded any, []any, map[string]any, strings, numbers, booleans, and nil.
• JSON helpers: Query []byte and io.Reader inputs with QueryJSON* convenience functions.
• Located results: Return immutable NormalizedPath values alongside matched nodes.
• Typed function extensions: Register custom filter functions with explicit Value, Logical, and Nodes runtime values.
• Structured diagnostics: Inspect parse failures with errors.Is and errors.As.

Installation

go get github.com/agentable/jsonpath

Requires Go 1.26.5+.

Quick Start

package main

import (
	"fmt"
	"log"

	"github.com/agentable/jsonpath"
)

func main() {
	path, err := jsonpath.Parse("$.store.book[*].author")
	if err != nil {
		log.Fatal(err)
	}

	data := map[string]any{
		"store": map[string]any{
			"book": []any{
				map[string]any{"author": "Nigel Rees"},
				map[string]any{"author": "Evelyn Waugh"},
			},
		},
	}

	for author := range path.Select(data).All() {
		fmt.Println(author)
	}
}

API Overview

See pkg.go.dev/github.com/agentable/jsonpath for complete package documentation.

Valid(expr) checks whether Parse(expr) succeeds with the default built-in functions; use NewParser and Parser.Parse for expressions that rely on custom functions. QueryJSON* helpers preserve JSON numbers as encoding/json.Number; invalid Path values fail with ErrInvalidPath before reading or decoding. Callers that need another number representation, decoder policy, or streaming behavior should decode outside this package and then call Path.Select or Path.SelectLocated.

Filter comparison preserves the exact magnitude of Go integer types and the exact decimal value of encoding/json.Number. Finite float32 and float64 values supplied to Select compare by their exact binary value. Invalid json.Number text, NaN, and infinities are outside the decoded-JSON numeric domain and are not comparable.

Core Concepts

Compiled Paths

Compile once, select many times:

path := jsonpath.MustParse("$['store']['book'][*]['title']")
titles := path.Select(data)

Path.String() and Path.MarshalText() return a stable, canonical JSONPath string for the compiled query. The zero Path value is invalid; String() returns an empty string and MarshalText() returns ErrInvalidPath.

Located Results

Use located queries when you need both the value and its RFC 9535 normalized path.

src := []byte(`{"store":{"book":[{"title":"Moby Dick"},{"title":"1984"}]}}`)
path := jsonpath.MustParse("$.store.book[*].title")

located, err := jsonpath.QueryJSONLocated(src, path)
if err != nil {
	log.Fatal(err)
}

for node := range located.All() {
	fmt.Printf("%s -> %s = %v\n", node.Path, node.Path.Pointer(), node.Value)
}

NormalizedPath is immutable. NewNormalizedPath and Append reject nil elements and negative indexes with ErrInvalidPath. Read elements through Element or Elements. LocatedNodeList is a nodelist in query order, not a set. Use Values and Paths to iterate just values or paths. Sort and Deduplicate are caller opt-in operations; Deduplicate is path-based, keeps the first node for each path, and ignores value equality.

path, err := jsonpath.NewNormalizedPath(
	jsonpath.NameElement("store"),
	jsonpath.NameElement("book"),
	jsonpath.IndexElement(0),
)
if err != nil {
	log.Fatal(err)
}

fmt.Println(path.String())  // $['store']['book'][0]
fmt.Println(path.Pointer()) // /store/book/0

Parse Diagnostics

Parse failures satisfy ErrPathParse. Function lookup, validation, and registration failures also satisfy ErrFunction. JSON decode failures from QueryJSON* wrap ErrUnmarshal, and invalid compiled paths return ErrInvalidPath.

_, err := jsonpath.Parse(" $.store")

var parseErr *jsonpath.ParseError
if errors.As(err, &parseErr) {
	fmt.Println(errors.Is(err, jsonpath.ErrPathParse))
	fmt.Println(parseErr.Offset)
	fmt.Println(parseErr.Reason)
}

Function Extensions

Register custom filter functions with NewParser(jsonpath.WithFunctions(...)). Invalid function options fail at parser construction with ErrFunction. Runtime arguments and return values are typed:

• jsonpath.Value: one JSON value or NoValue
• jsonpath.Logical: boolean test result
• jsonpath.Nodes: node list result

Functions have one immutable name, fixed parameter list, result category, and callback. The parser validates argument conversions from that signature; callbacks receive only typed runtime values. Return NoValue, Logical(false), or an empty Nodes value for runtime absence. FuncLogical parameters accept the same comparisons, test expressions, negation, conjunction, disjunction, and parentheses used by filters.

hasPrefix := jsonpath.NewLogicalFunction(
	"has_prefix",
	[]jsonpath.FuncType{jsonpath.FuncValue, jsonpath.FuncValue},
	func(args []jsonpath.FunctionValue) jsonpath.Logical {
		value, ok := args[0].(jsonpath.Value)
		if !ok || value.IsNothing() {
			return jsonpath.Logical(false)
		}
		prefix, ok := args[1].(jsonpath.Value)
		if !ok || prefix.IsNothing() {
			return jsonpath.Logical(false)
		}

		s, ok := value.Any().(string)
		p, ok2 := prefix.Any().(string)
		return jsonpath.Logical(ok && ok2 && strings.HasPrefix(s, p))
	},
)

parser, err := jsonpath.NewParser(jsonpath.WithFunctions(hasPrefix))
if err != nil {
	log.Fatal(err)
}
path, err := parser.Parse(`$[?has_prefix(@.sku, "book-")]`)
if err != nil {
	log.Fatal(err)
}

Use NewValueFunction, NewLogicalFunction, or NewNodesFunction according to the result category. WithFunctions rejects zero-value definitions, nil callbacks, invalid names or parameter types, duplicates, and built-in collisions when NewParser is called. Function names use RFC function-name grammar: a lowercase ASCII letter followed by lowercase ASCII letters, digits, or underscores.

Performance

The package includes benchmarks for selector execution, located queries, filter evaluation, normalized-path construction, JSON decoding, and PGO workflows.

task bench
go test -run '^$' -bench 'Benchmark(Select_|SelectLocated_|QueryJSON|ExtendPath|ParserParse)' -benchmem -count=10 .
task pgo:generate
task bench-pgo

Compare results only when the machine, Go toolchain, PGO mode, benchmark regex, and repetition count are identical.

Regenerate default.pgo only when representative query hot paths change materially.

Development

task fmt        # format code
task lint       # tidy-lint + golangci-lint
task test       # go test -race ./...
task vet        # go vet ./...
task verify     # deps + fmt + vet + lint + test + vuln

For development conventions and repository workflow, see CLAUDE.md.

Contributing

Run task fmt, task lint, and task test before submitting changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.