JSONPath Cheat Sheet: Syntax and Tested Examples

What JSONPath is

JSONPath is a query language for picking values out of a JSON document. $.store.books[0].title reads like a path in code, but JSONPath also has wildcards, slices and filters, so one expression can pull the same field out of every element of an array.

You meet it in Postman tests, kubectl -o jsonpath, AWS Step Functions, API gateways and many low-code integration tools. For years every implementation worked from Stefan Goessner's 2007 article and filled its gaps differently. In February 2024 the IETF published RFC 9535, which standardized the syntax for the first time.

This cheat sheet uses RFC 9535 syntax. Every result shown was produced by running the expression against the sample document below, not written by hand.

The sample document

Every example runs against this order response. It has nested arrays, a field that only some orders have (giftMessage), an empty array, and two keys that break dot notation (x-request-id and rate.limit).

{
  "store": "Northwind Books",
  "orders": [
    {
      "id": "ord_1001",
      "status": "shipped",
      "total": 249.99,
      "items": [{ "sku": "KB-204", "qty": 1 }, { "sku": "MS-310", "qty": 2 }]
    },
    {
      "id": "ord_1002",
      "status": "pending",
      "total": 15.5,
      "giftMessage": "Happy birthday",
      "items": [{ "sku": "CB-001", "qty": 3 }]
    },
    {
      "id": "ord_1003",
      "status": "shipped",
      "total": 89,
      "items": []
    }
  ],
  "meta": { "page": 1, "x-request-id": "req_7f3a9c21", "rate.limit": 100 }
}

Results come from jsonpath-rfc9535 2.0.0, a Python implementation of the standard. Where the popular JavaScript library jsonpath-plus 10.4.0 gives a different answer, the section on disagreements says so.

The cheat sheet

Two rules explain most surprises:

• A query always returns a list. One match is a list of one. No match is an empty list, not an error, so a typo in a field name fails silently.
• Object order is not promised. The standard does not fix the order of $.meta.* results. Arrays keep their order.

Filters

A filter keeps the elements for which a condition is true. Inside it, @ is the element being tested.

RFC 9535 also defines five functions for use in filters:

The fifth, value(), turns a single-node result into a plain value for comparisons.

Three details catch people out:

• Equality is ==. A single = is a syntax error: unexpected '=', did you mean '=='?
• ?@.giftMessage tests that the field exists, not that it is truthy. Under the standard, a field whose value is null, false or 0 still passes. To find real nulls, write ?@.giftMessage == null.
• match() must match the whole string, while search() finds a match anywhere. match(@.id, 'ord') would match nothing here; search(@.id, 'ord') matches all three.

Bracket notation for awkward keys

Dot notation is shorthand for names made of letters, digits and underscores. Any other key needs brackets and quotes, single or double:

The last row is the dangerous one. It looks for a limit key inside a rate object, finds nothing, and returns an empty list without any error. Whenever a key contains a dot, a space or a hyphen, use brackets.

Some libraries, including both tested here, also accept $.meta.x-request-id. The standard's grammar does not allow a hyphen in dot notation, so another tool may reject it. Brackets work everywhere.

Brackets are also the canonical form. RFC 9535 defines a normalized path for every match, written entirely in brackets. Asking the Python library where $..sku matched returns:

$['orders'][0]['items'][0]['sku']
$['orders'][0]['items'][1]['sku']
$['orders'][1]['items'][0]['sku']

JSONPath, jq and JSON Pointer side by side

Three notations address values inside JSON, and each tool you use picks one of them. Here are the same tasks in all three, tested with jq 1.7:

Which to use depends on the job:

• JSONPath selects values. It is what Postman, kubectl, API gateways and integration platforms expect.
• jq selects and also reshapes. {shipped: [.orders[] | select(.status == "shipped") | .id], revenue: ([.orders[].total] | add)} builds a new object, {"shipped":["ord_1001","ord_1003"],"revenue":354.49}, which JSONPath cannot do.
• JSON Pointer (RFC 6901) points at exactly one value, with no wildcards or filters. JSON Patch documents, JSON Schema $ref and OpenAPI references all use it. In a key, / is written ~1 and ~ is written ~0.

Where implementations disagree

The standard is new, and many libraries predate it. Running the same expressions through jsonpath-rfc9535 and jsonpath-plus turned up these differences:

Notice that none of these is an error. Every disagreement shows up as an empty or different list, which is easy to miss.

The patterns behind them:

• Filter syntax. Older libraries need the filter wrapped in parentheses, ?(...). The standard does not, but it accepts them, so the parenthesized form is the more portable one.
• JavaScript leaking through. jsonpath-plus evaluates filters as JavaScript, so .length works and existence tests follow JavaScript truthiness. The standard has length() instead, and tests whether a field exists, whatever its value.
• Indexes and slices. Negative indexes and negative steps are standard, but not universal.

Tools also wrap JSONPath in their own syntax. kubectl, for example, drops the $ and uses braces: kubectl get pods -o jsonpath='{.items[*].metadata.name}'.

The rule that follows: test an expression on the engine you will actually run it on, with a document where you know the right answer.

Generating expressions instead of writing them

Writing the first expression is the slow part, because you need to know the document's shape. The JSONPath Generator on JSON Keyper starts from the document instead. Paste it, tick Collapse array indices, and you get an expression for every field. For the sample above:

$.store
$.orders
$.orders[*].id
$.orders[*].status
$.orders[*].total
$.orders[*].items
$.orders[*].items[*].sku
$.orders[*].items[*].qty
$.orders[*].giftMessage
$.meta
$.meta.page
$.meta['x-request-id']
$.meta['rate.limit']

Keys like x-request-id and rate.limit come out in brackets, so the paths work in strict engines too. Pick the path you need, then add a filter by hand where you want one. The document is processed in your browser and never uploaded.