# JSONata: a query and transformation language for JSON documents

> The reference implementation of JSONata turns JSON into something you can query with a compact expression syntax, and the repository is small enough to read in an afternoon.

**jsonata-js/jsonata** — JSONata query and transformation language - http://jsonata.org

- Repository: https://github.com/jsonata-js/jsonata
- Stars: 2,693 · Forks: 287
- Language: JavaScript
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/jsonata-js-jsonata

## One install and an expression you can evaluate

Installation is a single line, and the quick start evaluates a real expression against a real object rather than a toy string:

```bash
npm install jsonata
```

```javascript
const jsonata = require('jsonata');

const data = {
    example: [
        {value: 4},
        {value: 7},
        {value: 13}
    ]
};
```

The expression itself is a string, which is the detail that matters most about the design. You are not writing JavaScript that traverses the document, you are writing a query that the interpreter runs against the data, so the same expression can come from a configuration file, a stored user preference or a request body:

```javascript
const expression = jsonata('$sum(example.value)');
const result = await expression.evaluate(data);  // returns 24
```

That path syntax is where JSONata departs from JSONPath most visibly. `example.value` walks into each element of the array and collects the `value` field, and the surrounding `$sum()` reduces it. A JSONPath library would give you the three values and leave the arithmetic to you. Writing the whole shape query and the reduction as one expression is the reason people reach for this library instead of a path evaluator.

## The browser build loads from a CDN with no build step

The README ships a second quick start that runs entirely in a page, which tells you something about how the library was meant to be used early on. There is no bundler, no module import, just a script tag pointing at the minified distribution:

```html
<!DOCTYPE html>
<html lang="en">
<script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
<script>
  async function greeting() {
    var json = JSON.parse(document.getElementById('json').value);
```

```javascript
    var result = await jsonata('"Hello, " & name').evaluate(json);
    document.getElementById('greeting').innerHTML = result;
  }
</script>
```

The expression `"Hello, " & name` uses the string concatenation operator rather than a template literal, and the result is written straight into the page. A textarea holds the input JSON, so the demo is a live editor for expressions without a server anywhere in the picture. The same idea is served as try.jsonata.org, which the README links as the third bullet in its opening section.

## A compact expression syntax instead of object traversal

The argument for a dedicated query language is strongest when you compare what the same task costs in each style. In JavaScript, flattening an array of objects and reducing the values takes a filter or map chained onto a reduce, and the result is an object you have to keep correct if anyone else touches the function later. In JSONata it is one string. The trade is that the string is opaque unless you already know the language, which is why docs.jsonata.org is a first-class link rather than an afterthought.

The repository tree explains where that documentation lives and what else the project ships. There is `src/` for the interpreter, `test/` for the suite, `docs/` and `website/` for documentation, plus three files worth knowing about before you start: `functions.md` at the root, `tutorial.md`, and `jsonata.d.ts` for TypeScript consumers. `polyfill.js` is there for the built-in functions that need to exist on older runtimes. The presence of `bower.json` alongside `package.json` dates the project's structure to when npm was the only distribution channel people expected.

The interpreter being small is the practical advantage. `src/` is one directory rather than a monorepo of packages, and the browser build is a single minified file. If you want to know exactly what happens when an expression is evaluated, the code is close enough to the documentation that reading both is a few hours of work, not a research project.

## Two release lines, and both shipped security fixes in July 2026

The release list is short and unusually informative. Three releases are visible, and two of them carry the name Security Release rather than a feature description.

v1.8.8, published 2026-07-16, says in so many words that it contains only fixes to vulnerabilities with associated CVEs. The two named changes are prevention of object prototype pollution and a backport of important security fixes to v1. v1.8.9 followed on 2026-07-30 and backports `$toMillis` security fixes. Prototype pollution through an object-shaped input is a real risk for a library whose whole job is evaluating expressions against JSON that somebody else supplied, so that is not a ceremonial CVE.

