JsonPathKt

A lighter and more efficient implementation of JsonPath in Kotlin Multiplatform (KMP). With functional programming aspects found in languages 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 7x 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.

Credit

Ported from @codeniko JsonPathKt

Getting started

JsonPathKt is available at the Maven Central repository.

Kotlinx Serialization

You can use JsonPathKt with Kotlinx Serialization in your KMP projects.

It targets JVM, JS (node and browser), and all native targets.

dependencies {
    implementation("com.eygraber:jsonpathkt-kotlinx:3.0.2")
}

JSON-java (org.json)

You can use JsonPathKt with JSON-java (org.json) in your JVM projects.

dependencies {
    implementation("com.eygraber:jsonpathkt-jsonjava:3.0.2")
}

Code examples

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.compile("$.family.children..['name','nickname']")

JsonPath.resolveOrNull will return your implementation's native JSON type. JsonPath.resolveAsStringOrNull will return a String if that is what is resolved, otherwise it will return null.

jsonpath.resolveOrNull(json1)
jsonpath.resolveAsStringOrNull(json2)

Each implementation provides extension functions on its JSON types to allow for easy resolution. Using Kotlinx Serialization as an example:

val json = Json.parseToJsonElement("""{"hello": "world"}""")
val helloPath = JsonPath.compile("$.hello")
val somethingElsePath = JsonPath.compile("$.somethingelse")

json?.resolveOrNull(helloPath) // returns JsonPrimitve("world")
json?.resolveAsStringOrNull(helloPath) // returns "world"

json?.resolvePathOrNull("$.hello") // returns JsonPrimitve("world")
json?.resolvePathAsStringOrNull("$.hello") // returns "world"

json?.resolveOrNull(somethingElsePath) // returns null since "somethingelse" key not found
json?.resolveAsStringOrNull(somethingElsePath) // returns null since "somethingelse" key not found

json?.resolvePathOrNull("$.somethingelse") // returns null since "somethingelse" key not found
json?.resolvePathAsStringOrNull("$.somethingelse") // returns null since "somethingelse" key not found

Another example; 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 = Json.parseToJsonElement("""{"list": ["a","b","c","d"]}""")

json?.resolvePathOrNull("$.list[1:3]") // returns JsonArray(listOf("b", "c"))
json?.resolvePathAsStringOrNull("$.list[1:3]") // returns null since the result is not a String

If you want to resolve a JSON type as a String, you can use resolvePathOrNull and your implementation's JSON type to do that:

val json = Json.parseToJsonElement("""{"list": ["a","b","c","d"]}""")

json?.resolvePathOrNull("$.list[1:3]")?.toString // returns '["b", "c"]'

Accessor operators

Edge cases

This section will try to keep track of the edge cases where behavior might not be what you expect.

Range steps

Ranges use the array slice operator, i.e. [start:end:step]. The step value is not (currently) supported and behavior is undefined if there is a step value present.

Unions and Ranges

When an expression contains both unions ([,]) and ranges (start:send) the ranges will be resolved first, resulting in the resolved range being present in the final set.

Given the JSON:

[1, 2, 3, 4]

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 other implementations. 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).

Evaluating/reading path against large JSON

Compiling JsonPath strings to internal tokens