JSONPath Plus

If you are transitioning from XPath, note these three key behavioral differences in JSONPath Plus:

1. Filter Selection: In JSONPath, a filter expression (using @) selects the immediate children that satisfy the condition. In XPath, filter conditions delimit which parent nodes are returned but do not select the children themselves.
2. Array Indexing: JSONPath uses 0-based indexing (consistent with JavaScript), whereas XPath uses 1-based indexing.
3. Equality Tests: JSONPath uses JavaScript-style equality operators (e.g., == or ===), whereas XPath uses a single = sign.

JSONPath-Plus evaluates expressions provided by the caller. While the default eval: "safe" option prevents arbitrary code execution, it does not prevent data exposure if the query itself is manipulated. If untrusted input is interpolated into a JSONPath expression, an attacker can alter the query structure to return broader or unexpected data (data leakage).

To mitigate this risk:

1. Do not interpolate unsanitized user input into JSONPath queries.
2. If user-controlled input must be included, ensure the target JSON object contains only non-confidential data.

Treat JSONPath expressions as code and avoid constructing them dynamically from untrusted sources.

If you are using a bundler like Rollup, import JSONPath from the package. For browser builds, ensure your bundler's mainFields includes browser.

import {JSONPath} from 'jsonpath-plus';

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

For direct browser usage without a bundler, include the UMD build via a <script> tag. Note that when using the UMD build, you access the function via JSONPath.JSONPath.

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

<script>
const result = JSONPath.JSONPath({path: '...', json: {}});
</script>

In a Node.js environment, you can use the require syntax to import JSONPath and evaluate paths against JSON objects.

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

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

Do not report security vulnerabilities through public GitHub issues. If you find a vulnerability, email one of the following addresses:

• iamavinashthakur.at@gmail.com
• brettz9@yahoo.com

Include these details in your report:

1. Description of the location and potential impact.
2. Detailed steps to reproduce (including POC scripts).
3. How you would like to be credited.

Policy on Disclosure: Please do not disclose the vulnerability publicly until a fix is released. You may publicly report the vulnerability on the tracker after:

• A fix has been published,
• The vulnerability has been declined for address,
• Or 30 days have passed without a reply.

For modern browsers supporting ES6 modules, import JSONPath directly from the ESM build file.

<script type="module">
import {
    JSONPath
} from './node_modules/jsonpath-plus/dist/index-browser-esm.js';

const result = JSONPath({path: '...', json: {}});
</script>

To use jsonpath-plus in your project, install it using npm:

npm install jsonpath-plus

To verify the installation or contribute to the project, you can run the test suites.

Node.js tests: Run via npm in your terminal.

In-browser tests:

1. Serve the js/html files using the provided script.
2. Open your browser and navigate to http://localhost:8082/test/.

# Run Node tests
npm test

# Run browser tests
npm run browser-test

The @other() operator allows you to define custom type filtering. To use it, you must provide an otherTypeCallback in your options. This callback is invoked when the query encounters @other(). It should return true if the value matches your custom criteria, or false otherwise.

const data = { a: 1, b: 'hello', c: [1, 2] };

JSONPath({
  json: data,
  path: '$.@other()',
  otherTypeCallback: (val) => typeof val === 'string'
});
// Returns ['hello']