AsaiYusuke/JSONPath

This Go library allows you to extract parts of a JSON object using the JSONPath query syntax.

The core JSONPath syntax supported by this library is based on:

• Stefan Gössner's JSONPath - XPath for JSON
• Christoph Burgmer's json-path-comparison
• JSONPath Internet Draft Development

Note

For details on syntax compatibility with other libraries, see :memo: my comparison results.

Table of Contents

• Getting started
• Basic design
• How to use
  • Retrieve one-time or repeated
  • Error handling
  • Function syntax
  • Accessing JSON
• Differences
• Benchmarks
• Project progress

Getting started

Install

go get github.com/AsaiYusuke/jsonpath/v2

Simple example

package main

import (
  "encoding/json"
  "fmt"

  "github.com/AsaiYusuke/jsonpath/v2"
)

func main() {
  jsonPath, srcJSON := `$.key`, `{"key":"value"}`
  var src any
  json.Unmarshal([]byte(srcJSON), &src)
  output, _ := jsonpath.Retrieve(jsonPath, src)
  outputJSON, _ := json.Marshal(output)
  fmt.Println(string(outputJSON))
  // Output:
  // ["value"]
}

Basic design

Streamlined Development

• The JSONPath syntax parser is implemented using PEG, which helps keep the source code simple and maintainable.
• Robust unit tests are provided to prevent bugs and ensure consistent results.

User-Friendly Interface

• The library provides comprehensive error types, making it easy for users to handle errors appropriately.

High Compatibility

• The library incorporates consensus behaviors from Christoph Burgmer's json-path-comparison, ensuring high compatibility with other implementations.

How to use

* Retrieve one-time or repeatedly

The Retrieve function extracts values from a JSON object using a JSONPath expression:

output, err := jsonpath.Retrieve(jsonPath, src)

:memo: Example

The Parse function returns a parser function that checks the JSONPath syntax in advance. You can use this parser function to repeatedly extract values with the same JSONPath:

parsed, err := jsonpath.Parse(jsonPath)
output1, err1 := parsed(src1)
output2, err2 := parsed(src2)

:memo: Example

parser function

• The parser function accepts an optional second argument: a pointer to a []any buffer.
• When omitted or nil, a new slice is allocated on each call and returned.
• When provided (non-nil), the buffer will be reset to length 0 and filled directly, enabling reuse without extra allocations.

Example of buffer reuse:

parsed, _ := jsonpath.Parse("$[*]")
buf := make([]any, 0, 4)
args := []*[]any{&buf}
out1, _ := parsed([]any{1}, args...) // writes into buf -> [1]
out2, _ := parsed([]any{2}, args...) // reuses the same buf -> now [2]
fmt.Println(out1)
fmt.Println(out2)
fmt.Println(buf)
  // Output:
  // [2]
  // [2]
  // [2]

:memo: Example

Note: Do not share the same buffer across goroutines concurrently.

* Error handling

If an error occurs during API execution, a specific error type is returned. The following error types help you identify the cause:

Syntax errors from Retrieve or Parse

| Error type | Message format | Symptom | Ex | | ----------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | ErrorInvalidSyntax | invalid syntax (position=%d, reason=%s, near=%s) | The JSONPath contains invalid syntax. The reason in the message provides more details. | :memo: | | ErrorInvalidArgument | invalid argument (argument=%s, error=%s) | An argument in the JSONPath is invalid according to Go syntax. | :memo: | | ErrorFunctionNotFound | function not found (path=%s) | The specified function in the JSONPath was not found. | :memo: | | ErrorNotSupported | not supported (path=%s, feature=%s) | The JSONPath uses unsupported syntax. | :memo: |

Runtime errors from Retrieve or parser functions

| Error type | Message format | Symptom | Ex | | --------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | ErrorMemberNotExist | member did not exist (path=%s) | The specified object or array member does not exist in the JSON object. | :memo: | | ErrorTypeUnmatched | type unmatched (path=%s, expected=%s, found=%s) | The type of the node in the JSON object does not match what is expected by the JSONPath. | :memo: | | ErrorFunctionFailed | function failed (path=%s, error=%s) | The function specified in the JSONPath failed to execute. | :memo: |

Type checking makes it easy to determine which error occurred.

import jsonpath "github.com/AsaiYusuke/jsonpath/v2"
import errors "github.com/AsaiYusuke/jsonpath/v2/errors"

_, err := jsonpath.Retrieve(jsonPath, srcJSON)
switch err.(type) {
case errors.ErrorMemberNotExist:
  fmt.Printf("retry with other srcJSON: %v", err)
  // handle or continue
case errors.ErrorInvalidArgument:
  return nil, fmt.Errorf("specified invalid argument: %v", err)
}

* Function syntax

You can use user-defined functions to format results. The function syntax is appended after the JSONPath expression.

There are two types of functions:

Filter function

A filter function applies a user-defined function to each value in the result, transforming them individually.

:memo: Example

Aggregate function

An aggregate function combines all values in the result into a single value.

:memo: Example

* Accessing JSON

Instead of retrieving values directly, you can obtain accessors (Getters / Setters) for the input JSON. These accessors allow you to update the original JSON object.

Enable this feature by calling Config.SetAccessorMode().

:memo: Example

Accessor limitations

Setters are not available for some results, such as when using function syntax in the JSONPath.

Accessor operations follow Go's map/slice semantics. If you modify the structure of the JSON, be aware that accessors may not behave as expected. To avoid issues, obtain a new accessor each time you change the structure.

Differences

Some behaviors in this library differ from the consensus of other implementations. For a full comparison, see :memo: this result.

These behaviors may change in the future if more appropriate approaches are found.

Character types

The foll