Simple library to provide fluent interface for JSON assertions
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Maven Central

JSON Assert

Small library for those who have a hard time understanding the complexity of JSON Path.


Have you ever met such a JSON Path expression?

$[*].place.bounding_box.coordinates[*][*][?(@ == 38.791645)]

Pretty isn’t it? Wouldn’t it be better to just read:


JSON Assert to the rescue!

Fast intro


The library has a couple of main classes. One is JsonAssertion that gives you public static methods:

public static JsonVerifiable assertThat(String body)

NOTE! The aforementioned version caches the DocumentContext for the provided JSON.


public static JsonVerifiable assertThat(DocumentContext parsedJson)

Both these methods give return the public JsonVerifiable interface which is a fluent interface with which you can build your JSON path expression. Please check the Javadocs of that file for more information.

Building JSON Paths

As you could see it’s not that easy to build a JSON Path. With JSON Assert you can use the JsonPath class to finally build the JSON Paths yourself! This is the contract for the JsonPath class:

 * Returns a builder of {@link JsonVerifiable} with which you can build your
 * JSON Path. Once finished just call {@link JsonVerifiable#jsonPath()} to get
 * JSON Path as String.
public static JsonVerifiable builder()

and when you call:


you will receive $.some.nested.withlist[*][?( == 'name1')] String.

Retrieving JSON Path value (since 0.4.0)

Wouldn’t it be great to retrieve the value from the JSON via the JSON Path? There you go!

    String json = ''' [ {
                            "some" : {
                                "nested" : {
                                    "json" : "with value",
                                    "anothervalue": 4,
                                    "withlist" : [
                                        { "name" :"name1"} ,
                                        {"name": "name2"},
                                        {"anothernested": { "name": "name3"} }
                            "someother" : {
                                "nested" : {
                                    "json" : true,
                                    "anothervalue": 4,
                                    "withlist" : [
                                        { "name" :"name1"} , {"name": "name2"}
                                    "withlist2" : [
                                        "a", "b"
        com.toomuchcoding.jsonassert.JsonPath.builder(json).array().field("some").field("nested").field("json").read(String) == 'with value'
        com.toomuchcoding.jsonassert.JsonPath.builder(json).array().field("some").field("nested").field("anothervalue").read(Integer) == 4
        assertThat(json).array().field("some").field("nested").array("withlist").field("name").read(List) == ['name1', 'name2']
        assertThat(json).array().field("someother").field("nested").array("withlist2").read(List) == ['a', 'b']
        assertThat(json).array().field("someother").field("nested").field("json").read(Boolean) == true

All thanks to the JsonReader interface:

 * Returns the value from the JSON, based on the created JSON Path. If the result is an
 * JSON Array and has a single value then that value is returned. If that's an array with
 * greater number of results then that array is returned.
<T> T read(Class<T> clazz);

How to add it

Just add it as your dependency (Example for Gradle)

testCompile 'com.toomuchcoding.jsonassert:jsonassert:0.4.13'


JSON Assert is really lightweight. It has only one dependency

compile "com.jayway.jsonpath:json-path:2.2.0"


Example 1

For the JSON

        "some" : {
            "nested" : {
                "json" : "with \"val'ue",
                "anothervalue": 4,
                "withlist" : [
                    { "name" :"name1"} ,
                    {"name": "name2"}

The following is true

JSON Assert expressions:

JsonAssertion.assertThat(json).field("some").field("nested").field("json").isEqualTo("with \"val'ue")

Respective JSON Path expressions:

$.some.nested[?(@.anothervalue == 4)]
$.some.nested.withlist[*][?( == 'name1')]
$.some.nested.withlist[*][?( == 'name2')]
$.some.nested[?(@.json == 'with "val\\'ue')]

Example 2

For the JSON


The following is true

JSON Assert expressions:


Respective JSON Path expressions:

$[*].place.bounding_box.coordinates[*][*][?(@ == 38.995548)]
$[*].place.bounding_box.coordinates[*][*][?(@ == -77.119759)]
$[*].place.bounding_box.coordinates[*][*][?(@ == -76.909393)]
$[*].place.bounding_box.coordinates[*][*][?(@ == 38.791645)]

More examples

More examples can be found in the JsonAssertionSpec in the test sources

Additional features

AssertJ integration (since 0.2.0)

There is a possibility to use JSON Assert via AssertJ. Regardless of which version you’ll choose you have the same class that you can use to start the fluent assertion

The standard version

com.toomuchcoding.jsonassert.JsonAssertions.assertThat(DocumentContext context);
com.toomuchcoding.jsonassert.JsonAssertions.assertThat(JsonVerifiable jsonVerifiable);

or the BDD version

com.toomuchcoding.jsonassert.BDDJsonAssertions.then(DocumentContext context);
com.toomuchcoding.jsonassert.BDDJsonAssertions.then(JsonVerifiable jsonVerifiable);

AssertJ 2.x

Just add

testCompile 'com.toomuchcoding.jsonassert:jsonassert-assertj-java7:0.4.13'

AssertJ 3.x

Just add

testCompile 'com.toomuchcoding.jsonassert:jsonassert-assertj-java8:0.4.13'


From 0.1.x → 0.2.0

  • Convert all project imports from com.blogspot.toomuchcoding:jsonassert to com.toomuchcoding.jsonassert:jsonassert

  • Convert all code imports from com.blogspot.toomuchcoding.jsonassert to com.toomuchcoding.jsonassert