Skip to content

Parse JSON in Python: Read, Write, and Validate Data

Python's built-in json module handles the common shapes of JSON work: a string in memory, a file on disk, an HTTP response body, or a stream of line-delimited records. The main decision is not which library to install, but which function matches the input you actually have. This guide maps each input to the right call, shows how parsed values behave in Python, and separates decoding failures from application-level data problems.

What JSON becomes in Python

JSON is a text format built from objects, arrays, strings, numbers, booleans, and null. When Python parses it, those constructs become ordinary Python values. A JSON object normally becomes a dict, and a JSON array becomes a list. That means you can use dictionary keys and list iteration after parsing, including for nested structures.

The conversion is mostly predictable, but it is not a one-to-one type system. The JSON-to-Python mapping table below shows the standard correspondences. Keep it nearby when you are checking whether a parsed value will support the operation you plan to run.

Read a JSON string with json.loads()

Use json.loads() when the JSON text is already in a Python string. The function returns the corresponding Python value, so a top-level object becomes a dictionary and a top-level array becomes a list. Nested objects become nested dictionaries, and nested arrays become lists.

A typical workflow is to assign the JSON text to a variable, call json.loads(), then index into the result. If the parsed value is a dictionary, access values by key. If it is a list, iterate over it. The function can also accept supported bytes-like input, which is useful when the JSON arrives as bytes rather than text.

For a worked example, the code module code0004 parses a JSON string and prints a nested street value. The surrounding explanation is simple: the top-level object is a dict, so the address key returns another dict, and the street key returns the string value.

Python example

json_string = """
{
    "name": "John Doe",
    "age": 32,
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA"
    },
    "tags": ["Finance", "Admin"]
}
"""

Read a JSON file with json.load()

Use json.load() when the JSON lives in a file or another file-like object with a read() method. Open the file with an explicit encoding, pass the file object to json.load(), and use the returned Python value. The code module code0006 demonstrates this pattern with a profile.json file and a UTF-8 encoding.

The distinction between json.load() and json.loads() is about input type, not about the resulting data. json.load() reads from a file-like object; json.loads() parses a string or supported bytes-like input. Both return Python values after parsing.

Access nested objects and arrays

After parsing, nested data is just Python data. A dictionary inside a dictionary is reached with successive keys. A list of dictionaries is reached by indexing the list or iterating over it. The code module code0007 shows a team object with a members array; the team value is read by key, and each member's name is read inside a loop.

This is also where type expectations matter. If a field that should be a list is actually a string, iteration may produce characters rather than records. If a nested object is missing, a key lookup will fail. Those are application-level checks, not JSON syntax errors.

Parse a JSON response from an API

When you use the Requests library, response.json() is the direct way to decode a JSON response body. It returns the corresponding Python value. If you already have the raw response text, json.loads(response.text) performs the same decoding step explicitly.

HTTP status and JSON decoding are separate concerns. A request can return a successful HTTP status while the body contains invalid JSON or HTML. An error response such as 400 or 500 can still contain a valid JSON body. Call response.raise_for_status() to check the HTTP status, and handle JSON decoding separately. Inspecting the Content-Type header can help with debugging, but a missing or incorrect content type does not by itself prove that the body cannot be parsed as JSON.

The code module code0008 shows a Requests call followed by raise_for_status() and response.json(). The code module code0009 shows the explicit json.loads(response.text) alternative.

Python example

# Run before proceeding:
# pip install requests
import requests

response = requests.get("https://httpbin.org/json", timeout=30)
response.raise_for_status()

data = response.json()

print(data["slideshow"]["title"])
# Output: Sample Slide Show

Python example

import json

data = json.loads(response.text)

Handle JSON parsing errors without confusing them with HTTP errors

Python's json module raises json.JSONDecodeError when the input cannot be parsed as valid JSON. Common causes include an empty body, truncated text, invalid syntax, or content that is not JSON at all, such as an HTML page. Catch that exception when the input may be unreliable.

With Requests, a decode failure can surface as requests.exceptions.JSONDecodeError. Keep the two failure classes separate in your code: response.raise_for_status() checks the HTTP status, while response.json() attempts to decode the body. A 200 response with an HTML body is a decoding problem, not an HTTP status problem.

For debugging, printing a short prefix of response.text can reveal an empty body, an HTML error page, or unexpected content. Avoid logging complete response bodies indiscriminately in production; they may be large or sensitive. Truncate and sanitize where appropriate. The code modules code0010, code0011, and code0012 show the exception handling and the short-prefix inspection pattern.

Python example

print(response.text[:200])

Write JSON with json.dumps() and json.dump()

Serialization runs in the opposite direction. json.dumps() converts a Python object into a JSON string. json.dump() writes the serialized JSON directly to a file or another writable file-like object. The code modules code0013 and code0015 show both patterns.

The reverse mapping is mostly the mirror of parsing: dictionaries become JSON objects, lists and tuples become arrays, strings remain strings, numbers remain numbers, True and False become true and false, and None becomes null. Some Python types do not have an exact JSON equivalent, so a round trip can change the type. A tuple, for example, becomes a JSON array and parses back as a list. The values are preserved, but the original tuple type is not. The code module code0014 demonstrates that round-trip difference.

Serialize custom Python objects

The json module cannot automatically serialize arbitrary custom objects. Attempting to do so raises a TypeError indicating that the object is not JSON serializable. One fix is to pass a function through the default argument. That function should return a JSON-serializable representation of the object, such as its __dict__, and should raise TypeError for unsupported types. The code modules code0016, code0017, and code0018 show the failure and the default-function solution.

