Free JMESPath Tester
Run a JMESPath query against your JSON, the way the AWS CLI’s --query does, and see the result or the exact reason it fails.
What is a JMESPath Tester?
JMESPath is a query language for JSON: one short expression picks, filters and reshapes data. It’s what the AWS CLI’s --query option, the Azure CLI and Ansible’s json_query filter use. This tester runs an expression against JSON you paste and shows the result.
Expressions run on jmespath.js, the reference implementation that the JMESPath specification’s compliance tests are written against. Results come back as indented JSON or as tab-separated text like the AWS CLI’s --output text, and errors name the token or function that broke.
Key Features
Your Own JSON, Not a Demo
Paste the real output of aws, az or an API, then refine the expression until it returns exactly the fields you need.
Text Output Like the AWS CLI
Text mode prints a flat list on one line and a list of rows one per line, tab-separated. You see what a shell script will receive before you run it.
Errors That Say What Broke
A bare number in a filter, an unknown function or a wrong argument type each get their own message. The most common slip, forgetting backticks around a number, is called out directly.
The Reference Implementation
jmespath.js follows the JMESPath specification, so the results match the AWS SDKs and other compliant libraries.
Cloud Output Stays Private
Queries run in the browser, so account IDs, instance details and API responses aren’t uploaded.
Perfect for everyone
- AWS and Azure users writing --query expressions
- Ansible authors using json_query
- Developers filtering API responses
How to Use the JMESPath Tester
Paste JSON, write an expression, and refine it until the result is right.
Paste the JSON
Copy the output of a command such as aws ec2 describe-instances, or any API response, into the second box.
Write the Expression
Start broad, like Reservations[], and add one step at a time: a projection, then a filter, then the fields to keep. The result updates on every keystroke.
Choose JSON or Text
JSON shows the structured result. Text shows the tab-separated form the AWS CLI prints with --output text, which is what shell scripts usually read.
Copy It Into Your Command
Paste the expression after --query in single quotes, so the shell leaves backticks and brackets alone.
JMESPath Expressions, Evaluated
Each example is an expression, a line of three dashes, then the JSON it runs on. The answer is what this tester returned in the mode on the chip, so work it out before revealing.
“people[*].first --- {"people":[{"first":"James","age":30},{"first":"Jacob","age":25},{"first":"Jayden","age":40}]}”
“people[?age > `28`].first --- {"people":[{"first":"James","age":30},{"first":"Jacob","age":25},{"first":"Jayden","age":40}]}”
“people[?age > 28].first --- {"people":[{"first":"James","age":30},{"first":"Jacob","age":25},{"first":"Jayden","age":40}]}”
“max_by(people, &age).first --- {"people":[{"first":"James","age":30},{"first":"Jacob","age":25},{"first":"Jayden","age":40}]}”
“people[].{name: first, adult: age >= `18`} --- {"people":[{"first":"James","age":30},{"first":"Jacob","age":15}]}”
“people[*].[first, age] --- {"people":[{"first":"James","age":30},{"first":"Jacob","age":25},{"first":"Jayden","age":40}]}”
“sort_by(people, &age)[*].first --- {"people":[{"first":"James","age":30},{"first":"Jacob","age":25},{"first":"Jayden","age":40}]}”
“people[?first == 'Jacob'].age | [0] --- {"people":[{"first":"James","age":30},{"first":"Jacob","age":25}]}”
“nobody --- {"people":[]}”
“abs(people[0].first) --- {"people":[{"first":"James","age":30}]}”
JMESPath Syntax in Ten Pieces
Nearly every expression is built from these ten pieces. Each one keeps working on whatever the previous step returned.
Identifiers and Dots
A name picks a field, and a dot steps into it, so a.b.c walks three levels. Quote names with dashes or spaces, as in "user-id".
“What does State.Name return for an EC2 instance?”
Index and Slice
[0] picks the first element and [-1] the last. [0:5] takes a slice, like Python, and [::-1] reverses a list.
“How do you get the last element?”
List Projection [*]
[*] applies the rest of the expression to every element of a list. people[*].first returns every first name.
“What does people[*].first return?”
Flatten []
[] projects like [*] and also flattens one level of nested lists. Reservations[].Instances[] gives one flat list of instances.
“Which turns a list of lists into one list?”
Filter [?]
[?condition] keeps elements where the condition is true, using comparisons and the logical operators &&, || and !. Strings go in single quotes.
“How do you keep only running instances?”
Literals Need Backticks
Numbers, true, false, null and JSON values are written inside backticks. age > 28 fails, and age > `28` works.
“How do you compare age with 28?”
Multiselect List and Hash
[a, b] builds a list from several fields, and {name: first, age: age} builds an object with new keys. Both are how you reshape results.
“Which builds an object with renamed keys?”
The Pipe Stops a Projection
Everything after a projection applies to each element until a pipe. people[*].age | [0] takes the first result, while people[*].age[0] takes the first character of each age.
“How do you take the first item of a projection’s result?”
Functions and Expression References
Built-ins such as length, contains, sort_by and max_by take arguments, and &field passes an expression to sort or compare by. @ means the current value.
“How do you find the oldest person?”
Missing Means Null
Asking for a field that doesn’t exist returns null rather than an error. Projections quietly drop null results from the list.
“What does a missing field return?”
Built-In Functions Worth Knowing
JMESPath ships about 25 functions. These eight cover most real queries against CLI and API output.
length
Counts the items in a list, the keys in an object or the characters in a string. Wrap a projection to count matches, as in length(people[?age > `28`]).
“How many running instances are there?”
contains
Tests whether a list holds a value or a string holds a substring. It’s the usual way to match part of a name inside a filter.
“How do you keep names that include web?”
starts_with and ends_with
Compare the start or end of a string, for prefixes like prod- or suffixes like .log. Both are case-sensitive.
“Which function checks a prefix?”
sort_by and sort
sort orders a list of strings or numbers, and sort_by orders objects by an expression such as &age. Add [-1] or reverse() for descending order.
“How do you sort instances by launch time?”
max_by and min_by
Return the whole object with the largest or smallest value of an expression. Use max and min for plain lists of numbers.
“Which returns the newest object, max or max_by?”
join
Joins a list of strings with a separator, which turns a projection into one line of text. Every element must already be a string.
“How do you make a comma-separated list of IDs?”
to_string and to_number
Convert between strings and numbers, so a value stored as text can be compared with a number. to_number returns null when the text isn’t numeric.
“What does to_number('abc') return?”
keys, values and merge
keys and values list an object’s names or contents, and merge combines objects with later ones winning. They help when tags arrive as maps.
“Which function combines two objects?”
Where JMESPath Is Used
The same expression language turns up in several command-line tools, each with its own quirks.
AWS CLI --query
Every aws command accepts --query with a JMESPath expression, applied client-side after the response arrives. Combine it with --output text or table to format the result.
Azure CLI --query
The az command uses JMESPath for --query too, so the same projections and filters work on Azure resources.
Ansible json_query
Ansible’s community.general.json_query filter runs JMESPath on registered variables. It needs the jmespath Python package installed on the controller.
AWS SDK Waiters and Paginators
Boto3 paginators accept a JMESPath search, and SDK waiters use JMESPath paths to decide when a resource is ready.
Libraries in Many Languages
Official implementations exist for Python, JavaScript, Go, Java, Rust and more, and pass the same compliance tests, so an expression tested here behaves the same in code.
JMESPath Versus jq
jq is a fuller programming language with variables and string functions, while JMESPath is smaller and declarative. Use jq for shell pipelines and JMESPath where a tool asks for it.
JMESPath Mistakes
These account for most expressions that fail or return the wrong thing.
Numbers Without Backticks
age > 28 is a syntax error, since numbers are JSON literals. Write age > `28`.
Double Quotes for String Values
"running" in double quotes is a field name, not a string. Compare with 'running' in single quotes, or a JSON literal in backticks.
Forgetting the Pipe
people[*].age[0] indexes into each age instead of the list. Use people[*].age | [0] to take the first result.
Unflattened Nested Lists
Reservations[*].Instances[*] returns a list of lists. Use [] at either level to get one flat list.
Shell Quoting
Backticks and brackets mean something to your shell. Wrap the whole --query value in single quotes, and on Windows cmd, use double quotes and escape inner ones.
Expecting Server-Side Filtering
--query filters after the full response downloads. For large results, also use the API’s own --filters option to cut what comes back.
Comparing Strings and Numbers
A comparison between a string and a number is false rather than an error. If a filter returns nothing, check the field’s JSON type.
Assuming Text Output Keeps Order
In text output, object values appear in key order, not the order you wrote them. Use a multiselect list when column order matters.
When a JMESPath Tester Saves Time
Whenever a command returns more JSON than you need.
Writing an AWS CLI One-Liner
Paste a describe call’s output and build the --query that extracts IDs, IPs or tags, without rerunning the command each time.
Feeding a Shell Loop
Check the text output before piping it into a for loop or xargs, so each line holds exactly one value.
Debugging an Ansible Playbook
Test a json_query expression against a registered variable’s JSON instead of rerunning the playbook.
Reshaping an API Response
Use a multiselect hash to rename and pick fields so the result matches what your report or dashboard expects.
Writing an SDK Waiter
Confirm a path such as Table.TableStatus resolves to the value the waiter should wait for.
Auditing Cloud Resources
Filter a resource listing for untagged, stopped or public items with one expression, then reuse it in a scheduled script.
Learning the Language
Change one piece of an expression at a time and watch the result change. Projections and pipes click quickly this way.