Python JSON Dates and Decimals: Serialize Values Deliberately

Published September 5, 2026 · Reviewed by the json2py editorial team

Python can serialize strings, numbers, lists, dictionaries, booleans and None with its standard JSON module. Some useful application values do not have a direct JSON counterpart. Dates, times, decimals, UUIDs and custom classes require an explicit decision about their representation before they cross an API or file boundary.

JSON has a limited type system

JSON has no built-in date, decimal or binary type. A date is commonly represented as a text string, and a monetary amount may be represented as a string or an integer count of minor units. The best choice depends on the receiving system and must be agreed upon by both sides of the interface.

Use a documented date format

An ISO 8601-style string with an explicit time zone is generally easier to compare and exchange than a locale-specific date. Decide whether a value represents a date only, a local time or a precise timestamp. Store enough information to recover the intended meaning; a timestamp without a time-zone convention invites errors.

Do not silently turn Decimal into float

Binary floating-point values can introduce small rounding differences. For money and exact quantities, decide whether JSON will carry a quoted decimal string or an integer such as cents. Convert intentionally and validate the value on the receiving side rather than relying on a generic fallback serializer.

Keep serialization rules centralized

A custom encoder or a small conversion function is preferable to scattered str() calls. Centralization makes the API contract visible and makes it possible to test all special values in one place. It also prevents two endpoints from emitting the same conceptual value in different formats.

Round-trip test important values

Serialize a representative value, read it back and compare the normalized result with what the application expects. For dates this might mean comparing an aware timestamp; for currency it might mean comparing a Decimal reconstructed from the JSON string. Tests should document accepted precision and time-zone behavior.