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 hashes)

Uploaded Source

Built Distribution

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

Uploaded Python 3

Supported by

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