JSON Path

JSON Path

When getting documents out of the database, it's common to not need the entire document. To satisfy this need there are many places in the API where you can include a path that describes what portion of the document should be returned. The syntax of these paths will be very familiar to JavaScript developers as it mirrors the dot notation for drilling down object properties.

First let's give an example document that we'll be working with:

{   
    "title": {
        "main": "The Big Lebowski",
        "subtitle": null
    },
    "year": 1998,
    "writers": [
        {   
            "first-name": "Ethan",
            "last-name": "Coen"
        },  
        {   
            "first-name": "Joel",
            "last-name": "Coen"
        }   
    ]   
}

Let's start out with a simple example, just returning the writers from the document. To do so we'd supply a path of:

writers

This path simply says, return the value of the writers key which will be the following array:

[
    {   
        "first-name": "Ethan",
        "last-name": "Coen"
    },  
    {   
        "first-name": "Joel",
        "last-name": "Coen"
    }   
]

If only life was always that simple. Let's say we'd like to just return the main title from the above document, here's what our path would be:

title.main

This will return the string "The Big Lebowski". Just like in JavaScript, traversing the object is done with the dot notation. However, not everything is an object and for accessing a member in an array the same JavaScript patterns are followed. For example, let's say we are just interested in the first writer in each document, the [<index>] syntax is what we're looking for:

writers[1]

Now inside of each writer object there are two keys, first-name and last-name (JavaScript developers should be able to spot what's coming next). Because JSON is very liberal with what can be used as an object key, there needs to be a way to quote access to object keys. Dot notation of keys need to start with either a letter, an underscore or a dollar sign and can only contain alphanumerics, underscores and dollar signs after that. For all the other cases, the key names will need to be quoted using the ["<key-name>"] syntax. So to access the last-name` of the first writer, our path will be:

writers[1]["last-name"]

Extensions

So far this is all standard object traversal in JavaScript. However, we've added in a few handy extensions to make life a touch easier.

Wildcard Steps

Sometimes you don't care where a key is in the object, you just want to get right to it and not explicitly specify every step along the way. This can be done using the asterisk or wildcard character (*). For example, using the document at the top let's jump right to the subtitle key:

*.subtitle

This can also be used to traverse every item in an array. For example, let's say we're interested in pulling out the last name of every writer:

writers.*["last-name"]

Moving up the tree

Because the wildcard step allows you jump to an arbitrary point in the document, it's sometimes useful to be able to move back up the tree a bit. Let's say we'd like to return the entire object that holds the last-name key. This can be done using the parent() function:

*["last-name"].parent()

Or perhaps we'd like to move up the tree until we reach the value of a specific key. This can be done using the ancestor() function:

*["last-name"].ancestor("writers")

Lastly, if we'd like to move all the way back to the root of the document, this can be accomplished with the root() function:

*["last-name"].root()

Descending into XML

Because of the (extensions to JSON)[JSON-Extensions] that we've made, a string of XML inside the JSON can be parsed and queried as XML. To allow a path to descend into the XML structure, use of the xpath() function is required:

writers[1].bio.xpath("background/hometown")

The value inside the xpath() function can be any simplified XPath statement.