The interesting part is the shape of the maintenance. v2.2.2 was published the same day as v1.8.8, 2026-07-16, and its five items are ordinary: updated TypeScript type definitions, a fix for `$contains()` when the token is undefined, a regression in looking up keys of an object, a race condition when `$$` is used concurrently, and correct handling of empty joins. So the project is running a v1 line and a v2 line at once, both receiving security backports, both with the last push to master on 2026-09-10. That is the profile of a library with users in production who cannot all upgrade at once, which is a reasonable thing to be, and it means you get to choose your migration pace rather than being told when to move.

The 170 open issues on the repository are worth reading against that background. A language implementation with a large backlog is not necessarily a troubled one, but it does mean the release notes are a better signal of health than the issue count.

## Where the README stops and the language documentation begins

The README is genuinely short: a description, three links, two quick starts, a contributing note and a security file reference. Two thousand six hundred ninety-three stars and two hundred eighty-seven forks sit behind an install command and a fifteen-line example, and there is no feature list, no benchmark and no comparison table.

That is defensible for a reference implementation whose language is specified elsewhere, but it means the repository cannot answer the questions you would use it to decide anything. What happens when an expression references a key that does not exist? Whether undefined propagates or becomes an empty sequence? How are numbers coerced, and what happens on division by zero? What is in the function catalogue, and what signatures do user-defined functions take? None of that is on this page. It is on docs.jsonata.org, and the root-level `functions.md` is the closest local answer.

The `SECURITY.md` file points at a disclosure process, which matters more than usual here. If you accept expressions from users, a language interpreter is an execution surface, and the prototype pollution issue in v1.8.8 is a reminder that the surface needs the same care as any other. Read the security policy before you decide where expressions come from, and pin your version rather than tracking master.

## Conclusion

JSONata is genuinely good at the narrow job of turning a JSON document into the JSON you actually wanted, without the mutable-object gymnastics that plain JavaScript forces on you. The reference implementation is a small dependency with a permissive licence and a maintenance history that includes two CVE fixes in July 2026, which is worth weighing if you plan to evaluate expressions from anywhere near untrusted input. What the repository will not tell you is the language itself. Order of evaluation, numeric behaviour, the function catalogue and the function signature syntax all live on docs.jsonata.org, and functions.md in the tree is the closest thing to a local reference. Read that file before you commit, because the interesting decisions in this project were made in the language design, not in the interpreter.

## FAQ

### What is JSONata used for?

It is used to pull values out of a JSON document and reshape them into a different JSON document, using one expression string instead of traversal code. The common jobs are selecting nested fields across an array, summing or grouping values, renaming keys and filtering objects by a condition. The README's own example sums a numeric field across an array of records.

### How do I run a JSONata expression in Node.js?

Install the package, build an expression with the exported function, then await its evaluate method against your data. Because evaluation is asynchronous, the call has to be inside an async function or chained onto a promise. The README's quick start shows this exact pattern.

### What is the difference between JSONata and JSONPath?

JSONPath selects and returns parts of a document, while JSONata goes further and lets you reduce, aggregate, rename and reconstruct within the same expression. If you only need to locate a value, JSONPath is the lighter choice. If you need the selected values combined into a different structure, that is where a transformation language pays for itself.

### Is JSONata safe to use with expressions from untrusted users?

Treat it as an execution surface, not as a string formatter. The v1.8.8 release addresses object prototype pollution with an associated CVE, and v1.8.9 backports further `$toMillis` fixes, so the project has had real vulnerabilities here. Pin a patched version and read the repository's SECURITY.md for the disclosure process before exposing evaluation to untrusted input.

## Sources

- [Issues](https://github.com/jsonata-js/jsonata/issues)
- [jsonata-js/jsonata on GitHub](https://github.com/jsonata-js/jsonata)
- [License: MIT](https://github.com/jsonata-js/jsonata/blob/master/LICENSE)
- [README](https://github.com/jsonata-js/jsonata/blob/master/README.md)
- [Releases](https://github.com/jsonata-js/jsonata/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jsonata-js-jsonata