How to Use JSONPath Expressions

In this article we will explain what JSONPath is and how to use it to easily fetch fields from a JSON string.

Let’s start!

Introduction

JSONPath is an expression language that was conceived as a need to have an equivalent in JSON to what XPath is for XML language. You can find JSONPath specifications here.

JSONPath gives us the ability to easily get a portion of the data in a JSON object, by specifying a query using its expression language.

Now that we understand the reason why JSONPath was created, let’s dive into some basics!

Usage

To be able to understand how JSONPath works, there are a few notations that you need to know. We will show them in the table below:

Understanding and remembering these notations is a must if you want to become fluent with JSONPath. As you will see in future articles, JSONPath has been adopted by many existing tools. For example, knowing JSONPath well will make your life much easier when using kubectl in Kubernetes.

You can check our article “How to Use JSONPath in Kubernetes” for more details on this topic.

Now that we know the notations, let’s look at a few examples!

Before we dive into the examples, we are going to show you the JSON we will be using for all of our examples:

{
    "firstName": "John",
    "lastName": "doe",
    "age": 26,
    "address": {
        "streetAddress": "naist street",
        "city": "Nara",
        "postalCode": "630-0192"
    },
    "phoneNumbers": [
        {
            "type": "iPhone",
            "number": "0123-4567-8888"
        },
        {
            "type": "home",
            "number": "0123-4567-8910"
        }
    ]
}

Let’s start then!

Access Field From Root

This is the simplest example of all, we’d like to access a field in the root. Doing so will be as simple as the following:

$.firstName

And the output should be just the name:

[
  "John"
]

Let’s go one step further, what if we need to extract the value of a field included in a nested object?

Access Field From Nested Object

This example is also quite simple, let’s say we want to access the city name under the address object. This would look like this:

$.address.city

The result should be the following:

[
  "Nara"
]

If our JSON had more than one object at the root level, we’d be getting the city name for each person in our list.

What if we need to access data from a nested array? Let’s find out!

Access Fields From Nested Array

Let’s complicate things a bit more, we are going to access data from our list of phone numbers. Initially we just want to get a list of this person phone numbers. This would be like this:

$.phoneNumbers[*].number

In this case, we use the wildcard number to get every element in the phoneNumbers array. The result should be this:

[
  "0123-4567-8888",
  "0123-4567-8910"
]

What if we only need the “home” phone number? This is where the filter notation can come handy.

$.phoneNumbers[?(@.type == "home")].number

We use ?() to be able to specify a predicate to filter elements from our collection. Inside that predicate, we use @ notation to get the object in each iteration and then check for each of them if the type field is “home”.

If we execute that expression, the response should be including just one phone number:

[
  "0123-4567-8910"
]

It’s quite simple if you know the notations well!

What if the JSON object is an array, how can we iterate elements from the root? Let’s see how!

Iterate Through JSON Array

Knowing what we know at this point, you can probably guess how would it work but, let’s look into it to make it clear.

For this example we are going to modify the original JSON to be an array:

[{
    "firstName": "John",
    "lastName": "doe",
    "age": 26,
    "address": {
        "streetAddress": "naist street",
        "city": "Nara",
        "postalCode": "630-0192"
    },
    "phoneNumbers": [
        {
            "type": "iPhone",
            "number": "0123-4567-8888"
        },
        {
            "type": "home",
            "number": "0123-4567-8910"
        }
    ]
},
{
    "firstName": "Peter",
    "lastName": "Johnson",
    "age": 33,
    "address": {
        "streetAddress": "Praed street",
        "city": "New York",
        "postalCode": "134-0987"
    },
    "phoneNumbers": [
        {
            "type": "iPhone",
            "number": "0572-4567-8888"
        },
        {
            "type": "home",
            "number": "0911-4567-8910"
        }
    ]
}]

You can see how now we have an array with two elements. Let’s say that we need to get the first names for every person in the list. How would that be? Simple!

$[*].firstName

We will treat the root object ($) as an array, therefore we can use the [] notation.

This should result in the following:

[
  "John",
  "Peter"
]

Simple, right? The rest of the queries should be the same once you can access the elements in the array that you’re looking for.

Conclusion

In this article we’ve seen what is JSONPath and how to use it to be able to fetch data from a JSON object very easily.

That’s all from us today! We hope that you’ve learned something new and enjoyed reading this article!

Thanks for reading us and see you soon!