JSONPath Queries: Select Values from Nested JSON

When an API response contains dozens of nested fields, scrolling through the whole payload is a slow way to find one value. JSONPath lets you describe the route to that value, or select the same field from every item in an array.

Consider an endpoint that returns this response:

{
  "data": [
    { "id": "ord-104", "customer": { "name": "Rae" }, "total": 28.50 },
    { "id": "ord-105", "customer": { "name": "Luis" }, "total": 61.00 }
  ],
  "page": 1
}

To inspect the customer names, the path is $.data[*].customer.name. It means: start at the root, open data, visit every array item, then select customer.name from each one. The result is ["Rae", "Luis"].

Read a path from left to right

The root marker $ refers to the input document. A dot selects an object property, and a bracket index selects an array element:

$.data[0].id       → ["ord-104"]
$.data[1].total    → [61]

Indexes start at zero. The tester displays matches as an array, even when a path selects one value. That output shape is useful when you move from a single index to a wildcard and suddenly get several results.

For a property whose name is not a simple identifier, use quoted bracket notation:

$.data[0]['customer name']

The OCMA tester accepts quoted keys such as ['display name']. It does not parse escaped quote characters inside a key, so a property containing an apostrophe or quote needs another JSONPath implementation.

Select fields across an array

The wildcard * visits each child at the current level. Put it at the array position to extract the same property from every record:

$.data[*].id       → ["ord-104", "ord-105"]
$.data[*].total    → [28.5, 61]

This avoids hard-coding array positions when the response can contain more records. A numeric union selects particular indexes: $.data[0,1].id returns the ids at indexes 0 and 1. The tester supports unions of numeric array indexes; it does not support unions of property names.

Use a slice when you want a range. The start index is included and the end index is excluded:

$.data[0:2]        → both records
$.data[0:2:2]      → the record at index 0
$.data[-1].id      → ["ord-105"]

The tester accepts positive integer slice steps and negative array indexes. It reports an error for a zero or negative slice step. Those details matter because a query can be valid in one engine and behave differently in another.

Search when the nesting depth is unknown

Recursive descent uses two dots. $..name looks for a name property among descendants of the root. For the sample response, $..name returns ["Rae", "Luis"] without spelling out the path through data[*].customer.

Recursive descent is convenient for discovery, but it can return multiple matches from unrelated parts of a document if the same property name appears more than once. Once you know the response shape, prefer the longer path when it selects only the intended field. It makes the query easier to review and less sensitive to new fields added elsewhere in the payload.

Diagnose an empty result

An empty array [] means the expression produced no matches. Check these points in order:

1. Validate the input. A JSON parse error must be fixed before the path can run. Property names and string values need double quotes in JSON.
2. Check the root and spelling. Paths start with $; property names are case-sensitive. $.data and $.Data are different.
3. Check the value type. [0] expects an array at that position. A property selector such as .id expects an object.
4. Reduce the path. Try $.data, then $.data[0], then add .customer.name. The first step that changes the result shows where the assumption stopped matching the input.
5. Check the query engine. The tester does not evaluate filter expressions such as [?(@.total > 30)], functions, script expressions, property-name unions, escaped quotes inside bracket keys, or negative slice steps. Some unsupported bracket syntax can return [] instead of a dedicated syntax error.

That final point is important when a query is headed into an application. The standardized JSONPath syntax is described in RFC 9535, but libraries and older implementations may support different subsets or extensions. Test against the same library and version that will run in production.

Try a path against your own response

The JSONPath tester updates the result as you edit either the JSON or the expression. It shows a match count, formats the selected values as a JSON array, and keeps the input in the browser. Start with a known field, then add a wildcard or recursive selector when you need more results. The JSONPath cheatsheet has example expressions and the tester's exact operator limits.

For malformed JSON, use the JSON Validator to locate the syntax problem first. For large minified responses, the JSON Formatter can make the object structure easier to inspect before you write a path.