Skip to main content

Python functions for flattening a JSON object to a single dictionary of pairs, and unflattening that dictionary back to a JSON object

Project description

json-flatten

PyPI Changelog Tests License

Python functions for flattening a JSON object to a single dictionary of pairs, and unflattening that dictionary back to a JSON object.

This 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.

For example:

>>> import json_flatten
>>> json_flatten.flatten({"foo": {"bar": [1, True, None]}})
{'foo.bar.[0]$int': '1', 'foo.bar.[1]$bool': 'True', 'foo.bar.[2]$none': 'None'}
>>> json_flatten.unflatten(_)
{'foo': {'bar': [1, True, None]}}

The top-level object passed to flatten() must be a dictionary.

JSON flattening format

Basic principles

  1. Keys are constructed using dot notation to represent nesting.
  2. Type information is preserved using $type suffixes.
  3. List indices are represented using [index] notation.
  4. Empty objects and lists have special representations.

Nested objects

For nested objects, keys are constructed by joining the nested keys with dots.

Example:

{
  "user": {
    "name": "John",
    "age": 30
  }
}

Flattened:

user.name=John
user.age$int=30

Lists

List items are represented using [index] notation.

Example:

{
  "fruits": [
    "apple",
    "banana",
    "cherry"
  ]
}

Flattened:

fruits.[0]=apple
fruits.[1]=banana
fruits.[2]=cherry

Nested lists

For nested lists, the index notation is repeated.

Example:

{"matrix": [[1, 2], [3, 4]]}

Flattened:

matrix.[0].[0]$int=1
matrix.[0].[1]$int=2
matrix.[1].[0]$int=3
matrix.[1].[1]$int=4

Type preservation

Types are preserved using $type suffixes:

Type Suffix Example
String name=Cleo
Integer $int age$int=30
Float $float price$float=19.99
Boolean $bool active$bool=True
Null $none data$none=None
Empty object $empty obj$empty={}
Empty list $emptylist list$emptylist=[]

String values do not require a type suffix.

Example

JSON:

{
  "user": {
    "name": "Alice",
    "age": 28,
    "hobbies": [
      "reading",
      "swimming"
    ],
    "address": {
      "street": "123 Main St",
      "city": "Anytown"
    },
    "active": true,
    "salary": 50000.5,
    "spouse": null
  }
}

Flattened:

user.name=Alice
user.age$int=28
user.hobbies.[0]=reading
user.hobbies.[1]=swimming
user.address.street=123 Main St
user.address.city=Anytown
user.active$bool=True
user.salary$float=50000.5
user.spouse$none=None

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

json_flatten-0.3.1.tar.gz (8.3 kB view details)

Uploaded Source

Built Distribution

json_flatten-0.3.1-py3-none-any.whl (8.5 kB view details)

Uploaded Python 3

File details

Details for the file json_flatten-0.3.1.tar.gz.

File metadata

  • Download URL: json_flatten-0.3.1.tar.gz
  • Upload date:
  • Size: 8.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for json_flatten-0.3.1.tar.gz
Algorithm Hash digest
SHA256 70e813acf431b1ab7e9eb7b98f5733d307d6b9d27b553a344904b9c8eafdad3a
MD5 3dee06b8e645d081269ed76fe501cd71
BLAKE2b-256 a106e6a7046e71488a899a990206dc2426e8b9192ab7a341bb95a75ac1c88922

See more details on using hashes here.

File details

Details for the file json_flatten-0.3.1-py3-none-any.whl.

File metadata

  • Download URL: json_flatten-0.3.1-py3-none-any.whl
  • Upload date:
  • Size: 8.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for json_flatten-0.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 26470dbe9d6d7eb1b7f69c59ba2ade9d52608a76b8443e4654f3adb9c78c1c3e
MD5 b5f7dca5494635a1dc42cc217808933a
BLAKE2b-256 9bed75de9521770184c783ec0d4d75c0bb00f99ac7a21bca48adf9df596483c3

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page