json-path (alpha)

JSON-Path utility (XPath for JSON) for nodejs and modern browsers.

You may be looking for the prior work found here. This implementation is a new JSON-Path syntax building on JSON Pointer (RFC 6901) in order to ensure that any valid JSON pointer is also valid JSON-Path.

Warning: This is a work in progress - I am actively adding selection expressions and have yet to optimize, but as I use it in a few other projects I went ahead and made it available via npm. Until I take the alpha tag off you should look to the examples and test to understand the selection path syntax.

Example

flikr-example-2.js

var jpath = require('json-path')
, http = require('http')
, util = require('util')
;

var feed = "http://api.flickr.com/services/feeds/photos_public.gne?tags=beach,pipeline&tagmode=all&format=json&jsoncallback=processResponse"
;

function processResponse(json) {
	var res = jpath.resolve(json, "#/items[first(3)]take(/title,/author,media=/media/m)")
	console.log( util.inspect(res, false, 5) );
}

http.get(feed, function(res) {
	console.log("Got response: " + res.statusCode);

	var data = '';

	res.on('data', function (chunk){
		data += chunk;
	});

	res.on('end',function(){
		// result is formatted as jsonp... this is for illustration only.
		eval(data);
	})
}).on('error', function(e) {
	console.log("Got error: " + e.message);
});

Installation

node.js

$ npm install json-path

Basics

JSON-Path takes a specially formatted path statement and applies it to an object graph in order to select results. The results are returned as an array of data that matches the path.

Most paths start out looking like a JSON Pointer...

// From: http://goessner.net/articles/JsonPath/
var data = {
  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
    }
  }
};

The pointer /store/book/0 refers to the first book in the array of books (the one by Nigen Rees).

Differentiator

The thing that makes JSON-Path different from JSON-Pointer is that you can do more than reference a single point in a structure. Instead, you are able to select many pieces of data out of a structure, such as:

/store/book[*]/price

[8.95, 12.99, 8.99, 22.99]

In the preceding example, the path /store/book[*]/price has three distinct statements:

Starting with the original data, each statement refines the data, usually by selecting parts. As each statement is processed, it is given the results from the previous statement and may make further selections, until the final selections are returned to the caller. It works something like map-reduce; or if you like, something like list-comprehensions.

Distinguishing Statements

Statements are distinguished from one another using the square-brackets [ and ]. In many cases, the parser can infer where one statement ends and another begins, such as in the preceding example /store/book[*]/price. However, the parser understands the equivelant, fully specified path [/store/book][*][/price].

Paths can have as many distinct statements as you need to select just the right data. Since it extends JSON-Pointer, you must take care when your path contains square-brackets as part of property names such as the following contrived example:

var data = {
	'my[': {
		contrived: {
			'example]': { should: "mess with", your: "noodel" } } }
};

In this data, the property names my[ and example] are valid but would cause ambiguities for either the parser or the processing of statements. In these cases, you must use the URI fragment identifier representation described in RFC 6901 Section 6. For instance, to access data['my['].contrived['example]'].your you would need the path #/my%5B/contrived/example%5D/your.

More Power

JSON-Path becomes more powerful with a few additional types of statements:

Consider the following examples using the same preceding data:

User Supplied Selection Methods

JSON-Path supports the use of user-supplied selections - which will need to fill in until the expression syntax is completed. Mindful of the preceding data, consider the following code:

var jpath = require('json-path')
, expect  = require('expect.js')
, data    = require('./example-data')

var p = jpath.create("#/store/book[*][@]");

var res = p.resolve(data, function(obj, accum) {
  if (typeof obj.price === 'number' && obj.price < 10)
    accum.push(obj);
  return accum;
});

// Expect the result to have the two books priced under $10...
expect(res).to.contain(data["store"]["book"][0]);
expect(res).to.contain(data["store"]["book"][2]);
expect(res).to.have.length(2);

The example above illustrates user-defined selection given to resolve used in place of the @.

To use more than one user-defined selections, refer to selection functions by name and provide implementations when resolving the path:

var jpath = require('json-path')
, expect = require('expect.js')
, data = require('./example-data')

var p = jpath.create("#/store/book[*][@lt10][@format]");

var res = p.resolve(data, {

	lt10: function(obj, accum) {
		if (typeof obj.price === 'number' && obj.price < 10)
			accum.push(obj);
		return accum;
	},

	format: function(obj, accum) {
		accum.push(obj.title.concat(
			": $", obj.price
			));
		return accum;
	}

});

// Expect the result to have formatted strings for
// the twb books priced under $10...
expect(res).to.contain("Sayings of the Century: $8.95");
expect(res).to.contain("Moby Dick: $8.99");
expect(res).to.have.length(2);

#noConflict

When used in an environment that has a global namespace the only variable used is JsonPath. If you utilize other libraries that already occupy that name you can use the noConflict function to restore the obstructing value and assign json-path to another variable.

  <!--script src="../scripts/json-ptr-0.1.1.min.js"></script-->
  <!--script src="../releases/json-path-0.1.3.min.js"></script-->
  <script src="../releases/json-path+json-ptr-0.1.3.min.js"></script>
  <script>
    // note: json-path uses json-ptr, so both are in the global namespace...
    var ptr = JsonPointer.noConflict();
    var path = JsonPath.noConflict(ptr);
  </script>