JSONPath -- XPath for JSON

1.1. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

The grammatical rules in this document are to be interpreted as described in [RFC5234].¶

The terminology of [RFC8259] applies.¶

Data Item:

A structure complying to the generic data model of JSON, i.e., composed of containers such as arrays and maps (JSON objects), and of atomic data such as null, true, false, numbers, and text strings.¶

Object:

Used in its generic sense, e.g., for programming language objects. When a JSON Object as defined in [RFC8259] is meant, we specifically say JSON Object.¶

Query:

Short name for JSONPath expression.¶

Argument:

Short name for the JSON data item a JSONPath expression is applied to.¶

Output Path:

A simple form of JSONPath expression that identifies a Position by providing a query that results in exactly that position. Similar to, but syntactically different from, a JSON Pointer [RFC6901].¶

Position:

A JSON data item identical to or nested within the JSON data item to which the query is applied to, expressed either by the value of that data item or by providing a JSONPath Output Path.¶

1.2. Inspired by XPath

A frequently emphasized advantage of XML is the availability of plenty tools to analyse, transform and selectively extract data out of XML documents. [XPath] is one of these powerful tools.¶

In 2007, the need for something solving the same class of problems for the emerging JSON community became apparent, specifically for:¶

• Finding data interactively and extracting them out of [RFC8259] data items without special scripting.¶
• Specifying the relevant parts of the JSON data in a request by a client, so the server can reduce the data in the server response, minimizing bandwidth usage.¶

So how does such a tool look like when done for JSON? When defining a JSONPath, how should expressions look like?¶

The XPath expression¶

/store/book[1]/title

looks like¶

x.store.book[0].title

or¶

x['store']['book'][0]['title']

in popular programming languages such as JavaScript, Python and PHP, with a variable x holding the JSON data item. Here we observe that such languages already have a fundamentally XPath-like feature built in.¶

The JSONPath tool in question should:¶

• be naturally based on those language characteristics.¶
• cover only essential parts of XPath 1.0.¶
• be lightweight in code size and memory consumption.¶
• be runtime efficient.¶

1.3. Overview of JSONPath Expressions

JSONPath expressions always apply to a JSON data item in the same way as XPath expressions are used in combination with an XML document. Since a JSON data item is usually anonymous and doesn't necessarily have a "root member object", JSONPath used the abstract name $ to refer to the top level object of the data item.¶

JSONPath expressions can use the dot-notation¶

$.store.book[0].title

or the bracket-notation¶

$['store']['book'][0]['title']

for paths input to a JSONPath processor. Where a JSONPath processor uses JSONPath expressions for internal purposes or as output paths, these will always be converted to the more general bracket-notation.¶

JSONPath allows the wildcard symbol * for member names and array indices. It borrows the descendant operator .. from [E4X] and the array slice syntax proposal [start:end:step] [SLICE] from ECMASCRIPT 4.¶

JSONPath can employ an underlying scripting language, expressions of which, written in parentheses: (<expr>), can be used as an alternative to explicit names or indices as in:¶

$.store.book[(@.length-1)].title

The symbol @ is used for the current object. Filter expressions are supported via the syntax ?(<boolean expr>) as in¶

$.store.book[?(@.price < 10)].title

Here is a complete overview and a side by side comparison of the JSONPath syntax elements with its XPath counterparts.¶

XPath has a lot more to offer (location paths in unabbreviated syntax, operators and functions) than listed here. Moreover there is a significant difference how the subscript operator works in Xpath and JSONPath:¶

• Square brackets in XPath expressions always operate on the node set resulting from the previous path fragment. Indices always start at 1.¶
• With JSONPath, square brackets operate on the object or array addressed by the previous path fragment. Indices always start at 0.¶

A.1. Implementation

JSONPath is implemented in JavaScript for client-side usage and ported over to PHP for use on the server.¶

A.2. Usage

All you need to do is downloading either of the files¶

• jsonpath.js [JSONPath-impl]¶
• jsonpath.php [JSONPath-impl]¶

include it in your program and use the simple API consisting of one single function.¶

jsonPath(obj, expr [, args])

A.3. Parameters

obj (object|array):

Object representing the JSON data item.¶

expr (string):

JSONPath expression string.¶

args (object|undefined):

Object controlling path evaluation and output. Currently only one member is supported.¶

args.resultType ("VALUE"|"PATH"):

causes the result to be either matching values (default) or normalized path expressions.¶

A.4. Return value

(array|false):

Array holding either values or normalized path expressions matching the input path expression, which can be used for lazy evaluation. false in case of no match.¶

A.5. JavaScript Example

var o = { /*...*/ },  // the 'store' JSON object from above
    res1 = jsonPath(o, "$..author").toJSONString(),
    res2 = jsonPath(o, "$..author",
                    {resultType:"PATH"}).toJSONString();

A.6. PHP example

We need here to convert the JSON string to a PHP array first. I am using Michal Migurski's JSON parser [JSON-PHP] for that.¶

require_once('json.php');      // JSON parser
require_once('jsonpath.php');  // JSONPath evaluator

$json = '{ ... }';  // JSON data item from above

$parser = new Services_JSON(SERVICES_JSON_LOOSE_TYPE);
$o = $parser->decode($json);
$match1 = jsonPath($o, "$..author");
$match2 = jsonPath($o, "$..author",
                   array("resultType" => "PATH"));
$res1 = $parser->encode($match1);
$res2 = $parser->encode($match2);

A.7. Results

Both JavaScript and PHP example result in the following JSON arrays (as strings):¶

res1:
[ "Nigel Rees",
  "Evelyn Waugh",
  "Herman Melville",
  "J. R. R. Tolkien"
]
res2:
[ "$['store']['book'][0]['author']",
  "$['store']['book'][1]['author']",
  "$['store']['book'][2]['author']",
  "$['store']['book'][3]['author']"
]

Please note that the return value of jsonPath is an array, which is also a valid JSON data item. So you might want to apply jsonPath to the resulting data item again or use one of your favorite array methods as sort with it.¶