For more reusable or complex serialization logic, subclass json.JSONEncoder and override its default() method. For simple custom types, a default function usually keeps the code shorter.

Choose a parsing approach for scale and line-delimited data

For small strings and files, the standard json module is usually sufficient. Two other patterns matter when the workload changes shape.

orjson is a third-party library designed for fast serialization and deserialization. It can outperform the standard library for some workloads, but the difference depends on the data and how the application uses JSON. One API difference to plan for is that orjson.dumps() returns bytes, while json.dumps() returns a str. If parsing or serialization is a bottleneck, benchmark orjson against the standard library using your own data before switching. The code modules code0019, code0020, and code0021 show installation, parsing, and the return-type difference.

JSON Lines, also called JSONL or newline-delimited JSON, stores one valid JSON value on each line. It is common for large datasets, logs, exports, and data-processing pipelines. Parse each line with json.loads() and process one record at a time. Because each line is parsed separately, the program does not need to load the entire dataset into memory at once. The code modules code0022 and code0023 show a sample .jsonl file and a line-by-line loop.

Command example

pip install orjson

Parsing JSON from a scraping workflow

Web scraping often turns page content into structured data. When a scraping service returns extracted data as JSON, the same Python parsing techniques apply. Selector-based extraction rules and AI-described extraction rules serve different input styles, while a JSON response wrapper serves a different purpose: it packages the response body, headers, and captured XHR requests rather than selecting specific page values.

Once the response is JSON, decode it with response.json() or json.loads(). The exact request construction for a scraping API belongs in the service's own documentation and is not reproduced here; the important Python step is the same decode-and-access pattern used for any other JSON response.

A decision checklist for choosing the right call

Use this checklist before writing the parsing line:

  • If the JSON is already a string, use json.loads().
  • If the JSON is in a file or file-like object, use json.load().
  • If the JSON is a Requests response body, use response.json(); use json.loads(response.text) when you already have the raw text.
  • If the file is JSON Lines, parse each line with json.loads() rather than loading the whole file as one JSON document.
  • If performance is the bottleneck, benchmark orjson against the standard library with your own data before changing libraries.
  • If the input may be empty, truncated, or non-JSON, catch json.JSONDecodeError and inspect a short, sanitized prefix of the source.
  • If the data must match a schema, validate required fields, types, and constraints after parsing; successful decoding alone does not establish application validity.

Validate parsed data separately from parsing

A successful parse means the decoder accepted the input and returned Python values. It does not mean the data matches the structure, types, or constraints your application expects. Required fields may be missing, values may have the wrong type, or a field may be present but empty. Check those conditions with normal Python checks, or use a separate validation step such as JSON Schema or Pydantic for stricter rules.

This distinction is useful when debugging: a JSONDecodeError points to the text itself, while a validation failure points to the shape or content of an otherwise decodable document.

JSON-to-Python type mapping
JSONPython
objectdict
arraylist
stringstr
number (integer)int
number (real)float
trueTrue
falseFalse
nullNone

Standard conversion mapping for Python's json module.

Choosing a JSON parsing approach by input
What you haveRecommended approach
JSON stringjson.loads()
JSON file or file-like objectjson.load()
Requests responseresponse.json()
JSON Lines (.jsonl) fileParse each line with json.loads()
Performance-sensitive workloadBenchmark orjson against the standard-library json module

For most applications, start with the built-in json module; specialized options become useful when the format or performance requirement calls for them.

Frequently asked questions

How do I parse a JSON string in Python?

Pass the JSON text to json.loads(). The result is a normal Python value—often a dictionary or list—that you can index, iterate over, and otherwise manipulate with standard Python syntax.

How do I parse a JSON file in Python?

Open the file and pass the file object to json.load(). Use json.loads() instead when the JSON is already in a string.

How do I parse a JSON response from an API in Python?

With Requests, use response.json() to decode the response body. Call response.raise_for_status() separately to check for HTTP errors. If you already have the raw response text, use json.loads(response.text).

Why does json.loads() raise a JSONDecodeError?

The input could not be parsed as valid JSON. It may be empty, truncated, incorrectly formatted, or contain something else such as HTML. Catch json.JSONDecodeError when parsing potentially unreliable input and inspect the source safely.

What's the difference between json.load() and json.loads()?

json.load() reads JSON from a file or file-like object. json.loads() parses JSON from a string and can also accept supported bytes-like input. Both deserialize JSON into corresponding Python values.

How do I convert JSON to a Python object?

Use json.loads() for JSON text or json.load() for a JSON file. JSON objects become dictionaries, arrays become lists, and scalar values such as strings, numbers, booleans, and null are converted to their corresponding Python types.

Does valid JSON mean the data is valid?

No. A successful parse only confirms that the decoder recognized the input as JSON syntax. Whether the document fits your application is a separate question: required fields, expected types, and value constraints still need checking, either with ordinary Python logic or with a dedicated validator such as JSON Schema or Pydantic.

{
    "name": "John Doe",
    "age": 32,
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA"
    },
    "tags": ["Finance", "Admin"]
}
{
    "name": "John Doe",
    "age": 32,
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA"
    },
    "tags": ["Finance", "Admin"]
}
{"name": "Ana", "role": "developer"}
{"name": "Ben", "role": "designer"}
{"name": "Kai", "role": "writer"}