JMESPath Tester

What is JMESPath?

JMESPath is a query language for JSON. An expression such as people[?age > `30`].name picks out matching parts of a document and returns them as JSON. It has a written specification and a shared compliance test suite, and the AWS CLI and Azure CLI both use it for their --query option.

This tester runs @jmespath-community/jmespath 1.3.0, an open-source JavaScript library under the MPL-2.0 licence (source repository), inside a Web Worker. Run through this page's own code, the official compliance suite (16 test files, 892 cases) gives 891 passes. The one difference: a doubled backslash in a raw string becomes one backslash, where the older test expects two. The page follows the JMESPath specification, but the AWS CLI, the Azure CLI and other tools implement it themselves, so edge cases can differ.

The library also adds features that are not in the specification, and queries that use them fail in tools that implement only the specification. The extra functions are find_first, find_last, from_items, group_by, items, lower, pad_left, pad_right, replace, split, trim, trim_left, trim_right, upper, zip. The extra syntax is arithmetic, let variables, a $ root reference, and slicing of strings (people[0].name[0:3] gives "Ada"). The page notes it under a query that uses any of them.

How do I filter an array with JMESPath?

Use a filter expression in square brackets: people[?age > `30`].name returns the names of everyone over 30. The ? starts a condition, backticks hold JSON literals such as numbers, and single quotes hold plain strings. Filters work on arrays only, and an item that fails the condition is simply left out.

A filter can combine conditions with && and || and call functions, as in people[?contains(tags, 'code')].name, which returns ["Ada Lovelace","Margaret Hamilton"]. Then continue: people[?age > `30`] | length(@) counts the matches and gives 3. To inspect the data first, format the result with the JSON Formatter; the JSON Schema Validator checks its shape.

How do I flatten and project nested data?

A projection such as people[*].name applies the part after it to every item in an array. A trailing [] flattens one level of nesting, so Reservations[].Instances[].InstanceId turns nested lists into one flat list. Projections skip null results, which is why missing values never appear in the output.

Without the flatten, Reservations[*].Instances[*].InstanceId keeps one inner list per reservation and gives [["i-0a1","i-0b2"],["i-0c3"]]. With it, Reservations[].Instances[].InstanceId gives ["i-0a1","i-0b2","i-0c3"]. A multiselect list such as people[*].[name, age] builds one array per item, and a multiselect hash such as people[*].{who: name, years: age} builds one labelled object per item.

JMESPath vs JSONPath: what is the difference?

Both select parts of JSON, but they are different languages. JSONPath paths start with $, can search at any depth with .., and always return a list of matches. JMESPath returns a bare value or a list, has built-in functions such as sort_by, and needs an explicit path instead of a recursive search.

The table runs the same selections in both languages. The JMESPath results come from this page's worker; the JSONPath results come from jsonpath-plus 11.1.1, the library behind the JSONPath Tester, with the same options that page uses. Neither is better: they suit different jobs. For background on JSONPath itself, see the guide to JSONPath.

The last row is a real difference. JSONPath's $..city finds every city key at any depth, including company.hq.city. JMESPath has no recursive search, so the query has to name each place, for example [people[*].address.city, company.hq.city], which gives [["London","New York","Boston"],"Paris"]. Another: JSONPath always returns a list, JMESPath a bare value.

Why does my JMESPath query return null?

A JMESPath query returns null when a key is missing, when the value really is null, or when a step does not apply, such as a filter on something that is not an array. A valid query that matches nothing is not an error, so null alone does not tell you which of these happened.

Gotchas, each checked with this tool

• Null and missing look the same. people[2].address is a JSON null and people[2].nothing is a missing key, and both give null. Even type() returns "null" for both.
• Quote odd identifiers. "first name" gives "Ada", while first name is a syntax error. A dash is a trap: unquoted a-b gives 3 here, because this library reads it as subtraction, whereas a tool that follows the specification only would report a syntax error. Write "a-b".
• Raw strings are not literals. name == 'London' and name == `"London"` both give true. But age == '30' gives false, because '30' is a string and the age is a number, while age == `30` gives true. A bare word such as name == London is read as a key and gives false.
• Backtick literals must be JSON. `[1, 2]` gives [1,2], but `foo` is rejected: Syntax error: unexpected end of JSON input or invalid format for a JSON literal: `.
• Projections drop nulls. people[*].address returns three of four people, and people[*].address.city gives ["London","New York","Boston"], skipping the person whose address is null. Projecting a string, as in people[0].name[*], gives null.
• Large numbers lose digits. The browser reads JSON numbers as 64-bit floats, so 12345678901234567890 comes back as 12345678901234567000 and 9007199254740993 as 9007199254740992. This page warns before running when the input has integers beyond 2⁵³; it has no custom number parser.
• sort_by needs one key type. sort_by(m, &v) fails with Invalid type: expected (number), received string, while numbers alone work: sort_by(m, &v)[*].v gives [1,2].
• Function arguments are type-checked. abs(people) fails with Invalid type: abs() expected argument 1 to be type (number) but received type array instead., and length(people, people) fails with Invalid arity: length() takes 1 argument but received 2. Convert text first with to_number(people[0].score), which gives 91.5.
• Only numbers have an order. people[?name > 'B'].name gives [], because comparing strings with > never matches, while people[?age >= `36`].name gives ["Ada Lovelace","Grace Hopper","Margaret Hamilton"].
• A key named __proto__. __proto__ gives null when the data has no such key. The library alone would return the empty object prototype there, so the page copies the data into prototype-less objects when a query mentions it. A key named __proto__ in a multiselect hash is dropped by the library, and the page says so under the query.
• Non-standard syntax is flagged. A query that uses the library's extras, such as lower(), arithmetic, let, $ or string slicing, gets a note listing them, because the AWS CLI and other implementations may reject it.
• Carets cover syntax errors. The caret marks the first token the parser cannot accept, or the end of the query when it stops too soon. Function and type errors show the message alone.

What do JMESPath query examples return?

The examples below were each run through this page's own code against small sample documents. Click any of them in the examples panel above to load its document and query. The output shown is the exact text this tool produced, not typed by hand, and a script re-checks it against the library.

Sample document "people"

{
  "people": [
    {
      "name": "Ada Lovelace",
      "age": 36,
      "tags": [
        "math",
        "code"
      ],
      "address": {
        "city": "London"
      },
      "score": "91.5"
    },
    {
      "name": "Grace Hopper",
      "age": 45,
      "tags": [
        "compilers",
        "navy"
      ],
      "address": {
        "city": "New York"
      },
      "score": "88"
    },
    {
      "name": "Linus Torvalds",
      "age": 28,
      "tags": [],
      "address": null,
      "score": "79.25"
    },
    {
      "name": "Margaret Hamilton",
      "age": 52,
      "tags": [
        "apollo",
        "code"
      ],
      "address": {
        "city": "Boston"
      },
      "score": "95"
    }
  ]
}

Which operators and functions does JMESPath support?

The specification defines 26 built-in functions and a small set of operators: sub-expressions, indexes, slices, wildcards, flatten, filters, pipes, multiselect lists and hashes, comparisons and boolean logic. This page runs a library that adds 15 more functions and some syntax. The tables mark every addition as an extension.

Is my JSON uploaded?

No. The query runs in a Web Worker on your device, so your JSON and queries never leave your browser. Nothing you paste or upload is sent to a server, and nothing is stored. Still, do not paste secrets into any website, because pages can load third-party scripts such as the Google tag.

Queries run in the worker under a time limit with a Cancel button, and results above about 20 MB are not built. New to JSON? Read the introduction to JSON.