{"id":24840488,"url":"https://github.com/tuliren/json_tuple","last_synced_at":"2025-08-29T02:38:26.291Z","repository":{"id":39583441,"uuid":"95036013","full_name":"tuliren/json_tuple","owner":"tuliren","description":"A json tool that can convert json objects from / to key value tuples.","archived":false,"fork":false,"pushed_at":"2025-07-12T02:02:28.000Z","size":48,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-12T04:10:23.582Z","etag":null,"topics":["json","key-value"],"latest_commit_sha":null,"homepage":"https://github.com/tuliren/json_tuple","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuliren.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-21T18:51:18.000Z","updated_at":"2025-07-12T02:02:31.000Z","dependencies_parsed_at":"2022-09-04T09:50:40.535Z","dependency_job_id":null,"html_url":"https://github.com/tuliren/json_tuple","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tuliren/json_tuple","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuliren%2Fjson_tuple","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuliren%2Fjson_tuple/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuliren%2Fjson_tuple/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuliren%2Fjson_tuple/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuliren","download_url":"https://codeload.github.com/tuliren/json_tuple/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuliren%2Fjson_tuple/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272612205,"owners_count":24964388,"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","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["json","key-value"],"created_at":"2025-01-31T06:57:29.483Z","updated_at":"2025-08-29T02:38:26.252Z","avatar_url":"https://github.com/tuliren.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Json Tuple\n===\n\n[![Build Status](https://github.com/tuliren/json_tuple/workflows/build/badge.svg)](https://github.com/tuliren/json_tuple/actions)\n\n## Overview\n\nJson Tuple is a json tool that can **convert json objects from / to key value tuples**. This tool was originally created to parse and store json objects in database tables for [Jack](https://github.com/LiveRamp/jack).\n\n## How to Use\n\n```java\nJsonObject json1 = new JsonParser()\n    .parse(\"{k1: v1, k2: [v1, v2, v3], ...}\")\n    .getAsJsonObject();\n\n// from json object to tuples\nList\u003cJsonTuple\u003e tuples = JsonTuples.toTuples(json);\n\n// from tuples to json object\nJsonObject json2 = JsonTuples.fromTuples(tuples);\n\n// json1 is equal to json2\nassert json1.equals(json2)\n```\n\n## How to Install\n\nCheck the latest version [here](https://github.com/tuliren/json_tuple/packages/108692), and add this to `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003edev.tuliren\u003c/groupId\u003e\n  \u003cartifactId\u003ejson_tuple\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.0-snapshot\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nRun through command line:\n\n```sh\nmvn install\n```\n\n## How It Works\nEach json key value pair is converted to a [`JsonTuple`](https://github.com/tuliren/json_tuple/blob/master/src/main/java/com/github/tuliren/json_tuple/JsonTuple.java), which keeps track of the key ([`KeyPath`](https://github.com/tuliren/json_tuple/blob/master/src/main/java/com/github/tuliren/json_tuple/KeyPath.java)), value and value type ([`ValueType`](https://github.com/tuliren/json_tuple/blob/master/src/main/java/com/github/tuliren/json_tuple/ValueType.java)). There are five different value types: string, boolean, number, empty, and null.\n\n### Basic Element\n\nA simple and flat json object will be resolved to the following key value pairs:\n```java\n{\n  \"k1\": \"string\",\n  \"k2\": 10,\n  \"k3\": 5.5,\n  \"k4\": true,\n  \"k5\": \"\",\n  \"k6\": null,\n  null: \"null-key\",\n  \"null\": \"null-string-key\"\n}\n```\n\nTuple | Key | Value | Value Type\n---- | ---- | ---- | ----\n1 | \"k1\" | \"string\" | JSON_STRING\n2 | \"k2\" | 10 | JSON_NUMBER\n3 | \"k3\" | 5.5 | JSON_NUMBER\n4 | \"k4\" | `true` | JSON_BOOLEAN\n5 | \"k5\" | | JSON_EMPTY\n6 | \"k6\" | `null` | JSON_NULL\n7 | `null` | \"null-key\" | JSON_STRING\n8 | \"null\" | \"null-string-key\" | JSON_STRING\n\nTheir key is wrapped in [`ElementKeyPath`](https://github.com/tuliren/json_tuple/blob/master/src/main/java/com/github/tuliren/json_tuple/ElementKeyPath.java).\n\n### Nested Element\nA nested json element has more complicated keys (still wrapped in [`ElementKeyPath`](https://github.com/tuliren/json_tuple/blob/master/src/main/java/com/github/tuliren/json_tuple/ElementKeyPath.java)). Its key path is a concatenation of all parent keys joined by dots (`.`).\n\n```json\n{\n  \"k1\": {\n    \"nest1\": 10,\n    \"nest2\": 20\n  },\n  \"k2\": {\n    \"nest1\": 55,\n    \"nest2\": 56,\n    \"nest3\": {\n      \"double-nest1\": 100,\n      \"double-nest2\": 200\n    }\n  }\n}\n```\n\nTuple | Key | Value | Value Type\n---- | ---- | ---- | ----\n1 | \"k1.nest1\" | 10 | JSON_NUMBER\n2 | \"k1.nest2\" | 20 | JSON_NUMBER\n3 | \"k2.nest1\" | 55 | JSON_NUMBER\n4 | \"k2.nest2\" | 56 | JSON_NUMBER\n5 | \"k2.nest3.double-nest1\" | 100 | JSON_NUMBER\n6 | \"k2.nest3.double-nest2\" | 100 | JSON_NUMBER\n\nThe order of the tuples matters. The parser assumes that their order remains the same as they are generated. If they are disarranged, exception may be thrown, or an incorrect json may be created.\n\n### Array\nElements in a json array have even more complicated keys. It is wrapped in [`ArrayKeyPath`](https://github.com/tuliren/json_tuple/blob/master/src/main/java/com/github/tuliren/json_tuple/ArrayKeyPath.java), which keeps track of the total size of the array in which the element resides, as well as the index of this element. In this way, tuples can be constructed back into a json array.\n\n```json\n{\n  \"key\": [\n      1,\n      2.5,\n      true,\n      \"string\",\n      [100, 200]\n  ]\n}\n```\n\nTuple | Key | Value | Value Type\n---- | ---- | ---- | ----\n1 | \"key\\|0\\|5\" | 1 | JSON_NUMBER\n2 | \"key\\|1\\|5\" | 2.5 | JSON_NUMBER\n3 | \"key\\|2\\|5\" | `true` | JSON_BOOLEAN \n4 | \"key\\|3\\|5\" | \"string\" | JSON_STRING \n5 | \"key\\|4\\|5.\\|0\\|2\" | 100 | JSON_NUMBER\n6 | \"key\\|4\\|5.\\|1\\|2\" | 200 | JSON_NUMBER\n\nThe array key path is composed of three parts: array name, index, and size. Each part is separated by `|`. Nested array may not have a name, in that case the array name is empty. That's why the key for tuple 5 is `key|4|5.|1|2`. In this path, `key|4|5` is its parent key. `|0|2` is the nameless array element key, meaning that it is the `0` element in an array of size `2`. The two keys are joined with a `.`.\n\n### More Examples\nFor more examples, please see [`TestJsonTuples`](https://github.com/tuliren/json_tuple/blob/master/src/test/java/com/github/tuliren/json_tuple/TestJsonTuples.java).\n\n## Gotcha\n- Neither key or values should include `.` or `|`, as these two characters are used as key path separator and array path separator, respectively. If a json object has these characters, it cannot be processed correctly. This issue can be fixed in a future version that allows users to customize these separators.\n- The order of the tuples matters. The parser assumes that their order remains the same as they are generated. If they are disarranged, exception may be thrown, or an incorrect json may be created.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuliren%2Fjson_tuple","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuliren%2Fjson_tuple","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuliren%2Fjson_tuple/lists"}