BestWebExtension Guide

How to Query JSON With JSONata in the Browser

Pull one field out of a large API response without scrolling it: what JSONata is for, the expressions that do the work, and where to run them in a browser.

A large API response is mostly noise. You want the request id from the meta block, or the three services whose latency crossed a threshold, and the answer sits five thousand lines down. Scrolling works until the payload stops fitting in your head.

JSONata is a query and transformation language for JSON. It walks a document with a path, keeps or drops items with a predicate, and returns only what matched. In a viewer that embeds it, one typed expression replaces the hunt. This guide uses Best JSON Viewer, built by BestWebExtension, and checks every expression against the JSONata documentation.

What you need

The examples below run against this small response. Its shape is the usual one: a wrapper object, an array of records, and a meta block.

{
  "status": "ok",
  "page": 2,
  "results": [
    { "id": "svc-1041", "name": "checkout", "state": "healthy", "latencyMs": 120, "tags": ["edge", "public"] },
    { "id": "svc-1042", "name": "billing", "state": "degraded", "latencyMs": 940, "tags": ["internal"] },
    { "id": "svc-1043", "name": "search", "state": "healthy", "latencyMs": 210, "tags": ["edge"] }
  ],
  "meta": { "total": 184, "requestId": "3f9c21ab" }
}

1. Open the payload in the viewer

Best JSON Viewer has two activation modes, and the manual one is the default.

Either way you get a toolbar at the top of the page: a view switcher for Tree, Raw, Table, Visualize and Edit, the JSONata input, a theme toggle, and Copy / Export. The extension carries no telemetry and sends nothing out, so the payload stays in the tab you opened it in.

2. Pull one field with a path

Start with a field whose location you already know. Type the field names separated by dots:

meta.requestId
"3f9c21ab"

Now point a path at the array inside the response. A field name applied to an array of objects selects that field from every item:

results.name
["checkout", "billing", "search"]

A path that does not exist returns nothing rather than an error. That is the first thing JSONata buys you over scrolling: a wrong guess costs a keystroke, not a stack trace.

3. Filter with a predicate

Square brackets after the array hold a predicate. Each item is tested against the expression, and only the items that pass are kept.

results[name = "billing"].latencyMs
940

Numbers compare the same way:

results[latencyMs > 200].name
["billing", "search"]

Three details that save time later.

A record missing the field is dropped, not flagged. Add a fourth item with no latencyMs and results[latencyMs > 200] still returns those two rows, quietly. Check the counts when a filter looks short.

Comparisons are typed. If latencyMs arrives as the string "940", the same expression stops with the error The values "120" and 200 either side of operator ">" must be of the same data type. Cast the field inside the predicate and the filter works again:

results[$number(latencyMs) > 200].name

Negative indexes count from the end. results[-1].name returns "search", the last record, without knowing how long the array is.

Text matching belongs in a predicate too. $contains tests a field against a string or a regular expression:

results[$contains(name, "bill")].id
"svc-1042"

4. Reach a value at a depth you do not know

Nested responses are where hand-written paths get long and guessing starts. The descendant wildcard ** traverses every level below the current one:

**.requestId
"3f9c21ab"

Double star visits every descendant node, so it costs more than a direct path. Use it to find the shape of a response you have not seen before, then write the real path and remove the wildcard.

5. Count, total and group

Aggregation functions take a matched sequence and return one value:

$count(results[state = "healthy"])
2
$sum(results.latencyMs)
1270

Grouping is an object constructor placed directly on the sequence. The key comes from one field and the value from another:

results{state: name}
{
  "healthy": ["checkout", "search"],
  "degraded": "billing"
}

Every repeated key collects its values. Swap the value expression for an aggregation to get one number per group instead: results{state: $count($)} returns {"healthy": 2, "degraded": 1}.

6. Reshape what you keep

A result you can paste into a ticket or a config beats a view you scrolled past. An object constructor after the dot builds one object per item:

results.{"service": name, "ms": latencyMs}
[
  { "service": "checkout", "ms": 120 },
  { "service": "billing", "ms": 940 },
  { "service": "search", "ms": 210 }
]

For one line of text per record, $map applies a function to each item and & joins strings:

$map(results, function($v) { $v.name & " (" & $v.latencyMs & " ms)" })
["checkout (120 ms)", "billing (940 ms)", "search (210 ms)"]

& casts both operands to strings first, so the number needs no conversion.

7. Read the result in the views you already have

The expression is not a separate panel. Its result flows into every view, so after results[latencyMs > 200] you can switch to Table and read the matches as columns, or to Tree and open one record.

When it won’t help

Takeaways

For the trade-offs between viewers, the large payload comparison covers what each one does with a big file. For what happens when a JSONata expression meets a very large input inside a Node process, there is the event loop essay.

Questions

What is JSONata used for?

JSONata is a query and transformation language for JSON. It reads a document with path expressions, filters items with predicates, and builds a smaller result with object and array constructors.

Can I use JSONata without installing a toolchain?

Yes. JSONata runs in the browser. A viewer such as Best JSON Viewer embeds it, so you type an expression against the JSON you already have open in a tab.

Is JSONata the same as a JSONPath query?

No. JSONPath-style paths select values. JSONata selects values and computes with them, so the same expression can total a field, group records by one key, or build new objects from the fields you pick.

BestWebExtension JSON Viewer docs