README.md

json-flatten

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,
    "more_nesting": {
      "empty_lists": [
        [],
        []
      ],
      "empty_objects": [
        {},
        {}
      ]
    }
  }
}

Flattened with flattened = flatten(example)

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
user.more_nesting.empty_lists.[0]$emptylist=[]
user.more_nesting.empty_lists.[1]$emptylist=[]
user.more_nesting.empty_objects.[0]$empty={}
user.more_nesting.empty_objects.[1]$empty={}

Unflattened again with unflattened = unflatten(flattened)

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