Python json.JSONEncoder.default() Method

The Python json.JSONEncoder.default() method is a method of the json.JSONEncoder class that can be overridden to customize how non-serializable objects are encoded into JSON.

By default, the default() method raises a TypeError if an object is not serializable. However, we can override this method to define custom serialization logic for unsupported data types.

Syntax

Following is the syntax of the Python json.JSONEncoder.default() method −

json.JSONEncoder().default(obj)

Parameters

This method accepts the Python object as a parameter that needs to be serialized.

Return Value

This method should return a JSON-serializable object. If an object cannot be serialized, a TypeError is raised unless handled in a custom implementation.

Example: Default Behavior of default()

If we try to serialize an unsupported object, Python will raise a TypeError by default −

import json

# Sample class
class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

# Create a Person object
person = Person("Alice", 30)

# Attempt to encode the object
try:
   json_data = json.dumps(person)
except TypeError as e:
   print("Error:", e)

Following is the output obtained −

Error: Object of type 'Person' is not JSON serializable

Example: Custom Serialization Using default()

We can override the default() method to convert an unsupported object into a JSON-compatible format −

import json

# Sample class
class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

# Custom JSON Encoder
class CustomEncoder(json.JSONEncoder):
   def default(self, obj):
      if isinstance(obj, Person):
         return {"name": obj.name, "age": obj.age}  # Convert to dictionary
      return super().default(obj)  # Fallback to default behavior

# Create a Person object
person = Person("Alice", 30)

# Encode the object using the custom encoder
json_data = json.dumps(person, cls=CustomEncoder)

print("Serialized JSON:", json_data)

We get the output as shown below −

Serialized JSON: {"name": "Alice", "age": 30}

Example: Handling Multiple Custom Types

We can modify the default() method to support multiple custom types −

import json
from datetime import datetime

# Sample classes
class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

class Event:
   def __init__(self, event_name, date):
      self.event_name = event_name
      self.date = date  # datetime object

# Custom JSON Encoder
class CustomEncoder(json.JSONEncoder):
   def default(self, obj):
      if isinstance(obj, Person):
         return {"name": obj.name, "age": obj.age}
      elif isinstance(obj, Event):
         return {"event_name": obj.event_name, "date": obj.date.isoformat()}  # Convert datetime to string
      return super().default(obj)

# Create objects
person = Person("Bob", 25)
event = Event("Conference", datetime(2025, 5, 17))

# Encode the objects
json_data = json.dumps({"person": person, "event": event}, cls=CustomEncoder)

print("Serialized JSON:", json_data)

The result produced is as shown below −

Serialized JSON: {"person": {"name": "Bob", "age": 25}, "event": {"event_name": "Conference", "date": "2025-05-17T00:00:00"}}

Example: Using default() with JSONEncoder Subclass

Instead of creating a custom encoder class, we can pass a function to the default() method directly using the default parameter in json.dumps() function −

import json

# Sample class
class Product:
   def __init__(self, name, price):
      self.name = name
      self.price = price

# Custom serialization function
def custom_serializer(obj):
   if isinstance(obj, Product):
      return {"product_name": obj.name, "product_price": obj.price}
   raise TypeError(f"Object of type {obj.__class__.__name__} is not JSON serializable")

# Create a Product object
product = Product("Laptop", 1200.50)

# Encode the object with custom serialization function
json_data = json.dumps(product, default=custom_serializer)

print("Serialized JSON:", json_data)

After executing the above code, we get the following output −

Serialized JSON: {"product_name": "Laptop", "product_price": 1200.5}

Example: Handling Nested Objects

We can also handle nested objects inside dictionaries or lists using the default() method −

import json

# Sample class
class Address:
   def __init__(self, street, city):
      self.street = street
      self.city = city

class Person:
   def __init__(self, name, age, address):
      self.name = name
      self.age = age
      self.address = address  # Nested object

# Custom JSON Encoder
class CustomEncoder(json.JSONEncoder):
   def default(self, obj):
      if isinstance(obj, Address):
         return {"street": obj.street, "city": obj.city}
      elif isinstance(obj, Person):
         return {"name": obj.name, "age": obj.age, "address": self.default(obj.address)}
      return super().default(obj)

# Create objects
address = Address("123 Main St", "New York")
person = Person("Alice", 30, address)

# Encode the object
json_data = json.dumps(person, cls=CustomEncoder)

print("Serialized JSON:", json_data)

Following is the output of the above code −

Serialized JSON: {"name": "Alice", "age": 30, "address": {"street": "123 Main St", "city": "New York"}}