JarCastingJsonPathKt
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
| Operator | Description |
|---|---|
$ |
The root element to query. This begins all path expressions. |
.. |
Deep scan for values behind followed key value accessor |
.<name> |
Dot-notated key value accessor for JSON objects |
['<name>' (, '<name>')] |
Bracket-notated key value accessor for JSON objects, comma-delimited |
[<number> (, <number>)] |
JSON array accessor for index or comma-delimited indices |
[start:end] |
JSON array range accessor from start (inclusive) to end (exclusive) |
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
}
]
}
}
| JsonPath | Result |
|---|---|
| $.family | The family object |
| $.family.children | The children array |
| $.family['children'] | The children array |
| $.family.children[2] | The second child object |
| $.family.children[-1] | The last child object |
| $.family.children[-3] | The 3rd to last child object |
| $.family.children[1:3] | The 2nd and 3rd children objects |
| $.family.children[:3] | The first three children |
| $.family.children[:-1] | The first three children |
| $.family.children[2:] | The last two children |
| $.family.children[-2:] | The last two children |
| $..name | All names |
| $.family..name | All names nested within family object |
| $.family.children[:3]..age | The ages of first three children |
| $..['name','nickname'] | Names & nicknames (if any) of all children |
| $.family.children[0].* | Names & age values of first child |
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
| Path Tested | JsonPathKt (ms) | JsonPath (ms) |
|---|---|---|
| $[0].friends[1].other.a.b['c'] | 88 ms (35 ms w/ cache) | 144 ms (79 ms w/ cache) |
| $[2]._id | 34 ms (14 ms w/ cache) | 48 ms (28 ms w/ cache) |
| $..name | 82 ms (84 ms w/ cache) | 450 ms (572 ms w/ cache) |
| $..['email','name'] | 116 ms (108 ms w/ cache) | 479 ms (522 ms w/ cache) |
| $..[1] | 203 ms (202 ms w/ cache) | 401 ms (423 ms w/ cache) |
| $..[:2] | 352 ms (346 ms w/ cache) | 442 ms (437 ms w/ cache) |
| $..[2:] | 426 ms (419 ms w/ cache) | 476 ms (470 ms w/ cache) |
| $[0]['tags'][-3] | 67 ms (17 ms w/ cache) | 83 ms (37 ms w/ cache) |
| $[0]['tags'][:3] | 90 ms (36 ms w/ cache) | 103 ms (55 ms w/ cache) |
| $[0]['tags'][3:] | 97 ms (48 ms w/ cache) | 112 ms (65 ms w/ cache) |
| $[0]['tags'][3:5] | 85 ms (29 ms w/ cache) | 101 ms (50 ms w/ cache) |
| $[0]['tags'][0,3,5] | 95 ms (36 ms w/ cache) | 122 ms (52 ms w/ cache) |
| $[0]['latitude','longitude','isActive'] | 97 ms (36 ms w/ cache) | 124 ms (59 ms w/ cache) |
| $[0]['tags'].* | 88 ms (47 ms w/ cache) | 121 ms (86 ms w/ cache) |
| $[0]..* | 828 ms (796 ms w/ cache) | 797 ms (830 ms w/ cache) |
Compiling JsonPath strings to internal tokens
| Path size | JsonPathKt | JsonPath |
|---|---|---|
| 7 chars, 1 tokens | 14 ms (2 ms w/ cache) | 9 ms (9 ms w/ cache) |
| 16 chars, 3 tokens | 26 ms (2 ms w/ cache) | 25 ms (25 ms w/ cache) |
| 30 chars, 7 tokens | 55 ms (2 ms w/ cache) | 63 ms (57 ms w/ cache) |
| 65 chars, 16 tokens | 114 ms (2 ms w/ cache) | 157 ms (142 ms w/ cache) |
| 88 chars, 19 tokens | 205 ms (2 ms w/ cache) | 234 ms (204 ms w/ cache) |
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) { ... }
})