JsonPathKt

A lighter and more efficient implementation of JsonPath in Kotlin. With functional programming aspects found in langauges like Kotlin, Scala, and streams/lambdas in Java8, this library simplifies other implementations like Jayway's JsonPath by removing filter operations and in-path functions to focus on what matters most: modern fast value extractions from JSON objects. Up to 4x more efficient in some cases; see Benchmarks.

In order to make the library functional programming friendly, JsonPathKt returns null instead of throwing exceptions while evaluating a path against a JSON object. Throwing exceptions breaks flow control and should be reserved for exceptional errors only.

Code examples

A jsonpath that exists returns that value. null is returned when it doesn't.

val json = """{"hello": "world"}"""
JsonPath.parse(json)?.read<String>("$.hello") // returns "world"
JsonPath.parse(json)?.read<String>("$.somethingelse") // returns null since "somethingelse" key not found

A jsonpath that returns a collection containing the 2nd and 3rd items in the list (index 0 based and exclusive at range end).

val json = """{"list": ["a","b","c","d"]}"""
JsonPath.parse(json)?.read<List<String>>("$.list[1:3]") // returns listOf("b", "c")

JsonPathKt also works with Map and POJO.

val json = """[{ "outer": {"inner": 1} }]"""
JsonPath.parse(json)?.read<Map<String, Int>>("$[0].outer") // returns mapOf("inner" to 1)
data class ParsedResult(val outer: Map<String, Int>) // define this class in file scope, not in function scope which will anonymize it 
JsonPath.parse(json)?.read<ParsedResult>("$[0]") // returns ParsedResult instance

Internally, a jsonpath is compiled into a list of tokens. You can compile a complex jsonpath once and reuse it across multiple JSON strings.

val jsonpath = JsonPath("$.family.children..['name','nickname']")
jsonpath.readFromJson<List<Map<String, String>>>(json1)
jsonpath.readFromJson<List<Map<String, String>>>(json2)

JsonPathKt uses Jackson to deserialize JSON strings. JsonPath.parse returns a Jackson JsonNode object, so if you've already deserialized, you can also read the jsonpath value directly.

Getting started

JsonPathKt is available at the Maven Central repository.

POM

<dependency>
  <groupId>com.nfeld.jsonpathkt</groupId>
  <artifactId>jsonpathkt</artifactId>
  <version>2.0.0</version>
</dependency>

Gradle

dependencies {
    implementation 'com.nfeld.jsonpathkt:jsonpathkt:2.0.0'
}

Accessor operators

Path expression examples

JsonPathKt expressions can use any combination of dot–notation and bracket–notation operators to access JSON values. For examples, these all evaluate to the same result:

$.family.children[0].name
$['family']['children'][0]['name']
$['family'].children[0].name

Given the JSON:

{
    "family": {
        "children": [{
                "name": "Thomas",
                "age": 13
            },
            {
                "name": "Mila",
                "age": 18
            },
            {
                "name": "Konstantin",
                "age": 29,
                "nickname": "Kons"
            },
            {
                "name": "Tracy",
                "age": 4
            }
        ]
    }
}

Benchmarks

These are benchmark tests of JsonPathKt against Jayway's JsonPath implementation. Results for each test is the average of 30 runs with 80,000 reads per run and each test returns its own respective results (some larger than others). You can run these tests locally with ./runBenchmarks.sh

Evaluating/reading path against large JSON

Compiling JsonPath strings to internal tokens

Cache

JsonPathKt uses an LRU cache by default to cache compiled JsonPath tokens. If you don't want to use the cache, you can disable it or set the CacheProvider to use your own implementation of the Cache interface.

// Disable cache
CacheProvider.setCache(null)

// Implement your own cache
CacheProvider.setCache(object : Cache {
    override fun get(path: String): JsonPath? { ... }
    override fun put(path: String, jsonPath: JsonPath) { ... }
})