JSONPath Complete Guide – Query JSON Like XPath

If you have ever needed to extract a specific value from a deeply nested API response, JSONPath is the tool for that job. It is to JSON what XPath is to XML — a path query language that lets you select one or many values from a JSON document with a single expression.

JSONPath was originally defined by Stefan Goessner in 2007, and was officially standardised in RFC 9535 (published February 2024). It is used in AWS IAM policies, Kubernetes admission webhooks, Grafana alerting, and dozens of API testing frameworks.

The root element: $

Every JSONPath expression starts with $, which represents the root of the document. Given this JSON:

{
  "store": {
    "book": [
      { "author": "Nigel Rees",   "price": 8.95  },
      { "author": "Evelyn Waugh", "price": 12.99 }
    ],
    "bicycle": { "color": "red", "price": 19.95 }
  }
}

The expression $ returns the entire document. Everything else is a path from there.

Dot and bracket notation

You can navigate child keys using dot notation (.key) or bracket notation (['key']). Both are equivalent for simple key names:

Use bracket notation when a key contains spaces, hyphens, or starts with a digit: $['my-key'].

Wildcard: [*]

The wildcard * matches all elements of an array or all values of an object:

Recursive descent: ..

The double-dot operator searches all descendants, regardless of depth:

Recursive descent is the JSONPath equivalent of // in XPath. It is powerful but can be slow on very large documents.

Array slices

JSONPath supports Python-style array slicing: [start:end:step].

Filter expressions: [?()]

Filter expressions let you select elements that satisfy a condition. The current element is referenced with @:

Supported comparison operators: ==, !=, <, <=, >, >=. You can combine conditions with && and ||.

JSONPath cheat sheet

JSONPath in practice

AWS IAM condition keys

AWS uses JSONPath-like syntax in IAM condition keys and CloudFormation. Understanding path syntax makes reading policies much easier.

Kubernetes admission webhooks

Kubernetes uses JSONPath in kubectl output templates:

kubectl get pods -o jsonpath='{.items[*].metadata.name}'

Grafana alerting

Grafana alert conditions use JSONPath to extract values from API datasources. A path like $.data.result[0].value[1] extracts the metric value from a Prometheus response.

API testing (Postman, Bruno)

Most API testing tools support JSONPath for assertions: pm.expect(jsonData.store.book[0].price).to.equal(8.95).

Frequently Asked Questions