autostart (default: true) - If this is supplied as false, one may call the evaluate method manually.

flatten (default: false) - Whether the returned array of results will be flattened to a single dimension array.

resultType (default: "value") - Can be case-insensitive form of "value", "path", "parent", or "parentProperty" to determine respectively whether to return results as the values of the found items, as their absolute paths, as their parent objects, or as their parent's property name. If set to "all", all of these types will be returned on an object with the type as key name.

sandbox (default: {}) - Key-value map of variables to be available to code evaluations such as filtering expressions. (Note that the current path and value will also be available to those expressions; see the Syntax section for details.)

wrap (default: true) - Whether or not to wrap the results in an array. If wrap is set to false, and no results are found, undefined will be returned (as opposed to an empty array with wrap set to true). If wrap is set to false and a single result is found, that result will be the only item returned (not within an array). An array will still be returned if multiple results are found, however.

preventEval (default: false) - Although JavaScript evaluation expressions are allowed by default, for security reasons (if one is operating on untrusted user input, for example), one may wish to set this option to true to throw exceptions when these expressions are attempted.

parent (default: null) - In the event that a query could be made to return the root node, this allows the parent of that root node to be returned within results.

parentProperty (default: null) - In the event that a query could be made to return the root node, this allows the parentProperty of that root node to be returned within results.

callback (default: (none)) - If supplied, a callback will be called immediately upon retrieval of an end point value. The three arguments supplied will be the value of the payload (according to resultType), the type of the payload (whether it is a normal "value" or a "property" name), and a full payload object (with all resultTypes).

otherTypeCallback (default: <A function that throws an error when @other() is encountered>) - In the current absence of JSON Schema support, one can determine types beyond the built-in types by adding the operator @other() at the end of one's query. If such a path is encountered, the otherTypeCallback will be invoked with the value of the item, its path, its parent, and its parent's property name, and it should return a boolean indicating whether the supplied value belongs to the "other" type or not (or it may handle transformations and return false).

Instance methods

evaluate(path, json, callback, otherTypeCallback) OR evaluate({path: <path>, json: <json object>, callback: <callback function>, otherTypeCallback: <otherTypeCallback function>}) - This method is only necessary if the autostart property is set to false. It can be used for repeated evaluations using the same configuration. Besides the listed properties, the latter method pattern can accept any of the other allowed instance properties (except for autostart which would have no relevance here).

Class properties and methods

JSONPath.cache - Exposes the cache object for those who wish to preserve and reuse it for optimization purposes.

JSONPath.toPathArray(pathAsString) - Accepts a normalized or unnormalized path as string and converts to an array: for example, ['$', 'aProperty', 'anotherProperty'].

JSONPath.toPathString(pathAsArray) - Accepts a path array and converts to a normalized path string. The string will be in form like: $['aProperty']['anotherProperty]. The terminal constructions ~ and typed operators like @string(), as with $, get added without enclosing single quotes and brackets.

Grabs all categories of books where the parent object of the book has a bicycle child whose color is red (i.e., all the books)

@parent is not present in the original spec

//book/*[name() != 'category']

$..book.*[?(@property !== "category")]

Grabs all children of "book" except for "category" ones

@property is not present in the original spec

//book/*[position() != 0]

$..book[?(@property !== 0)]

Grabs all books whose property (which, being that we are reaching inside an array, is the numeric index) is not 0

@property is not present in the original spec

/store/*/*[name(parent::*) != 'book']

$.store.*[?(@parentProperty !== "book")]

Grabs the grandchildren of store whose parent property is not book (i.e., bicycle's children, "color" and "price")

@parentProperty is not present in the original spec

//book[count(preceding-sibling::*) != 0]/*/text()

$..book.*[?(@parentProperty !== 0)]

Get the property values of all book instances whereby the parent property of these values (i.e., the array index holding the book item parent object) is not 0

@parentProperty is not present in the original spec

//book/../*[. instance of element(*, xs:decimal)] (in XPath 2.0)

$..book..*@number()

Get the numeric values within the book array

@number(), the other basic types (@boolean(), @string()), other low-level derived types (@null(), @object(), @array()), the JSONSchema-added type, @integer(), the type, @other(), to be used in conjunction with a user-defined callback (see otherTypeCallback) and the following non-JSON types that can nevertheless be used with JSONPath when querying non-JSON JavaScript objects (@undefined(), @function(), @nonFinite()) are not present in the original spec

Any additional variables supplied as properties on the optional "sandbox" object option are also available to (parenthetical-based) evaluations.

Potential sources of confusion for XPath users

In JSONPath, a filter expression, in addition to its @ being a
reference to its children, actually selects the immediate children
as well, whereas in XPath, filter conditions do not select the children
but delimit which of its parent nodes will be obtained in the result.

In JSONPath, array indexes are, as in JavaScript, 0-based (they begin
from 0), whereas in XPath, they are 1-based.

In JSONPath, equality tests utilize (as per JavaScript) multiple equal signs
whereas in XPath, they use a single equal sign.

Todos

Conditionally resolve JSON references/JSON pointers instead or in
addition to raw retrieved data, with options on how deeply nested.

Support non-eval version (which supports parenthetical evaluations)

Support OR outside of filters (as in XPath |).

Create syntax to work like XPath filters in not selecting children?

Allow for type-based searches to be JSON Schema aware (and allow
retrieval of schema segment for a given JSON fragment)