What is JSONPath?

JSONPath is a standardized query language for selecting and extracting values from JSON. A query starts at the root symbol $ and applies segments and selectors (child names, indexes, wildcards, slices and filters) to produce a list of matching nodes in the input JSON. See the specification in RFC 9535: JSONPath RFC 9535: JSONPath.

Core syntax at a glance

• $ refers to the root of the input JSON value (the query argument).
• .name or ['name'] selects a child member by name (use brackets for names with special characters).
• [index] selects an array element by zero-based index.
• [start:end:step] selects a slice of an array.
• * matches all children; ..[*] matches all descendants.
• [?(<logical-expr>)] filters children using a condition; @ refers to the current node inside the filter.

These elements are defined and summarized in the standard RFC 9535: JSONPath.

JSONPath and JSON Pointer: how they differ

JSONPath is not a replacement for JSON Pointer; it is a more powerful companion. JSONPath supports queries that can return zero, one or many matches (for example via wildcards, recursive descent and filters), while JSON Pointer is a string syntax intended to identify a specific value at a single location in a JSON document. See the JSONPath introduction and its note on JSON Pointer in RFC 9535, and a concise description of JSON Pointer in the javax.json JsonPointer docs.

Short, runnable examples

Example JSON:

{
  "store": {
    "book": [
      {"title": "Sayings of the Century", "price": 8.95},
      {"title": "Moby Dick", "price": 8.99, "isbn": "0-553-21311-3"}
    ],
    "bicycle": {"color": "red", "price": 399}
  }
}

Queries and example value-list results (the recursive object traversal may return a different order):

• $.store.book[*].title →

["Sayings of the Century", "Moby Dick"]

• $..price →

[8.95, 8.99, 399]

• $.store.book[?(@.isbn)] →

[
  {"title": "Moby Dick", "price": 8.99, "isbn": "0-553-21311-3"}
]

Per the spec, applying a JSONPath produces a nodelist (a list of nodes). An API may expose those results as values, as normalized paths, or both; duplicate matches can be retained. Array traversal has defined ordering, while object-member traversal does not provide a portable member order. See semantics in RFC 9535.

Semantics, limits and gotchas that matter

• Empty results are valid. If any segment yields no matches, the overall result is an empty nodelist RFC 9535.
• Out-of-range indexes simply select nothing; they do not raise an error RFC 9535.
• Member name matching is exact. A name selector matches only if the member name is an identical sequence of Unicode scalar values; do not apply case folding or normalization RFC 9535.
• Integers significant to processing (e.g., indexes, slice steps) must be within the I-JSON exact-integer range; otherwise the query is invalid RFC 9535.
• History note: before standardization, implementations diverged on details. RFC 9535 establishes a common baseline, but confirm behavior in your chosen library when precise edge cases matter RFC 9535.

How to test JSONPath safely

Start with small, representative JSON and build your path from $. Validate each step, then add filters and slices. For public or fictitious samples, an online evaluator like the JSONLint JSONPath evaluator lets you see the matches immediately. When moving to code, verify how your library returns results (values, paths, or structured nodes) and how it represents no-match cases, as permitted by the spec’s API notes in RFC 9535.

Pre-flight checks for a reliable JSONPath

• Begin with $ and add one segment at a time; confirm each step returns what you expect
• Quote property names with ['...'] if they contain spaces or special characters
• Test edge cases: empty arrays, missing members, and out-of-range indexes
• Check your library’s output shape (values vs paths) and how it signals no matches
• Avoid unnecessary recursive descent (..); prefer explicit segments for precision and performance

Related reading on CheckMySchema

• How to escape a backslash in JSON
• Are JSON keys case-sensitive?

FAQ

Is JSONPath an official standard?

Yes. The IETF published JSONPath as an Internet Standards Track document in February 2024. See RFC 9535: JSONPath.

Does JSONPath modify data?

No. JSONPath defines a string syntax for selecting and extracting values. Mutation is out of scope of the specification RFC 9535.

What should I expect as the result of a JSONPath query?

The logical result is a nodelist. APIs may return values, normalized paths or both; duplicates can appear. Do not assume a portable ordering when traversing object members, as explained in RFC 9535.