JMESPath Query

Details and how to verify this yourself: Security & privacy.

The tool sits in a window that works like a desktop app: menus on the top row and the full-screen icon at its right (Esc leaves full screen). The set-up options described below are in Settings → Options…, an overlay, and the Settings menu also lists the common choices directly. To keep the options in view instead, choose View → Inline config; the page remembers that choice. Help → Keyboard shortcuts… lists the keys.

1. Paste JSON into the left box (or click Sample).
2. Type a JMESPath expression above it. The result and its type appear on the right as you type. The buttons next to the expression load common patterns.
3. If the expression is wrong, the error shows the column and the expression with a caret under the problem. If the JSON is wrong, Go to error selects the bad character.

A path that does not exist is not an error: it gives null. A filter that matches nothing gives [].

Three things that trip people up.

• Literals need backticks. price > `10` compares with the number 10; price > 10 is a syntax error. Strings can be raw literals in single quotes: name == 'bread'. A backtick literal must be valid JSON: `"text"`, `[1, 2]`, `true`.
• Projections keep going until a pipe. items[*].name[0] applies [0] to each name (a string, so each gives null and is dropped). To take the first element of the list of names, stop the projection with a pipe: items[*].name | [0].
• Ordering comparisons are for numbers. <, <=, >, >= between strings give null, and a filter treats null as false.

Dialect. JMESPath Community Edition, as implemented by @jmespath-community/jmespath 1.3 (a tree-walking interpreter: no code generation). It is the original JMESPath language (identifiers, sub-expressions, index and slice expressions, wildcard and flatten projections, filters, multi-select lists and hashes, pipes, ||, &&, !, comparisons, functions, expression references with &) plus these Community extensions:

Functions. abs, avg, ceil, contains, ends_with, find_first, find_last, floor, from_items, group_by, items, join, keys, length, lower, map, max, max_by, merge, min, min_by, not_null, pad_left, pad_right, replace, reverse, sort, sort_by, split, starts_with, sum, to_array, to_number, to_string, trim, trim_left, trim_right, type, upper, values, zip. No custom functions are registered. Calling any other name is reported before evaluation, with its position.

Errors.

• Syntax errors give the column of the token where the problem was detected; an incomplete expression points just past the end. The library’s own messages have no position, so the position is found by re-parsing prefixes of the expression and taking the first one that fails the same way. Unterminated quoted identifiers and invalid backtick literals point at their opening quote or backtick. (The library accepts an unterminated raw string such as 'abc as if it were closed.)
• Evaluation errors (a function given the wrong type, such as length of a number; division by zero; a slice step of 0) are reported with the position of the function involved when it can be identified.
• JSON errors give line, column, offset and a JSON Pointer, from the same strict RFC 8259 parser as the JSON tool. Duplicate keys and integers beyond 2^53 − 1 are reported as warnings; the query sees the last value of a duplicate key, and numbers as IEEE 754 doubles.

Result. result is the value; type is its JSON type (object, array, string, number, boolean or null); the formatted text uses 2 or 4 spaces or no whitespace. Object keys that look like array indexes ("2", "10") come first, in numeric order, in any object the query returns: this is how JavaScript orders object keys. Inherited JavaScript property names are never visible: constructor on {} is null.

Examples. All results below are produced by this tool against this document:

{
  "items": [
    { "name": "apple", "price": 1.2, "tags": ["fruit"], "stock": { "qty": 0 } },
    { "name": "bread", "price": 3.5, "tags": ["bakery", "fresh"], "stock": { "qty": 12 } },
    { "name": "cheese", "price": 12, "tags": ["dairy"], "stock": { "qty": 4 } }
  ],
  "owner": { "name": "shop", "email": "[email protected]" }
}

API. POST /api/json/query with input (the JSON text, at most 500,000 characters), expression (at most 2,048 characters) and indent (2, 4, tab or none). The response has result, type, json (the formatted text) and warnings. Invalid JSON, an invalid expression and an evaluation error are 422 errors whose message gives the position.