(see also licenses for dev. deps.)

JSONPath Plus

Analyse, transform, and selectively extract data from JSON documents (and JavaScript objects).

jsonpath-plus expands on the original specification to add some additional operators and makes explicit some behaviors the original did not spell out.

Try the browser demo or Runkit (Node).

Please note: This project is not currently being actively maintained. We may accept well-documented PRs or some simple updates, but are not looking to make fixes or add new features ourselves.

Features

• Compliant with the original jsonpath spec
• Convenient additions or elaborations not provided in the original spec:
  • ^ for grabbing the parent of a matching item
  • ~ for grabbing property names of matching items (as array)
  • Type selectors for obtaining:
    • Basic JSON types: @null(), @boolean(), @number(), @string(), @array(), @object()
    • @integer()
    • The compound type @scalar() (which also accepts undefined and non-finite numbers when querying JavaScript objects as well as all of the basic non-object/non-function types)
    • @other() usable in conjunction with a user-defined otherTypeCallback
    • Non-JSON types that can nevertheless be used when querying non-JSON JavaScript objects (@undefined(), @function(), @nonFinite())
  • @path/@parent/@property/@parentProperty/@root shorthand selectors within filters
  • Escaping
    • ` for escaping remaining sequence
    • @['...']/?@['...'] syntax for escaping special characters within property names in filters
  • Documents $.. (getting all parent components)
• ESM and UMD export formats
• In addition to queried values, can return various meta-information including paths or pointers to the value, as well as the parent object and parent property name (to allow for modification).
• Utilities for converting between paths, arrays, and pointers
• Option to prevent evaluations permitted in the original spec or supply a sandbox for evaluated values.
• Option for callback to handle results as they are obtained.

Benchmarking

jsonpath-plus is consistently performant with both large and small datasets compared to other json querying libraries per json-querying-performance-testing. You can verify these findings by running the project yourself and adding more perf cases.

Install

npm install jsonpath-plus

Setup

Node.js

const {JSONPath} = require('jsonpath-plus');

const result = JSONPath({path: '...', json});

Browser

For browser usage you can directly include dist/index-browser-umd.cjs; no Browserify magic is necessary:

<script src="node_modules/jsonpath-plus/dist/index-browser-umd.cjs"></script>

<script>

const result = JSONPath.JSONPath({path: '...', json: {}});

</script>

ESM (Modern browsers)

You may also use ES6 Module imports (for modern browsers):

<script type="module">

import {
    JSONPath
} from './node_modules/jsonpath-plus/dist/index-browser-esm.js';

const result = JSONPath({path: '...', json: {}});

</script>

ESM (Bundlers)

Or if you are bundling your JavaScript (e.g., with Rollup), just use, noting that mainFields should include browser for browser builds (for Node, the default, which checks module, should be fine):

import {JSONPath} from 'jsonpath-plus';

const result = JSONPath({path: '...', json});

Usage

The full signature available is:

const result = JSONPath([options,] path, json, callback, otherTypeCallback);

The arguments path, json, callback, and otherTypeCallback can alternatively be expressed (along with any other of the available properties) on options.

Note that result will contain all items found (optionally wrapped into an array) whereas callback can be used if you wish to perform some operation as each item is discovered, with the callback function being executed 0 to N times depending on the number of independent items to be found in the result. See the docs below for more on JSONPath's available arguments.

See also the API docs.

Properties

The properties that can be supplied on the options object or evaluate method (as the first argument) include: