Go JSONPath

中文文档

A complete Go implementation of JSONPath that fully complies with RFC 9535. Provides both a command-line tool and a Go library with support for all standard JSONPath features.

Features

• RFC 9535 Compliant - Passes all 703 compliance tests
• Complete JSONPath Support
  • Root node access ($)
  • Child node access (.key or ['key'])
  • Recursive descent (..)
  • Array indices ([0], [-1])
  • Array slices ([start:end:step])
  • Array wildcards ([*])
  • Multiple indices ([1,2,3])
  • Multiple field names (['name','age'])
  • Filter expressions ([?(@.price < 10)])
  • Existence tests ([?@.name])
  • Function calls (length(), count(), match(), search(), value())
• Command Line Tool (jp)
  • Beautiful colorized output
  • Syntax highlighting for JSON
  • File and stdin input support
  • Formatted and compact output options
  • Normalized Path output (--path)
• Go Library
  • Clean API with NodeList return type
  • Normalized Path for each result node
  • Type-safe operations
  • Comprehensive documentation

Installation

Homebrew (Recommended)

brew tap davidhoo/tap
brew install jsonpath

Go Install

go install github.com/davidhoo/jsonpath/cmd/jp@latest

Manual Installation

Download the appropriate binary for your platform from the releases page.

Command Line Usage

jp [-p <jsonpath_expression>] [-f <json_file>] [-c] [--no-color] [--path]

Options:

Flag	Description
-p	JSONPath expression (if not specified, output entire JSON)
-f	JSON file path (reads from stdin if not specified)
-c	Compact output (no formatting)
--no-color	Disable colored output
--path	Output Normalized Path with each result
-h	Show help information
-v	Show version information

Examples

# Output entire JSON with syntax highlighting
jp -f data.json

# Query specific path
jp -f data.json -p '$.store.book[*].author'

# Filter with conditions
jp -f data.json -p '$.store.book[?(@.price > 10)]'

# Read from stdin
echo '{"name": "John"}' | jp -p '$.name'

# Compact output
jp -f data.json -c

# Show Normalized Paths
echo '{"a":1,"b":2}' | jp --path '$.*'
# Output:
# $['a'] 1
# $['b'] 2

Go Library Usage

Basic Usage

import "github.com/davidhoo/jsonpath"

// Query JSON data - returns NodeList
result, err := jsonpath.Query(data, "$.store.book[*].author")
if err != nil {
    log.Fatal(err)
}

// Handle result (NodeList)
for _, node := range result {
    fmt.Printf("Location: %s, Value: %v\n", node.Location, node.Value)
}

Complete Example

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "github.com/davidhoo/jsonpath"
)

func main() {
    data := `{
        "store": {
            "book": [
                {"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95},
                {"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99}
            ]
        }
    }`

    var v interface{}
    if err := json.Unmarshal([]byte(data), &v); err != nil {
        log.Fatal(err)
    }

    result, err := jsonpath.Query(v, "$.store.book[?(@.price < 10)].title")
    if err != nil {
        log.Fatal(err)
    }

    for _, node := range result {
        fmt.Println(node.Value) // Sayings of the Century
    }
}

Common Query Examples

// Get all prices (recursive descent)
"$..price"

// Get books with specific price range
"$.store.book[?(@.price < 10)].title"

// Get all authors
"$.store.book[*].author"

// Get first/last book
"$.store.book[0]"
"$.store.book[-1]"

// Get first two books
"$.store.book[0:2]"

// Complex filter conditions
"$.store.book[?(@.price > 10 && @.category == 'fiction')]"

// Existence test
"$[?@.name]"

// Function calls (RFC 9535)
"$.store.book[?match(@.title, '^S.*')]"
"$.store.book[?search(@.title, 'Century')]"
"$[?count(@..*) > 5]"

// Non-standard extensions
"$.store.book[*].price.min()"
"$.store.book[*].price.max()"
"$.store.book[*].price.avg()"
"$.store.book[*].price.sum()"

Result Handling

Query() returns a NodeList (slice of Node). Each Node has:

• Location - Normalized Path (e.g., $['store']['book'][0])
• Value - The actual value

for _, node := range result {
    fmt.Printf("Location: %s\n", node.Location)
    fmt.Printf("Value: %v\n", node.Value)
}

// Access first result
if len(result) > 0 {
    firstValue := result[0].Value
}

RFC 9535 Compliance

This implementation fully complies with RFC 9535:

• 100% pass rate on the official compliance test suite (703/703)
• All standard selectors (name, index, slice, wildcard, filter, recursive descent, union)
• All standard functions (length, count, match, search, value)
• I-Regexp pattern matching (RFC 9485)
• Normalized Path generation
• Three-valued logic in filter expressions

See RFC9535_COMPLIANCE_REPORT.md for detailed compliance information.

Non-Standard Extensions

The following functions are non-standard extensions for convenience:

Function	Description
keys()	Returns sorted keys of an object
values()	Returns values of an object
min()	Returns minimum value in an array
max()	Returns maximum value in an array
avg()	Returns average of numeric values
sum()	Returns sum of numeric values
occurrences()	Counts occurrences of a value in an array

Testing

# Run all tests
go test -v ./...

# Run tests with coverage
go test -v -coverprofile=coverage.out ./...

# Run benchmarks
go test -bench=. -benchmem ./...

# Run RFC 9535 compliance tests
go test -run TestCTS -v

Contributing

Issues and Pull Requests are welcome!

License

MIT License

Changelog

See CHANGELOG.md for release history.