Python json.dumps(): Understanding default=str and ensure_ascii=False

When working with APIs, databases, JSON files, or system integrations, one of the most commonly used functions in Python is json.dumps(). This function converts Python objects into JSON-formatted strings that can be transmitted, stored, or processed by other applications.

A frequently encountered example is:

json.dumps(cdr_json, default=str, ensure_ascii=False)

Although it appears simple, this statement solves two important challenges: serializing objects that are not natively supported by JSON and preserving Unicode characters in a human-readable format.

What Is json.dumps()?

The json.dumps() function is part of Python’s built-in json module and is used to convert Python objects into JSON strings.

Example:

import json

data = {
    "name": "Example",
    "value": 123
}

result = json.dumps(data)
print(result)

Output:

{"name": "Example", "value": 123}

This JSON string can then be sent through an API, stored in a database, or written to a file.

The Problem with Non-Serializable Objects

JSON supports only a limited set of data types:

• String
• Number
• Boolean
• Array
• Object
• Null

Python, however, includes additional types such as:

• datetime
• date
• Decimal
• UUID
• Custom classes

Attempting to serialize these objects directly results in an exception.

Example:

from datetime import datetime
import json

data = {
    "timestamp": datetime.now()
}

json.dumps(data)

Output:

TypeError: Object of type datetime is not JSON serializable

The Purpose of default=str

The default parameter provides a fallback function for objects that the JSON encoder cannot process.

In the example:

json.dumps(data, default=str)

Python automatically executes:

str(object)

for any unsupported type.

Example:

from datetime import datetime
import json

data = {
    "timestamp": datetime.now()
}

result = json.dumps(data, default=str)

Output:

{
  "timestamp": "2026-07-11 09:30:00.123456"
}

This prevents serialization errors and allows the application to continue processing the data.

What Does ensure_ascii=False Do?

By default, the JSON encoder converts non-ASCII Unicode characters into escaped sequences.

Example:

json.dumps({"name": "Ștefan"})

Output:

{"name": "\u0218tefan"}

While technically correct, this format is less readable.

Using:

json.dumps({"name": "Ștefan"}, ensure_ascii=False)

produces:

{"name": "Ștefan"}

The original Unicode characters are preserved.

Benefits of ensure_ascii=False

Improved Readability

JSON output remains easy to read in logs, files, and debugging tools.

Better Internationalization Support

It works seamlessly with languages such as:

• Romanian
• Hebrew
• Arabic
• Chinese
• Japanese
• Korean

Easier Debugging

Developers can inspect the actual text without decoding Unicode escape sequences.

Complete Example

import json
from datetime import datetime
from decimal import Decimal

cdr_json = {
    "customer": "Ștefan Popescu",
    "timestamp": datetime.now(),
    "amount": Decimal("125.50")
}

result = json.dumps(
    cdr_json,
    default=str,
    ensure_ascii=False
)

print(result)

Possible output:

{
  "customer": "Ștefan Popescu",
  "timestamp": "2026-07-11 09:30:00.123456",
  "amount": "125.50"
}

When Should You Use This Approach?

This combination is particularly useful for:

• REST APIs
• Application logging
• JSON exports
• Database integrations
• Billing and invoicing systems
• Monitoring platforms
• IoT applications
• Python microservices

Important Considerations

While default=str is convenient, it converts all unsupported objects into strings.

For example:

Decimal("125.50")

becomes:

"125.50"

instead of:

125.50

In APIs that enforce strict schemas, it may be preferable to implement a custom serializer for specific object types rather than converting everything to strings.

Best Practices

For quick serialization, logging, and debugging:

json.dumps(data, default=str, ensure_ascii=False)

is often sufficient.

For production APIs with strict data contracts, consider:

• Explicit handling of datetime values using ISO 8601 format
• Converting Decimal values to numeric types when appropriate
• Creating a custom JSON encoder for greater control

Example:

json.dumps(
    data,
    default=lambda o: o.isoformat() if isinstance(o, datetime) else str(o),
    ensure_ascii=False
)

Conclusion

The statement:

json.dumps(cdr_json, default=str, ensure_ascii=False)

provides a practical and reliable way to serialize complex Python objects into JSON. The default=str parameter prevents failures caused by unsupported data types, while ensure_ascii=False keeps Unicode characters readable and user-friendly.

For modern applications that handle international data, API integrations, logging, and data exchange, this combination remains one of the most widely used and effective approaches for generating JSON output in Python.

Meta Description:
Learn how Python’s json.dumps() works and understand the purpose of default=str and ensure_ascii=False for serializing complex objects and preserving Unicode characters in JSON output.

Keywords:
python json.dumps, default str python, ensure_ascii false, json serialization python, python json unicode, json encoder python, datetime json serializable, decimal json serialization, python api json response, json dumps example, unicode json output, python backend development, python json tutorial, json encoding python, python programming guide

Suggested SEO Title:
Python json.dumps Explained: Using default=str and ensure_ascii=False for JSON Serialization

Suggested URL Slug:
python-json-dumps-default-str-ensure-ascii-false-explained