Python Working with JSON
JSON (JavaScript Object Notation) is the universal language of the
web — every REST API, config file, and web service communicates in JSON. Python's built-in json module makes encoding and decoding JSON effortless. This chapter is a
complete deep-dive: converting Python objects to JSON strings and back, reading and writing JSON files,
working with nested structures, pretty-printing, handling edge cases, custom serialisation for objects that
JSON can't handle natively, and real-world API patterns.
What is JSON and Why Does it Matter?
JSON (JavaScript Object Notation) is a lightweight, text-based data format that is language-independent and human-readable. It's the standard for web APIs, configuration files, NoSQL databases, and inter-service communication. Every Python developer works with JSON daily.
Encoding — json.dumps() Python → JSON String
json.dumps(obj) serialises a Python object to a
JSON-formatted string. The "s" stands for "string". Use this when you need to send JSON over
a network, store it in a variable, or embed it in code.
import json
# ── Basic types ───────────────────────────────────────
print(json.dumps({"name": "Alice", "age": 25}))
# '{"name": "Alice", "age": 25}'
print(json.dumps([1, 2, "three", True, None]))
# '[1, 2, "three", true, null]'
print(json.dumps(True)) # 'true' ← lowercase in JSON
print(json.dumps(None)) # 'null'
print(json.dumps(3.14)) # '3.14'
# ── Pretty-print with indent ──────────────────────────
data = {
"user": "alice",
"scores": [95, 87, 92],
"active": True,
"address": {"city": "Vadodara", "pin": "390001"}
}
print(json.dumps(data, indent=2))
# {
# "user": "alice",
# "scores": [95, 87, 92],
# "active": true,
# "address": {"city": "Vadodara", "pin": "390001"}
# }
# ── Sorting keys alphabetically ──────────────────────
print(json.dumps(data, sort_keys=True, indent=2))
# ── Compact output (no spaces) ───────────────────────
print(json.dumps(data, separators=(",", ":")))
# {"user":"alice","scores":[95,87,92],"active":true,...}
# ── Non-ASCII characters ─────────────────────────────
msg = {"greeting": "नमस्ते", "emoji": "🐍"}
print(json.dumps(msg)) # escaped unicode
print(json.dumps(msg, ensure_ascii=False)) # actual unicode chars
Decoding — json.loads() JSON String → Python
json.loads(string) deserialises a JSON string into a
Python object. JSON objects become dicts, arrays become lists, true/false become True/False, and null becomes None.
import json
# ── Parse a JSON string ───────────────────────────────
json_str = '{"name": "Alice", "age": 25, "active": true, "score": null}'
data = json.loads(json_str)
print(type(data)) # <class 'dict'>
print(data["name"]) # Alice
print(data["active"]) # True ← Python bool
print(data["score"]) # None ← Python None
print(type(data["age"])) # <class 'int'>
# ── Parse a JSON array ────────────────────────────────
arr_str = '[1, "two", 3.14, true, null]'
arr = json.loads(arr_str)
print(type(arr)) # <class 'list'>
print(arr[0]) # 1
# ── Nested JSON ───────────────────────────────────────
nested = """
{
"id": 1,
"user": {"name": "Bob", "email": "bob@example.com"},
"tags": ["python", "developer"],
"metadata": null
}
"""
obj = json.loads(nested)
print(obj["user"]["email"]) # bob@example.com
print(obj["tags"][0]) # python
# ── Handle JSONDecodeError ────────────────────────────
try:
json.loads("not valid json")
except json.JSONDecodeError as e:
print(f"Error: {e}")
# ── Parse with object_hook — custom decoding ─────────
def as_complex(dct):
if "real" in dct and "imag" in dct:
return complex(dct["real"], dct["imag"])
return dct
z = json.loads('{"real": 3, "imag": 4}', object_hook=as_complex)
print(z) # (3+4j) ← Python complex number!
File I/O — json.dump() and json.load()
json.dump(obj, file) writes JSON directly to an open
file object. json.load(file) reads and parses JSON from an open file
object. No "s" in the name = working with files (not strings).
import json
data = {
"project": "K2infocom Portal",
"version": "2.1.0",
"features": ["auth", "dashboard", "reports"],
"config": {
"debug": False,
"max_users": 1000,
"timeout": 30
}
}
# ── Write JSON to file ────────────────────────────────
with open("config.json", "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
# config.json now contains formatted JSON
# ── Read JSON from file ───────────────────────────────
with open("config.json", encoding="utf-8") as f:
loaded = json.load(f)
print(loaded["project"]) # K2infocom Portal
print(loaded["config"]["debug"]) # False
print(loaded["features"][0]) # auth
# ── Utility functions ─────────────────────────────────
def read_json(path):
"""Read a JSON file and return the parsed object."""
with open(path, encoding="utf-8") as f:
return json.load(f)
def write_json(path, obj, **kwargs):
"""Write a Python object to a JSON file."""
with open(path, "w", encoding="utf-8") as f:
json.dump(obj, f, ensure_ascii=False, **kwargs)
# Usage
write_json("settings.json", data, indent=4)
cfg = read_json("settings.json")
print(cfg["version"]) # 2.1.0
Pretty Printing & Formatting Options
The json module's formatting options let you control
indentation, key ordering, separators, and non-ASCII encoding. Knowing these makes your JSON output
professional and interoperable.
import json
data = {"b": 2, "a": 1, "c": [3, 1, 2]}
# indent — number of spaces (or "\t" for tabs)
print(json.dumps(data, indent=4))
print(json.dumps(data, indent="\t")) # tab indentation
# sort_keys — alphabetical key ordering
print(json.dumps(data, sort_keys=True))
# {"a": 1, "b": 2, "c": [3, 1, 2]}
# separators — customise between items and key:value
# default: (", ", ": ") with spaces
compact = json.dumps(data, separators=(",", ":")) # no spaces
print(compact) # {"b":2,"a":1,"c":[3,1,2]}
# ensure_ascii — True (default): escape non-ASCII; False: output as-is
non_ascii = {"city": "Vadodara 🏙️", "lang": "हिन्दी"}
print(json.dumps(non_ascii))
# {"city": "Vadodara \\ud83c\\udfd9\\ufe0f", "lang": "..."}
print(json.dumps(non_ascii, ensure_ascii=False))
# {"city": "Vadodara 🏙️", "lang": "हिन्दी"}
# allow_nan — control float special values
import math
# json.dumps(math.nan) → 'NaN' (non-standard JSON!)
# json.dumps(math.nan, allow_nan=False) → ValueError!
# Combining options
print(json.dumps(
data,
indent=2,
sort_keys=True,
ensure_ascii=False
))
Custom Serialisation — Dates, Classes & Decimal
Not all Python objects can be converted to JSON natively — datetime, custom classes, Decimal, set, and bytes all require custom
handling. Python provides two ways: a custom encoder class (subclass json.JSONEncoder) or a default function passed to the default parameter.
import json
from datetime import datetime, date
from decimal import Decimal
# ── Method 1: default function ────────────────────────
def json_serialiser(obj):
"""Handle types not natively supported by JSON."""
if isinstance(obj, (datetime, date)):
return obj.isoformat() # "2025-05-16T14:30:00"
if isinstance(obj, Decimal):
return float(obj)
if isinstance(obj, set):
return list(obj)
if isinstance(obj, bytes):
return obj.decode("utf-8")
raise TypeError(f"Type {type(obj)} not serialisable")
payload = {
"created": datetime.now(),
"price": Decimal("99.99"),
"tags": {"python", "web", "api"},
"raw": b"hello",
}
print(json.dumps(payload, default=json_serialiser, indent=2))
# ── Method 2: Custom JSONEncoder class ───────────────
class AppEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, datetime):
return obj.strftime("%Y-%m-%d %H:%M:%S")
if isinstance(obj, Decimal):
return str(obj) # keep precision as string
if hasattr(obj, "__dict__"): # any class instance
return obj.__dict__
return super().default(obj)
print(json.dumps(payload, cls=AppEncoder, indent=2))
# ── Serialise custom class instances ─────────────────
class Product:
def __init__(self, name, price):
self.name = name
self.price = price
p = Product("Laptop", Decimal("49999.00"))
print(json.dumps(p, cls=AppEncoder))
# {"name": "Laptop", "price": "49999.00"}
# ── parse_float — decode JSON numbers as Decimal ─────
precise = json.loads(
'{"price": 99.99}',
parse_float=Decimal # avoids float precision errors
)
print(type(precise["price"])) # <class 'decimal.Decimal'>
print(precise["price"]) # 99.99 (exact)
Real-World JSON Patterns
JSON is the backbone of REST APIs, config files, and data pipelines. Here are the patterns you'll use in every professional Python project:
import json
from pathlib import Path
# ── Pattern 1: Config file management ─────────────────
DEFAULT_CONFIG = {
"database_url": "sqlite:///app.db",
"debug": False,
"allowed_hosts": ["localhost", "127.0.0.1"],
"max_connections": 10,
}
def load_config(path="config.json"):
p = Path(path)
if not p.exists():
write_json(path, DEFAULT_CONFIG)
return DEFAULT_CONFIG.copy()
with p.open(encoding="utf-8") as f:
return {**DEFAULT_CONFIG, **json.load(f)} # merge defaults
# ── Pattern 2: Deep get from nested JSON ──────────────
def deep_get(obj, *keys, default=None):
"""Safely get nested JSON value: deep_get(d, "user", "email")"""
for key in keys:
if isinstance(obj, dict):
obj = obj.get(key, default)
elif isinstance(obj, list) and isinstance(key, int):
obj = obj[key] if key < len(obj) else default
else:
return default
return obj
api_resp = {"data": {"user": {"email": "alice@k2.com"}}}
print(deep_get(api_resp, "data", "user", "email")) # alice@k2.com
print(deep_get(api_resp, "data", "user", "phone", default="N/A"))
# ── Pattern 3: JSON Lines (JSONL) ─────────────────────
# One JSON object per line — common for streaming data / logs
records = [
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"},
{"id": 3, "name": "Carol"},
]
# Write JSONL
with open("data.jsonl", "w", encoding="utf-8") as f:
for rec in records:
f.write(json.dumps(rec) + "\n")
# Read JSONL
with open("data.jsonl", encoding="utf-8") as f:
for line in f:
rec = json.loads(line)
print(rec["name"])
# ── Pattern 4: Validate JSON schema manually ─────────
def validate_user(data):
required = {"name", "email", "age"}
missing = required - set(data.keys())
if missing:
raise ValueError(f"Missing fields: {missing}")
if not isinstance(data["age"], int):
raise TypeError("age must be int")
return True
Practice Python Online — Free Compilers
Don't want to install anything yet? Practice all JSON examples from this chapter directly in your browser — Python's json module is available in every online environment.
- JSON is text-based, language-independent, and the universal format for web APIs and
config files. Python's built-in
jsonmodule handles all JSON operations. - Type mapping: Python
dict→JSON object,list/tuple→array,str→string,int/float→number,True/False→true/false,None→null. json.dumps(obj)encodes Python → JSON string.json.loads(string)decodes JSON string → Python. The "s" = string.json.dump(obj, file)writes to file.json.load(file)reads from file. No "s" = file I/O. Always useencoding="utf-8".- Key formatting options:
indent=2for readable output,sort_keys=Truefor deterministic ordering,ensure_ascii=Falsefor Unicode output,separators=(",", ":")for compact output. - Types not natively serialisable:
datetime,Decimal,set,bytes, custom classes. Handle viadefault=function orcls=JSONEncodersubclass. - Use
parse_float=Decimalinjson.loads()to avoid floating-point precision errors when parsing monetary values. - JSONL (JSON Lines) — one JSON object per line — is the standard for streaming data, logs, and large datasets.
- Handle
json.JSONDecodeErrorfor malformed input; always validate required fields before processing API responses.
Both serialise a Python object to JSON, but differ in destination:
json.dumps(obj)— the "s" stands for string. Returns the JSON as a Python string. Use when you need the JSON in memory (e.g. sending over a network, embedding in code).json.dump(obj, file)— writes directly to an open file object. More memory-efficient for large objects since it streams directly to disk.
The same "s" rule applies to reading: json.loads(string) parses from a string; json.load(file) reads from a file.
The following types raise TypeError with default JSON
serialisation:
datetime/date— convert with.isoformat()Decimal— convert tofloatorstrset— convert tolistbytes— convert with.decode()- Custom class instances — convert to
dictvia.__dict__
Handle them with a default= function or
by subclassing json.JSONEncoder.
import json
data = {"z": 3, "a": 1, "m": [1, 2]}
print(json.dumps(data, indent=2, sort_keys=True))
# {
# "a": 1,
# "m": [1, 2],
# "z": 3
# }
Use ensure_ascii=False as well if your data contains non-ASCII
characters like Unicode, emojis, or Indian script.
JSONL (JSON Lines) is a format where each line of a text file is a separate, valid JSON object. There is no wrapping array — each line is independent.
Used for: streaming data processing (you can process line-by-line without loading the whole file), log files, large datasets, and machine learning training data. It's memory-efficient because you never need to parse the entire file at once.
# data.jsonl — one JSON object per line:
# {"id": 1, "name": "Alice"}
# {"id": 2, "name": "Bob"}
with open("data.jsonl") as f:
for line in f:
rec = json.loads(line) # one at a time
By default, JSON floating-point numbers are decoded as Python float, which uses IEEE 754 double precision. This can introduce tiny
precision errors that are catastrophic for financial or monetary values:
print(json.loads('{"price": 99.99}')["price"])
# 99.99000000000001 ← float precision issue!
from decimal import Decimal
print(json.loads('{"price": 99.99}', parse_float=Decimal)["price"])
# Decimal('99.99') ← exact!
Use parse_float=Decimal whenever you're
parsing monetary amounts or other values where precision is critical.
True become when serialised to
JSON?json.dumps() produces nicely
indented, human-readable output?
Rate Us on Google
Join Our Learning Community
Connect with thousands of learners, get daily tips, ask questions and stay updated with new tutorials.