{"id":24448492,"url":"https://github.com/codeniko/jsonpathkt","last_synced_at":"2025-07-17T07:32:49.363Z","repository":{"id":38389292,"uuid":"173902316","full_name":"codeniko/JsonPathKt","owner":"codeniko","description":"A lighter and more efficient implementation of JsonPath in Kotlin","archived":false,"fork":false,"pushed_at":"2023-09-11T05:05:09.000Z","size":208,"stargazers_count":62,"open_issues_count":7,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-04T19:42:11.938Z","etag":null,"topics":["jsonpath","kotlin"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeniko.png","metadata":{"files":{"readme":"README.md","changelog":"changelog_config.json","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-03-05T08:05:15.000Z","updated_at":"2024-09-27T08:43:06.000Z","dependencies_parsed_at":"2024-03-17T01:27:43.259Z","dependency_job_id":null,"html_url":"https://github.com/codeniko/JsonPathKt","commit_stats":null,"previous_names":["codeniko/jsonpathlite"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2FJsonPathKt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2FJsonPathKt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2FJsonPathKt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2FJsonPathKt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeniko","download_url":"https://codeload.github.com/codeniko/JsonPathKt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234875546,"owners_count":18900160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jsonpath","kotlin"],"created_at":"2025-01-21T00:22:39.357Z","updated_at":"2025-01-21T00:22:40.378Z","avatar_url":"https://github.com/codeniko.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JsonPathKt\n[![Build Status](https://travis-ci.com/codeniko/JsonPathKt.svg?branch=master)](https://travis-ci.com/codeniko/JsonPathKt)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.nfeld.jsonpathkt/jsonpathkt/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.nfeld.jsonpathkt/jsonpathkt)\n[![codecov](https://codecov.io/gh/codeniko/JsonPathKt/branch/master/graph/badge.svg)](https://codecov.io/gh/codeniko/JsonPathKt)\n\n**A lighter and more efficient implementation of JsonPath in Kotlin.**\nWith functional programming aspects found in langauges like Kotlin, Scala, and streams/lambdas in Java8, this\nlibrary simplifies other implementations like [Jayway's JsonPath](https://github.com/json-path/JsonPath) by removing \n*filter operations* and *in-path functions* to focus on what matters most: modern fast value extractions from JSON objects. \nUp to **4x more efficient** in some cases; see [Benchmarks](#benchmarks).\n\nIn order to make the library functional programming friendly, JsonPathKt returns `null` instead of throwing exceptions \nwhile evaluating a path against a JSON object. Throwing exceptions breaks flow control and should be reserved for exceptional \nerrors only.\n\n## Code examples\nA jsonpath that exists returns that value. `null` is returned when it doesn't.\n```kotlin\nval json = \"\"\"{\"hello\": \"world\"}\"\"\"\nJsonPath.parse(json)?.read\u003cString\u003e(\"$.hello\") // returns \"world\"\nJsonPath.parse(json)?.read\u003cString\u003e(\"$.somethingelse\") // returns null since \"somethingelse\" key not found\n```\n\nA jsonpath that returns a collection containing the 2nd and 3rd items in the list (index 0 based and exclusive at range end).\n```kotlin\nval json = \"\"\"{\"list\": [\"a\",\"b\",\"c\",\"d\"]}\"\"\"\nJsonPath.parse(json)?.read\u003cList\u003cString\u003e\u003e(\"$.list[1:3]\") // returns listOf(\"b\", \"c\")\n```\n\nJsonPathKt also works with `Map` and POJO.\n```kotlin\nval json = \"\"\"[{ \"outer\": {\"inner\": 1} }]\"\"\"\nJsonPath.parse(json)?.read\u003cMap\u003cString, Int\u003e\u003e(\"$[0].outer\") // returns mapOf(\"inner\" to 1)\ndata class ParsedResult(val outer: Map\u003cString, Int\u003e) // define this class in file scope, not in function scope which will anonymize it \nJsonPath.parse(json)?.read\u003cParsedResult\u003e(\"$[0]\") // returns ParsedResult instance\n```\n\nInternally, a jsonpath is compiled into a list of tokens. You can compile a complex jsonpath once and reuse it across multiple JSON strings.\n```kotlin\nval jsonpath = JsonPath(\"$.family.children..['name','nickname']\")\njsonpath.readFromJson\u003cList\u003cMap\u003cString, String\u003e\u003e\u003e(json1)\njsonpath.readFromJson\u003cList\u003cMap\u003cString, String\u003e\u003e\u003e(json2)\n```\n\n*JsonPathKt uses [Jackson](https://github.com/FasterXML/jackson) to deserialize JSON strings. `JsonPath.parse` returns a Jackson \n`JsonNode` object, so if you've already deserialized, you can also `read` the jsonpath value directly.*\n\n\n## Getting started\nJsonPathKt is available at the Maven Central repository.\n\n**POM**\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.nfeld.jsonpathkt\u003c/groupId\u003e\n  \u003cartifactId\u003ejsonpathkt\u003c/artifactId\u003e\n  \u003cversion\u003e2.0.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Gradle**\n```gradle\ndependencies {\n    implementation 'com.nfeld.jsonpathkt:jsonpathkt:2.0.1'\n}\n```\n\n## Accessor operators\n\n| Operator                  | Description                                                        |\n| :------------------------ | :----------------------------------------------------------------- |\n| `$`                       | The root element to query. This begins all path expressions.       |\n| `..`                      | Deep scan for values behind followed key value accessor            |\n| `.\u003cname\u003e`                 | Dot-notated key value accessor for JSON objects                    |\n| `['\u003cname\u003e' (, '\u003cname\u003e')]` | Bracket-notated key value accessor for JSON objects, comma-delimited|\n| `[\u003cnumber\u003e (, \u003cnumber\u003e)]` | JSON array accessor for index or comma-delimited indices           |\n| `[start:end]`             | JSON array range accessor from start (inclusive) to end (exclusive)|\n\n## Path expression examples\nJsonPathKt 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:\n```text\n$.family.children[0].name\n$['family']['children'][0]['name']\n$['family'].children[0].name\n```\n\nGiven the JSON:\n```json\n{\n    \"family\": {\n        \"children\": [{\n                \"name\": \"Thomas\",\n                \"age\": 13\n            },\n            {\n                \"name\": \"Mila\",\n                \"age\": 18\n            },\n            {\n                \"name\": \"Konstantin\",\n                \"age\": 29,\n                \"nickname\": \"Kons\"\n            },\n            {\n                \"name\": \"Tracy\",\n                \"age\": 4\n            }\n        ]\n    }\n}\n```\n\n| JsonPath | Result |\n| :------- | :----- |\n| $.family                  |  The family object  |\n| $.family.children         |  The children array  |\n| $.family['children']      |  The children array  |\n| $.family.children[2]      |  The second child object  |\n| $.family.children[-1]     |  The last child object  |\n| $.family.children[-3]     |  The 3rd to last child object  |\n| $.family.children[1:3]    |  The 2nd and 3rd children objects |\n| $.family.children[:3]     |  The first three children |\n| $.family.children[:-1]    |  The first three children |\n| $.family.children[2:]     |  The last two children  |\n| $.family.children[-2:]    |  The last two children  |\n| $..name                   |  All names  |\n| $.family..name            |  All names nested within family object  |\n| $.family.children[:3]..age     |  The ages of first three children |\n| $..['name','nickname']    |  Names \u0026 nicknames (if any) of all children |\n| $.family.children[0].*    |  Names \u0026 age values of first child |\n\n## Benchmarks\nThese are benchmark tests of JsonPathKt against Jayway's JsonPath implementation. Results for each test is the average of \n30 runs with 80,000 reads per run and each test returns its own respective results (some larger than others).\nYou can run these tests locally with `./runBenchmarks.sh`\n\n**Evaluating/reading path against large JSON**\n\n| Path Tested | JsonPathKt (ms) | JsonPath (ms) |\n| :---------- | :------ | :----- |\n|  $[0].friends[1].other.a.b['c']  |  88 ms *(35 ms w/ cache)* |  144 ms *(79 ms w/ cache)*  |\n|  $[2]._id  |  34 ms *(14 ms w/ cache)* |  48 ms *(28 ms w/ cache)*  |\n|  $..name  |  82 ms *(84 ms w/ cache)* |  450 ms *(572 ms w/ cache)*  |\n|  $..['email','name']  |  116 ms *(108 ms w/ cache)* |  479 ms *(522 ms w/ cache)*  |\n|  $..[1]  |  203 ms *(202 ms w/ cache)* |  401 ms *(423 ms w/ cache)*  |\n|  $..[:2]  |  352 ms *(346 ms w/ cache)* |  442 ms *(437 ms w/ cache)*  |\n|  $..[2:]  |  426 ms *(419 ms w/ cache)* |  476 ms *(470 ms w/ cache)*  |\n|  $[0]['tags'][-3]  |  67 ms *(17 ms w/ cache)* |  83 ms *(37 ms w/ cache)*  |\n|  $[0]['tags'][:3]  |  90 ms *(36 ms w/ cache)* |  103 ms *(55 ms w/ cache)*  |\n|  $[0]['tags'][3:]  |  97 ms *(48 ms w/ cache)* |  112 ms *(65 ms w/ cache)*  |\n|  $[0]['tags'][3:5]  |  85 ms *(29 ms w/ cache)* |  101 ms *(50 ms w/ cache)*  |\n|  $[0]['tags'][0,3,5]  |  95 ms *(36 ms w/ cache)* |  122 ms *(52 ms w/ cache)*  |\n|  $[0]['latitude','longitude','isActive']  |  97 ms *(36 ms w/ cache)* |  124 ms *(59 ms w/ cache)*  |\n|  $[0]['tags'].*  |  88 ms *(47 ms w/ cache)* |  121 ms *(86 ms w/ cache)*  |\n|  $[0]..*  |  828 ms *(796 ms w/ cache)* |  797 ms *(830 ms w/ cache)*  |\n\n\n**Compiling JsonPath strings to internal tokens**\n\n| Path size | JsonPathKt | JsonPath |\n| :-------- | :----------- | :------- |\n|  7 chars, 1 tokens  |  14 ms *(2 ms w/ cache)* |  9 ms *(9 ms w/ cache)* |\n|  16 chars, 3 tokens  |  26 ms *(2 ms w/ cache)* |  25 ms *(25 ms w/ cache)* |\n|  30 chars, 7 tokens  |  55 ms *(2 ms w/ cache)* |  63 ms *(57 ms w/ cache)* |\n|  65 chars, 16 tokens  |  114 ms *(2 ms w/ cache)* |  157 ms *(142 ms w/ cache)* |\n|  88 chars, 19 tokens  |  205 ms *(2 ms w/ cache)* |  234 ms *(204 ms w/ cache)* |\n\n# Cache\nJsonPathKt 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.\n```kotlin\n// Disable cache\nCacheProvider.setCache(null)\n\n// Implement your own cache\nCacheProvider.setCache(object : Cache {\n    override fun get(path: String): JsonPath? { ... }\n    override fun put(path: String, jsonPath: JsonPath) { ... }\n})\n```\n\n[![Analytics](https://ga-beacon.appspot.com/UA-116910991-3/jsonpathlite/index)](https://github.com/igrigorik/ga-beacon)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeniko%2Fjsonpathkt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeniko%2Fjsonpathkt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeniko%2Fjsonpathkt/lists"}