Python JSON Handling

JSON has six kinds of value, and each maps to a Python type:

import json
checklist = json.loads('{"camp": "Pine Bay", "nights": 2, "booked": true, "items": ["lamp"]}')
print(type(checklist), checklist["booked"], type(checklist["nights"]))
# <class 'dict'> True <class 'int'>

Going the other way, tuples are written as arrays, so they come back as lists. JSON object keys are always strings, so a dictionary with integer keys returns with string keys: {1: "a"} becomes {"1": "a"}. Sets, dates, Decimal values and your own class instances aren't supported by default, and dumps raises TypeError: Object of type set is not JSON serializable.

Use the s functions when the JSON is already in a string, for example an API response body, and the file functions when reading or writing a file:

import json

checklist = {"camp": "Pine Bay", "items": ["lamp", "rope"]}

with open("checklist.json", "w", encoding="utf-8") as file:
    json.dump(checklist, file, indent=2)

with open("checklist.json", encoding="utf-8") as file:
    loaded = json.load(file)

print(loaded == checklist)   # True

A file must be opened in text mode with an encoding for these functions. Passing a file object to loads, or a string to load, is a common mix-up that fails with TypeError or AttributeError.

Invalid JSON raises json.JSONDecodeError, which includes the line and column of the problem. Typical causes are single quotes (JSON requires double quotes), trailing commas, comments, and Python's True/None spellings instead of true/null.

By default, dumps produces compact, single-line text. Options make it easier to read or compare:

data = {"camp": "Café du Lac", "items": ["lamp", "rope"], "nights": 2}
print(json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False))

{
  "camp": "Café du Lac",
  "items": [
    "lamp",
    "rope"
  ],
  "nights": 2
}

• indent=2 adds line breaks and indentation, ideal for files people will read and diffs in version control.
• sort_keys=True writes keys alphabetically, so the same data always produces the same text.
• ensure_ascii=False keeps characters like é readable. The default True writes them as escapes such as é, which are equally valid but harder to read. When using it with files, open them with encoding="utf-8".
• separators=(",", ":") removes spaces for the smallest possible output.

These options change only the text. Loading any of these variants gives back the same Python data.

json.loads checks that text is syntactically valid JSON. It doesn't check that the data has the shape your program expects:

import json

def load_checklist(text):
    data = json.loads(text)
    if not isinstance(data, dict):
        raise ValueError("checklist must be a JSON object")
    items = data.get("items")
    if not isinstance(items, list) or not all(isinstance(i, str) for i in items):
        raise ValueError("items must be a list of strings")
    return data

'"rope"', '[1, 2]' and '{"items": 5}' are all valid JSON, but none is a valid checklist. Data from users, files or other services should be checked before use, especially before it reaches a database or decides an action. For larger schemas, libraries such as jsonschema or Pydantic describe the expected shape declaratively.

The json module never executes code, so parsing untrusted JSON is safe in that sense. Never use eval() to parse JSON-like text.

Task: validate a campsite checklist and write readable UTF-8 JSON without serialising unsupported objects.

import json
from pathlib import Path

raw = '{"camp": "Lac d’Annecy", "items": ["tent", "stove"], "tags": ["lake"]}'
data = json.loads(raw)

if not isinstance(data.get("items"), list):
    raise ValueError("items must be a list")
data["items"].append("torch")

path = Path("camp.json")
path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
print(json.loads(path.read_text(encoding="utf-8"))["items"])   # ['tent', 'stove', 'torch']
path.unlink()

Tags were stored as a list, not a set, so dumps needs no default function. For the worked check, the function that decodes JSON from a string is json.loads.

The json module documentation covers every option, and json.org defines the format. Continue with CSV handling and web APIs. Practise with the Python exercises and Python quiz.