Python JSON Decode: json.loads(), json.load(), and Type-Safe Parsing

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

Python's built-in json module covers the vast majority of JSON decoding needs: parsing API responses, reading config files, and processing data pipelines. For advanced use cases — custom types, date parsing, high throughput, or type validation — Python's ecosystem provides object_hook, Pydantic, orjson, and ijson. This guide covers all of them with working code examples.

json.loads() — Decode a JSON String

json.loads() is the primary function for decoding JSON. It accepts a str, bytes, or bytearray and returns the corresponding Python object. Since Python 3.6, bytes input is handled natively with automatic encoding detection.

import json

# Basic decode
data = json.loads('{"name": "Alice", "age": 30}')
print(data['name'])   # Alice
print(type(data))     # <class 'dict'>

# Decode arrays
items = json.loads('[1, 2, 3]')   # → [1, 2, 3]
flag = json.loads('true')          # → True
nothing = json.loads('null')       # → None

# Error handling
try:
    data = json.loads('{"bad": ,}')   # trailing comma
except json.JSONDecodeError as e:
    print(f"Line {e.lineno}, col {e.colno}: {e.msg}")

json.load() — Decode from a File

json.load() reads a file-like object and decodes its contents. It is equivalent to calling json.loads(fp.read()). Always open files in text mode with an explicit encoding to avoid platform-specific surprises.

import json
from pathlib import Path

# Read JSON file
with open('config.json', 'r', encoding='utf-8') as f:
    config = json.load(f)

# Using pathlib (Python 3.6+)
config = json.loads(Path('config.json').read_text(encoding='utf-8'))

# Decode from HTTP response (requests library)
import requests
response = requests.get('https://api.example.com/data')
response.raise_for_status()
data = response.json()   # calls json.loads(response.text) internally

Type Mapping Reference

The JSON specification defines six value types. Python's json module maps them as follows. Note that JSON integers that fit in Python's arbitrary-precision int are decoded as int; large JSON floats lose precision since Python float is IEEE 754 64-bit.

Custom Object Decoding with object_hook

The object_hook parameter accepts a callable that is invoked for every decoded JSON object (dict). Return a custom Python type from the hook to bypass the default dict result. The parse_float and parse_int parameters similarly intercept number decoding.

import json
from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int

def user_decoder(d: dict) -> User:
    if 'name' in d and 'age' in d:
        return User(name=d['name'], age=d['age'])
    return d

# Decode directly into User objects
users = json.loads('[{"name":"Alice","age":30},{"name":"Bob","age":25}]',
                   object_hook=user_decoder)
# → [User(name='Alice', age=30), User(name='Bob', age=25)]

# parse_float and parse_int for precision control
import decimal
data = json.loads('{"price": 9.99}',
                  parse_float=decimal.Decimal)
# → {'price': Decimal('9.99')} — exact decimal, not IEEE 754 float

Date/DateTime Decoding

JSON has no native date type — dates are always strings. The decoder returns them as plain str values. Use an object_hook or post-process the decoded dict to convert date strings into datetime objects.

import json
from datetime import datetime, timezone

# JSON has no native date type — dates are strings
raw = '{"created": "2026-01-15T10:30:00Z"}'
data = json.loads(raw)
# data['created'] is still a string — must parse manually

# Parse dates with a custom decoder
def decode_dates(d: dict) -> dict:
    for key, value in d.items():
        if isinstance(value, str):
            try:
                d[key] = datetime.fromisoformat(value.replace('Z', '+00:00'))
            except ValueError:
                pass
    return d

data = json.loads(raw, object_hook=decode_dates)
# data['created'] → datetime(2026, 1, 15, 10, 30, tzinfo=timezone.utc)

Type-Safe Decoding with Pydantic

Pydantic v2's model_validate_json() parses JSON and validates types in a single step using a Rust-based core. It is faster than json.loads() + manual validation, provides detailed error messages, and handles nested models, optional fields, and type coercion automatically.

from pydantic import BaseModel, ValidationError
from typing import Optional
import json

class User(BaseModel):
    name: str
    age: int
    email: Optional[str] = None

# Direct JSON string decode (fastest — avoids intermediate dict)
user = User.model_validate_json('{"name":"Alice","age":30}')
print(user.name)   # Alice
print(user.age)    # 30 (int, not str)

# From dict (already parsed)
user = User.model_validate({"name": "Alice", "age": 30})

# With validation errors
try:
    user = User.model_validate_json('{"name": "Alice", "age": "not-a-number"}')
except ValidationError as e:
    print(e.errors())  # [{'type': 'int_parsing', 'loc': ('age',), ...}]

Performance & Large File Handling

For most workloads the stdlib json module is sufficient. When throughput or memory becomes a constraint, the following alternatives provide targeted improvements.

# orjson — 4× faster than stdlib json
import orjson
data = orjson.loads(b'{"name": "Alice"}')  # bytes input

# ijson — streaming for huge files
import ijson
with open('large.json', 'rb') as f:
    for obj in ijson.items(f, 'item'):   # parse array items one by one
        process(obj)

FAQ

Definitions

json.loads(s)

Decodes a JSON string (str, bytes, or bytearray) and returns a Python object. The s stands for "string". It is the standard entry point for decoding JSON received from network requests or already loaded into memory.

json.load(fp)

Decodes JSON from a file-like object opened in text mode. Equivalent to json.loads(fp.read()). The file must be opened with a compatible encoding — UTF-8 is the standard for JSON files.

object_hook

A callable passed to json.loads() or json.load() that is called with every decoded JSON object (dict). Used to transform dicts into custom Python types such as dataclasses, NamedTuples, or domain objects. Called bottom-up for nested structures.

JSONDecodeError

Raised by json.loads() when the input is not valid JSON. It subclasses ValueError, so existing except ValueError clauses catch it automatically. Provides lineno, colno, and msg attributes for precise error location.

parse_float

A callable passed to json.loads() that receives each JSON floating-point number as a raw string before conversion. Use decimal.Decimal to preserve exact decimal precision instead of converting to IEEE 754 64-bit float, which can introduce rounding errors for financial values.