One of advantages of XML is the availability of processing – including XPath – which is defined as a W3C standard. For JSON, a similar tool called JSONPath has emerged.
This article will give an introduction to Jayway JsonPath, a Java implementation of the JSONPath specification. It describes setup, syntax, common APIs, and a demonstration of use cases.
In order to use JsonPath, we simply need to include a dependency in the Maven pom:
The following JSON structure will be used in this section to demonstrate the syntax and APIs of JsonPath:
JsonPath uses special notation to represent nodes and their connections to adjacent nodes in a JsonPath path. There are two styles of notation, namely dot and bracket.
Both of the following paths refer to the same node from the above JSON document, which is the third element within the location field of creator node, that is a child of jsonpath object belonging to tool under the root node.
With dot notation:
With bracket notation:
The dollar sign ($) represents root member object.
We have has several helpful operators in JsonPath:
Root node ($): This symbol denotes the root member of a JSON structure no matter it is an object or array. Its usage examples were included in the previous sub-section.
Current node (@): Represents the node that is being processed, mostly used as part of input expressions for predicates. Suppose we are dealing with book array in the above JSON document, the expression book[?(@.price == 49.99)] refers to the first book in that array.
Wildcard (*): Expresses all elements within the specified scope. For instance, book[*] indicates all nodes inside a book array.
3.3. Functions and Filters
JsonPath also has functions that can be used to the end of a path to synthesize that path’s output expressions: min(), max(), avg(), stddev(), length().
Finally – we have filters; these are boolean expressions to restrict returned lists of nodes to only those that calling methods need.
A few examples are equality (==), regular expression matching (=~), inclusion (in), check for emptiness (empty). Filters are mainly used for predicates.
For a full list and detailed explanations of different operators, functions and filters, please refer to JsonPath GitHub project.
Before we get into operations, a quick side-note – this section makes use of the JSON example structure we defined earlier.
4.1. Access to Documents
JsonPath has a convenient way to access JSON documents, which is through static read APIs:
The read APIs can work with static fluent APIs to provide more flexibility:
Other overloaded variants of read can be used for different types of JSON sources, including Object, InputStream, URL and File.
To make things simple, the test for this part does not include predicates in the parameter list (empty varargs); predicates will be discussed in later sub-sections.
Let’s start by defining two sample paths to work on:
Next, we will create a DocumentContext object by parsing the given JSON source†jsonDataSourceString. The newly created object will then be used to read content using the†paths defined above:
The first read API returns a String containing the name of JsonPath creator, while the second returns a list of its addresses. And we’ll use the JUnit Assert API to confirm the methods work as expected:
Now that we’re done with the basics, let’s define a new JSON example to work on and illustrate the creation and usage of predicates:
Predicates determine true or false input values for filters to narrow down returned lists to only matched objects or arrays. A Predicate may easily be integrated into a Filter by using as an argument for its static factory method. The requested content can then be read out of a JSON string using that Filter:
We may also define our own customized Predicate and use it as an argument for the read API:
Finally, a predicate may be directly applied to read API without creation of any objects, which is called inline predicate:
All the three of the Predicate examples above are verified with the help of the following assertion helper method:
Jayway JsonPath provides several options to tweak the default configuration:
- Option.AS_PATH_LIST: Returns paths of the evaluation hits instead of their values.
- Option.DEFAULT_PATH_LEAF_TO_NULL: Returns null for missing leaves.
- Option.ALWAYS_RETURN_LIST: Returns a list even when the path is definite.
- Option.SUPPRESS_EXCEPTIONS: Makes sure no exceptions are propagated from path evaluation.
- Option.REQUIRE_PROPERTIES: Requires properties defined in path when an indefinite path is evaluated.
Here is how Option is applied from scratch:
and how to add it to an existing configuration:
JsonPath’s default configuration with the help of Option should be enough for the majority of tasks. However, users with more complex use cases are able to modify the behavior of JsonPath according to their specific requirements – using three different SPIs:
- JsonProvider SPI: Lets us change the ways JsonPath parses and handles JSON documents
- MappingProvider SPI: Allows for customization of bindings between node values and returned object types
- CacheProvider SPI: Adjusts the manners that paths are cached, which can help to increase performance
6. An Example Use Cases
Now that we have a good understanding of the functionality that JsonPath can be used for – let’s look at an example.
This section illustrates dealing with JSON data returned from a web service – assume we have a movie information service, which returns the following structure:
Where the value of release date field is duration since the Epoch in milliseconds, and box office is revenue of a movie in the cinema in US dollars
We are going to handle five different working scenarios related to GET requests, supposing that the above JSON hierarchy has been extracted and stored in a String variable named jsonString.
6.1. Getting Object Data Given IDs
In this use case, a client requests detailed information on a specific movie by providing the server with the exact id of that one. This example demonstrates how the server looks for requested data before returning to the client.
Say we need to find a record with id equaling to 2. Below is how the process is implemented and tested.
The first step is to pick up the correct data object:
The JUnit Assert API confirms the existence of several fields:
6.2. Getting the Movie Title Given Starring
Let’s say we want to look for a movie starring an actress called Eva Green. Generally, the server needs to return title of the movie that Eva Green is included in the starring array.
The succeeding test will illustrate how to do that and validate the returned result:
6.3. Calculation of the Total Revenue
This scenario makes use of a JsonPath function called length() to figure out the number of movie records, in order to calculate the total revenue of all the movies. The implementation and testing are demonstrated as follows:
6.4. Highest Revenue Movie
This use case exemplifies the usage of a non-default JsonPath configuration option, namely Option.AS_PATH_LIST, to find out the movie with highest revenue. The particular steps are described underneath.
At first, we need to extract a list of all the movies’ box office revenue, then convert it to an array for sorting:
The highestRevenue variable may easily be picked up from the revenueArray sorted array, then used for working out the path to the movie record with highest revenue:
Based on that calculated path, title of the corresponding movie can be determined and returned:
The whole process is verified by the Assert API:
6.5. Latest Movie of a Director
This example will illustrate the way to figure out the lasted movie directed by a director named Sam Mendes.
To begin with, a list of all the movies directed by Sam Mendes is created:
That list is used for extraction of release dates. Those dates will be stored in an array and then sorted:
The lastestTime variable, which is the last element of the sorted array, is used in combination with the director field’s value to determine title of the requested movie:
The following assertion proved that everything works as expected:
This tutorial has covered fundamental features of Jayway JsonPath – a powerful tool to traverse and parse JSON documents.
Although JsonPath has some drawbacks, such as a lack of operators for reaching parent or sibling nodes, it can be highly useful in a lot of scenarios.
The implementation of all these examples and code snippets can be found in a GitHub project.
This article is by Eugen Paraschiv from baeldung.com.