6.3 KiB

Raw Blame History

GJSON Path Syntax

A GJSON Path is a text string syntax that describes a search pattern for quickly retreiving values from a JSON payload.

This document is designed to explain the structure of a GJSON Path through examples.

Path structure
Basic
Wildcards
Escape Character
Arrays
Queries
Dot vs Pipe
Modifiers

The definitive implemenation is github.com/tidwall/gjson.

Path structure

A GJSON Path is intended to be easily expressed as a series of components seperated by a . character.

Along with . character, there are a few more that have special meaning, including |, #, @, \, *, and ?.

Example

Given this JSON

{
  "name": {"first": "Tom", "last": "Anderson"},
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
    {"first": "Dale", "last": "Murphy", "age": 44},
    {"first": "Roger", "last": "Craig", "age": 68},
    {"first": "Jane", "last": "Murphy", "age": 47}
  ]
}

The following GJSON Paths evaluate to the accompanying values.

Basic

In many cases you'll just want to retreive values by object name or array index.

name.last              "Anderson"
name.first             "Tom"
age                    37
children               ["Sara","Alex","Jack"]
children.0             "Sara"
children.1             "Alex"
friends.1              {"first": "Roger", "last": "Craig", "age": 68}
friends.1.first        "Roger"

Wildcards

A key may contain the special wildcard characters * and ?. The * will match on any zero+ characters, and ? matches on any one character.

child*.2               "Jack"
c?ildren.0             "Sara"

Escape character

Special purpose characters, such as ., *, and ? can be escaped with \.

fav\.movie             "Deer Hunter"

Arrays

The # character allows for digging into JSON Arrays.

To get the length of an array you'll just use the # all by itself.

friends.#              3
friends.#.age         [44,68,47]

Queries

You can also query an array for the first match by using #[...], or find all matches with #[...]#. Queries support the ==, !=, <, <=, >, >= comparison operators, and the simple pattern matching % (like) and !% (not like) operators.

friends.#[last=="Murphy"].first     "Dale"
friends.#[last=="Murphy"]#.first    ["Dale","Jane"]
friends.#[age>45]#.last             ["Craig","Murphy"]
friends.#[first%"D*"].last          "Murphy"
friends.#[first!%"D*"].last         "Craig"

To query for a non-object value in an array, you can forgo the string to the right of the operator.

children.#[!%"*a*"]                 "Alex"
children.#[%"*a*"]#                 ["Sara","Jack"]

Dot vs Pipe

The . is standard separator, but it's also possible to use a |. In most cases they both end up returning the same results. The cases where| differs from . is when it's used after the # for Arrays and Queries.

Here are some examples

friends.0.first                     "Dale"
friends|0.first                     "Dale"
friends.0|first                     "Dale"
friends|0|first                     "Dale"
friends|#                           3
friends.#                           3
friends.#[last="Murphy"]#           [{"first": "Dale", "last": "Murphy", "age": 44},{"first": "Jane", "last": "Murphy", "age": 47}]
friends.#[last="Murphy"]#.first     ["Dale","Jane"]
friends.#[last="Murphy"]#|first     <non-existent>
friends.#[last="Murphy"]#.0         []
friends.#[last="Murphy"]#|0         {"first": "Dale", "last": "Murphy", "age": 44}
friends.#[last="Murphy"]#.#         []
friends.#[last="Murphy"]#|#         2

Let's break down a few of these.

The path friends.#[last="Murphy"]# all by itself results in

[{"first": "Dale", "last": "Murphy", "age": 44},{"first": "Jane", "last": "Murphy", "age": 47}]

The .first suffix will process the first path on each array element before returning the results. Which becomes

["Dale","Jane"]

But the |first suffix actually processes the first path after the previous result. Since the previous result is an array, not an object, it's not possible to process because first does not exist.

Yet, |0 suffix returns

{"first": "Dale", "last": "Murphy", "age": 44}

Because 0 is the first index of the previous result.

Modifiers

A modifier is a path component that performs custom processing on the JSON.

For example, using the built-in @reverse modifier on the above JSON payload will reverse the children array:

children.@reverse                   ["Jack","Alex","Sara"]
children.@reverse.0                 "Jack"

There are currently three built-in modifiers:

@reverse: Reverse an array or the members of an object.
@ugly: Remove all whitespace from JSON.
@pretty: Make the JSON more human readable.

Modifier arguments

A modifier may accept an optional argument. The argument can be a valid JSON payload or just characters.

For example, the @pretty modifier takes a json object as its argument.

@pretty:{"sortKeys":true}

Which makes the json pretty and orders all of its keys.

{
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
    {"age": 44, "first": "Dale", "last": "Murphy"},
    {"age": 68, "first": "Roger", "last": "Craig"},
    {"age": 47, "first": "Jane", "last": "Murphy"}
  ],
  "name": {"first": "Tom", "last": "Anderson"}
}

The full list of @pretty options are sortKeys, indent, prefix, and width. Please see Pretty Options for more information.

Custom modifiers

You can also add custom modifiers.

For example, here we create a modifier which makes the entire JSON payload upper or lower case.

gjson.AddModifier("case", func(json, arg string) string {
  if arg == "upper" {
    return strings.ToUpper(json)
  }
  if arg == "lower" {
    return strings.ToLower(json)
  }
  return json
})
"children.@case:upper"             ["SARA","ALEX","JACK"]
"children.@case:lower.@reverse"    ["jack","alex","sara"]

6.3 KiB Raw Blame History