JSONPath expressions always refer to a JSON structure in the same way as XPath expression are used in combination with an XML document. Since a JSON structure is usually anonymous and doesn‘t necessarily have a "root member object" JSONPath assumes the abstract name $ assigned to the outer level object.

JSONPath expressions can use the dot–notation

$.store.book[0].title

or the bracket–notation

$[‘store‘][‘book‘][0][‘title‘]

for input pathes. Internal or output pathes will always be converted to the more general bracket–notation.

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

Expressions of the underlying scripting language (<expr>) can be used as an alternative to explicit names or indices as in

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

using the symbol ‘@‘ 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 pathes in not abbreviated syntax, operators and functions) than listed here. Moreover there is a remarkable 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 by 1.
• With JSONPath square brackets operate on the object or array addressed by the previous path fragment. Indices always start by 0.

Let‘s practice JSONPath expressions by some more examples. We start with a simple JSON structure built after an XML example representing a bookstore (original XML file).

{ "store": {
    "book": [ 
      { "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      { "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      { "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      { "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}

JSONPath is implemented in Javascript for clientside usage and ported over to PHP for use on the server.

Usage

All you need to do is downloading either of the files

• jsonpath.js
• jsonpath.php

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

jsonPath(obj, expr [, args])

parameters:

obj (object|array):

Object representing the JSON structure.

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.

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.

Javascript Example:

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

PHP example:

We need here to convert the JSON string to a PHP array first. I am using Michal Migurski‘s JSON parser for that.

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

$json = ‘{ ... }‘;  // JSON structure 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);

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 structure. So you might want to apply jsonPath to the resulting structure again or use one of your favorite array methods as sort with it.

• Currently only single quotes allowed inside of JSONPath expressions.
• Script expressions inside of JSONPath locations are currently not recursively evaluated byjsonPath. Only the global $ and local @ symbols are expanded by a simple regular expression.
• An alternative for jsonPath to return false in case of no match may be to return an empty array in future.