jq vs JSONPath vs JMESPath: the same 8 tasks in all three
· 6 min read · Updated · By Amir Badi
All three languages pull values out of JSON. They part ways in how much else they do, and you see that fastest by solving the same problems in each. Below are eight tasks on one data file. I ran every query with jq 1.7, the jsonpath-plus library for JSONPath, and jmespath.js.
Paste the sample into the JSONPath tester, the JMESPath playground or the jq playground and switch languages to try each line yourself.


Which one to use
- Use JSONPath when a tool asks for it, or when all you need is to point at values: test assertions, config templates,
kubectl -o jsonpath. - Use JMESPath when you're in the AWS or Azure CLI (
--query), or when you want selection plus a bit of reshaping with a strict, portable spec. - Use jq for anything that computes or reshapes, and in shell scripts. Of the three, only jq is a programming language.
Learning one from scratch for your own work? I'd learn jq.
The sample data
{
"orders": [
{ "id": "A-100", "customer": { "name": "Ana", "country": "PT" }, "status": "paid",
"total": 120.5, "items": [ { "sku": "KB-01", "qty": 1 }, { "sku": "MS-02", "qty": 2 } ] },
{ "id": "A-101", "customer": { "name": "Ben", "country": "US" }, "status": "pending",
"total": 35, "items": [ { "sku": "MS-02", "qty": 1 } ] },
{ "id": "A-102", "customer": { "name": "Chloe", "country": "PT" }, "status": "paid",
"total": 410, "items": [ { "sku": "MN-27", "qty": 1 }, { "sku": "KB-01", "qty": 1 } ] }
]
}
Task 1: every customer name
| Language | Query | Result |
|---|---|---|
| JSONPath | $.orders[*].customer.name |
["Ana","Ben","Chloe"] |
| JMESPath | orders[*].customer.name |
["Ana","Ben","Chloe"] |
| jq | [.orders[].customer.name] |
["Ana","Ben","Chloe"] |
Nearly the same, with two differences already. JSONPath starts at $ and gives you a list of matches. jq gives you a stream of separate values: drop the outer brackets and you get three lines, "Ana", "Ben" and "Chloe", which suits a shell loop.
Task 2: orders over 100
| Language | Query |
|---|---|
| JSONPath | $.orders[?(@.total > 100)].id |
| JMESPath | orders[?total > `100`].id |
| jq | [.orders[] | select(.total > 100) | .id] |
Each returns ["A-100","A-102"]. JMESPath puts literals in backticks (`100`, `"x"`) and raw strings in single quotes ('paid'). Those backticks catch people out in shell scripts, where backticks run a command. Put the whole query in single quotes.
RFC 9535, the JSONPath standard since 2024, lets you drop the parentheses: $.orders[?@.total > 100].id. Plenty of libraries still expect the older ?(...) form (jsonpath-plus returns [] without the parentheses), and that older form works nearly everywhere.
Task 3: every SKU from nested arrays
| Language | Query |
|---|---|
| JSONPath | $.orders[*].items[*].sku or $..sku |
| JMESPath | orders[].items[].sku |
| jq | [.orders[].items[].sku] |
Result: ["KB-01","MS-02","MS-02","MN-27","KB-01"].
JSONPath's .. (recursive descent) finds a key at any depth, handy when you don't know the structure. In jq you'd write [.. | .sku? // empty].
Watch the JMESPath version. orders[*].items[*].sku keeps the nesting and returns [["KB-01","MS-02"],["MS-02"],["MN-27","KB-01"]]. [] flattens one level, while [*] projects and leaves the nesting alone. For one flat list, use [].
Task 4: count the orders
| Language | Query | Result |
|---|---|---|
| JSONPath | none in the standard | |
| JMESPath | length(orders) |
3 |
| jq | .orders | length |
3 |
JSONPath can't do this one. RFC 9535 has a length() function, but you can only use it inside a filter, never as the result. A few libraries return JavaScript's .length property for $.orders.length (jsonpath-plus gives [3]). That's an accident of how they're built, and I wouldn't depend on it.
Task 5: two conditions at once
Paid orders from Portugal:
| Language | Query |
|---|---|
| JSONPath | $.orders[?(@.customer.country == "PT" && @.status == "paid")].id |
| JMESPath | orders[?customer.country == 'PT' && status == 'paid'].id |
| jq | [.orders[] | select(.customer.country == "PT" and .status == "paid") | .id] |
Same answer from each: ["A-100","A-102"]. JSONPath and JMESPath use && and ||, and jq spells them and and or.
Task 6: orders that contain a given SKU
A filter on a nested array: which orders include KB-01?
| Language | Query |
|---|---|
| JSONPath (RFC 9535) | $.orders[?@.items[?@.sku == 'KB-01']].id |
| JMESPath | orders[?contains(items[].sku, `"KB-01"`)].id |
| jq | [.orders[] | select(any(.items[]; .sku == "KB-01")) | .id] |
JMESPath and jq both return ["A-100","A-102"]. The JSONPath query is valid RFC 9535 (a nested filter used as an existence test), but libraries disagree on it: jsonpath-plus returned []. A JSONPath library older than the RFC breaks on queries like this first. The usual way out is to select the orders and filter them in your own code.
Task 7: build new objects
Just the id and total of each order:
| Language | Query |
|---|---|
| JSONPath | not possible |
| JMESPath | orders[*].{id: id, total: total} |
| jq | [.orders[] | {id, total}] |
Both give [{"id":"A-100","total":120.5},{"id":"A-101","total":35},{"id":"A-102","total":410}]. In jq, {id, total} is short for {id: .id, total: .total}.
JSONPath only returns values that already exist. $.orders[*]['id','total'] gives ["A-100",120.5,"A-101",35,...]: one flat list, and you lose which total went with which id.
Task 8: sort, sum and find the maximum
| What | JMESPath | jq |
|---|---|---|
| ids sorted by total | sort_by(orders, &total)[*].id |
.orders | sort_by(.total) | map(.id) |
| sum of totals | sum(orders[*].total) |
[.orders[].total] | add |
| id of the largest order | max_by(orders, &total).id |
.orders | max_by(.total) | .id |
Results: ["A-101","A-100","A-102"], 565.5, "A-102". JSONPath has no sorting or arithmetic at all.
The & in JMESPath makes an expression reference. It hands total to sort_by as the thing to sort by, unevaluated.
Beyond the eight: what only jq does
Grouping and aggregating, for a start. Here's the total quantity per SKU across all orders:
jq '[.orders[].items[]]
| group_by(.sku)
| map({sku: .[0].sku, qty: (map(.qty) | add)})' orders.json
[{"sku":"KB-01","qty":2},{"sku":"MN-27","qty":1},{"sku":"MS-02","qty":3}]
JMESPath has no group-by. jq also gives you variables (as $x), reduce, string interpolation, regular expressions, @csv/@tsv output, several input files at once, and --stream for files bigger than memory. All that explains why jq lives in shell scripts and CI pipelines, and why its syntax takes longer to learn.
Side by side
| Feature | JSONPath | JMESPath | jq |
|---|---|---|---|
| Specification | RFC 9535 (2024); older libraries vary | Formal spec with compliance tests | The jq manual; one main implementation plus ports |
| Selects values | Yes | Yes | Yes |
| Recursive search | .. |
No | .. |
| Builds new objects | No | Yes (multiselect hash) | Yes |
| Sort, sum, min, max | No | Yes | Yes |
| Group by, variables, reduce | No | No | Yes |
| Typical home | Test tools, Java/JS libraries, kubectl -o jsonpath |
aws --query, az --query, embedded in apps |
Shell, CI, data cleanup |
Practical advice
Let the place the query runs decide. In the AWS CLI you're writing JMESPath, like it or not. If a test framework takes JSONPath, write JSONPath and keep the logic in code. At a terminal with a file, jq handles every case above and plenty more.
Stuck on a query? Run it on your real data, not a toy sample. A path that works on three records can hit a null, a missing key or a string-instead-of-number at record 40,000. JMESPath and JSONPath skip missing values without a word (orders[*].customer.nickname gives []), and jq gives null ([null,null,null]), so one mistake looks different in each language. For jq on log files, where one bad line can stop a whole run, see querying API responses and NDJSON logs.
The JSONPath tester and jq playground run all three languages in your browser, and your data stays on your machine. In the GigaJSON app, the Query tab runs JSONPath and JMESPath on documents of hundreds of megabytes. jq tops out at about 20 MB of input there, because the WebAssembly build of jq aborts past roughly 25 MB. For bigger files, run jq in a terminal.