{"id":15432959,"url":"https://github.com/simonw/json-flatten","last_synced_at":"2025-08-02T20:06:31.097Z","repository":{"id":47071371,"uuid":"193191629","full_name":"simonw/json-flatten","owner":"simonw","description":"Python functions for flattening a JSON object to a single dictionary of pairs, and unflattening that dictionary back to a JSON object","archived":false,"fork":false,"pushed_at":"2024-09-07T04:32:44.000Z","size":32,"stargazers_count":47,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-18T07:53:35.844Z","etag":null,"topics":["json","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonw.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-22T04:38:59.000Z","updated_at":"2024-10-13T02:53:16.000Z","dependencies_parsed_at":"2024-10-20T20:19:17.256Z","dependency_job_id":null,"html_url":"https://github.com/simonw/json-flatten","commit_stats":{"total_commits":28,"total_committers":1,"mean_commits":28.0,"dds":0.0,"last_synced_commit":"78c2835bf3b7b7cf068fca04a6cf341347dfa2bc"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Fjson-flatten","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Fjson-flatten/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Fjson-flatten/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonw%2Fjson-flatten/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonw","download_url":"https://codeload.github.com/simonw/json-flatten/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243521281,"owners_count":20304186,"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":["json","python"],"created_at":"2024-10-01T18:29:46.173Z","updated_at":"2025-03-14T04:07:37.445Z","avatar_url":"https://github.com/simonw.png","language":"Python","readme":"# json-flatten\n\n[![PyPI](https://img.shields.io/pypi/v/json-flatten.svg)](https://pypi.org/project/json-flatten/)\n[![Changelog](https://img.shields.io/github/v/release/simonw/json-flatten?include_prereleases\u0026label=changelog)](https://github.com/simonw/json-flatten/releases)\n[![Tests](https://github.com/simonw/json-flatten/workflows/Test/badge.svg)](https://github.com/simonw/json-flatten/actions?query=workflow%3ATest)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/simonw/json-flatten/blob/main/LICENSE)\n\n\nPython functions for flattening a JSON object to a single dictionary of pairs, and unflattening that dictionary back to a JSON object.\n\nThis can be useful if you need to represent a JSON object using a regular HTML form or transmit it as a set of query string parameters.\n\nFor example:\n\n```pycon\n\u003e\u003e\u003e import json_flatten\n\u003e\u003e\u003e json_flatten.flatten({\"foo\": {\"bar\": [1, True, None]}})\n{'foo.bar.[0]$int': '1', 'foo.bar.[1]$bool': 'True', 'foo.bar.[2]$none': 'None'}\n\u003e\u003e\u003e json_flatten.unflatten(_)\n{'foo': {'bar': [1, True, None]}}\n```\n\nThe top-level object passed to `flatten()` must be a dictionary.\n\n## JSON flattening format\n\n### Basic principles\n\n1. Keys are constructed using dot notation to represent nesting.\n2. Type information is preserved using `$type` suffixes.\n3. List indices are represented using `[index]` notation.\n4. Empty objects and lists have special representations.\n\n### Nested objects\n\nFor nested objects, keys are constructed by joining the nested keys with dots.\n\nExample:\n\n\u003c!-- [[[cog\nimport cog\nimport json\nfrom json_flatten import flatten, unflatten\n\nexample = {\n  \"user\": {\n    \"name\": \"John\",\n    \"age\": 30\n  }\n}\n\ncog.out(\"```json\\n\")\ncog.out(json.dumps(example, indent=2))\ncog.out(\"\\n```\\n\")\ncog.out(\"Flattened:\\n```\\n\")\nfor key, value in flatten(example).items():\n    cog.out(f\"{key}={value}\\n\")\ncog.out(\"```\\n\")\n]]] --\u003e\n```json\n{\n  \"user\": {\n    \"name\": \"John\",\n    \"age\": 30\n  }\n}\n```\nFlattened:\n```\nuser.name=John\nuser.age$int=30\n```\n\u003c!-- [[[end]]]  --\u003e\n\n### Lists\n\nList items are represented using `[index]` notation.\n\nExample:\n\u003c!-- [[[cog\nexample = {\n  \"fruits\": [\"apple\", \"banana\", \"cherry\"]\n}\n\ncog.out(\"```json\\n\")\ncog.out(json.dumps(example, indent=2))\ncog.out(\"\\n```\\n\")\ncog.out(\"Flattened:\\n```\\n\")\nfor key, value in flatten(example).items():\n    cog.out(f\"{key}={value}\\n\")\ncog.out(\"```\\n\")\n]]] --\u003e\n```json\n{\n  \"fruits\": [\n    \"apple\",\n    \"banana\",\n    \"cherry\"\n  ]\n}\n```\nFlattened:\n```\nfruits.[0]=apple\nfruits.[1]=banana\nfruits.[2]=cherry\n```\n\u003c!-- [[[end]]] --\u003e\n\n### Nested lists\n\nFor nested lists, the index notation is repeated.\n\nExample:\n\u003c!-- [[[cog\nexample = {\n  \"matrix\": [[1, 2], [3, 4]]\n}\n\ncog.out(\"```json\\n\")\ncog.out(json.dumps(example))\ncog.out(\"\\n```\\n\")\ncog.out(\"Flattened:\\n```\\n\")\nfor key, value in flatten(example).items():\n    cog.out(f\"{key}={value}\\n\")\ncog.out(\"```\\n\")\n]]] --\u003e\n```json\n{\"matrix\": [[1, 2], [3, 4]]}\n```\nFlattened:\n```\nmatrix.[0].[0]$int=1\nmatrix.[0].[1]$int=2\nmatrix.[1].[0]$int=3\nmatrix.[1].[1]$int=4\n```\n\u003c!-- [[[end]]] --\u003e\n\n## Type preservation\n\nTypes are preserved using `$type` suffixes:\n\n\u003c!-- [[[cog\nexamples = (\n    (\"String\", \"\", {\"name\": \"Cleo\"}),\n    (\"Integer\", \"$int\", {\"age\": 30}),\n    (\"Float\", \"$float\", {\"price\": 19.99}),\n    (\"Boolean\", \"$bool\", {\"active\": True}),\n    (\"Null\", \"$none\", {\"data\": None}),\n    (\"Empty object\", \"$empty\", {\"obj\": {}}),\n    (\"Empty list\", \"$emptylist\", {\"list\": []}),\n)\ncog.out(\"| Type | Suffix | Example |\\n\")\ncog.out(\"|------|--------|---------|\\n\")\nfor type_, suffix, example in (examples):\n    key, value = list(flatten(example).items())[0]\n    suffix = f'`{suffix}`' if suffix else ''\n    cog.out(f\"|{type_}|{suffix}|`{key}={value}`|\\n\")\n]]] --\u003e\n| Type | Suffix | Example |\n|------|--------|---------|\n|String||`name=Cleo`|\n|Integer|`$int`|`age$int=30`|\n|Float|`$float`|`price$float=19.99`|\n|Boolean|`$bool`|`active$bool=True`|\n|Null|`$none`|`data$none=None`|\n|Empty object|`$empty`|`obj$empty={}`|\n|Empty list|`$emptylist`|`list$emptylist=[]`|\n\u003c!-- [[[end]]] --\u003e\n\nString values do not require a type suffix.\n\n## Example\n\nJSON:\n\u003c!-- [[[cog\nexample = {\n  \"user\": {\n    \"name\": \"Alice\",\n    \"age\": 28,\n    \"hobbies\": [\"reading\", \"swimming\"],\n    \"address\": {\n      \"street\": \"123 Main St\",\n      \"city\": \"Anytown\"\n    },\n    \"active\": True,\n    \"salary\": 50000.50,\n    \"spouse\": None,\n    \"more_nesting\": {\n      \"empty_lists\": [[], []],\n      \"empty_objects\": [{}, {}]\n    }\n  }\n}\n\ncog.out(\"```json\\n\")\ncog.out(json.dumps(example, indent=2))\ncog.out(\"\\n```\\n\")\ncog.out(\"\\nFlattened with `flattened = flatten(example)`\\n```\\n\")\nflattened = flatten(example)\nfor key, value in flattened.items():\n    cog.out(f\"{key}={value}\\n\")\ncog.out(\"```\\n\")\ncog.out(\"\\nUnflattened again with `unflattened = unflatten(flattened)`\\n\")\ncog.out(\"```json\\n\")\ncog.out(json.dumps(unflatten(flattened), indent=2))\ncog.out(\"\\n```\\n\")\n]]] --\u003e\n```json\n{\n  \"user\": {\n    \"name\": \"Alice\",\n    \"age\": 28,\n    \"hobbies\": [\n      \"reading\",\n      \"swimming\"\n    ],\n    \"address\": {\n      \"street\": \"123 Main St\",\n      \"city\": \"Anytown\"\n    },\n    \"active\": true,\n    \"salary\": 50000.5,\n    \"spouse\": null,\n    \"more_nesting\": {\n      \"empty_lists\": [\n        [],\n        []\n      ],\n      \"empty_objects\": [\n        {},\n        {}\n      ]\n    }\n  }\n}\n```\n\nFlattened with `flattened = flatten(example)`\n```\nuser.name=Alice\nuser.age$int=28\nuser.hobbies.[0]=reading\nuser.hobbies.[1]=swimming\nuser.address.street=123 Main St\nuser.address.city=Anytown\nuser.active$bool=True\nuser.salary$float=50000.5\nuser.spouse$none=None\nuser.more_nesting.empty_lists.[0]$emptylist=[]\nuser.more_nesting.empty_lists.[1]$emptylist=[]\nuser.more_nesting.empty_objects.[0]$empty={}\nuser.more_nesting.empty_objects.[1]$empty={}\n```\n\nUnflattened again with `unflattened = unflatten(flattened)`\n```json\n{\n  \"user\": {\n    \"name\": \"Alice\",\n    \"age\": 28,\n    \"hobbies\": [\n      \"reading\",\n      \"swimming\"\n    ],\n    \"address\": {\n      \"street\": \"123 Main St\",\n      \"city\": \"Anytown\"\n    },\n    \"active\": true,\n    \"salary\": 50000.5,\n    \"spouse\": null,\n    \"more_nesting\": {\n      \"empty_lists\": [\n        [],\n        []\n      ],\n      \"empty_objects\": [\n        {},\n        {}\n      ]\n    }\n  }\n}\n```\n\u003c!-- [[[end]]] --\u003e","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonw%2Fjson-flatten","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonw%2Fjson-flatten","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonw%2Fjson-flatten/lists"}