PEP 837 – Extensible JSON serialization | peps.python.org
PEP 837 – Extensible JSON serialization PEP 837 – Extensible JSON serialization Author : Serhiy Storchaka <storchaka at gmail.com> Discussions-To : Discourse thread Status : Draft Type : Standards Track Created : 12-Jul-2026 Python-Version : 3.16 Post-History : 12-Jul-2026 Table of Contents Abstract Motivation Rationale One system covering all of the collected needs Three levels of customization Why the registry lives in copyreg The raw-output mechanism Performance: the encoding pipeline as an invariant Which stdlib types get a default __json__ Specification The __json__ protocol The __raw_json__ protocol The registry The encoder Standard library __json__ methods Backwards Compatibility Security Implications How to Teach This Reference Implementation Rejected Ideas Open Issues Appendix: Related issues Copyright Abstract This PEP adds an extension mechanism to the json encoder consisting of three complementary parts, one per level of customization: library level : a serialization protocol — the special methods __json__() and __raw_json__() ; application level : a global registry — copyreg.json(cls, function) filling copyreg.json_dispatch_table , following the precedent of copyreg.pickle() ; call level : a per-encoder dispatch table — a dispatch_table attribute on a json.JSONEncoder , mirroring pickle.Pickler.dispatch_table .
The more specific level takes precedence. A helper class copyreg.RawJSON wraps an already-encoded JSON string so that it is emitted verbatim, enabling representations that are not otherwise expressible (such as serializing decimal.Decimal as a JSON number with full precision). Several standard library container types whose JSON form is unambiguous — collections.deque , types.MappingProxyType , collections.ChainMap , collections.UserDict , collections.UserList and collections.UserString — gain a __json__ method and therefore serialize out of the box.
The json module itself gains no new public names. Motivation Serializing anything beyond the basic types ( dict , frozendict , list , tuple , str , int , float , bool , None ) with json.dumps() today requires either passing a default= function to every call, or subclassing json.JSONEncoder and threading the subclass through every call site. Both mechanisms attach the knowledge to the call rather than to the type : They do not compose.
Two libraries that each need a custom default= cannot both have it applied to one document without the application writing a merging wrapper by hand. A library that serializes internally (for logging, caching, IPC) cannot see the application’s default= at all. Third-party types cannot opt in. A library defining a new type has no way to make it JSON-serializable for its users; every user must learn and repeat the incantation.
Requests to fix this for NumPy scalars and arrays ( python/cpython#68501 , python/cpython#62503 ) and for D-Bus integer types ( python/cpython#77978 ) were closed as out of scope for the standard library — correctly, but leaving the underlying need unmet. Some representations are impossible. default= must return one of the basic types, so there is no way to emit a non-integer JSON number that float cannot represent exactly. json.loads() can read decimal numbers losslessly via parse_float=decimal.Decimal , but the result cannot be written back ( python/cpython#67312 ).
The same limitation blocks control over float formatting ( python/cpython#81022 ) and non-finite float representation ( python/cpython#98306 , python/cpython#134717 ), and the general request for emitting pre-encoded JSON ( python/cpython#86957 ). The demand is long-standing and broad. Beyond the general proposals for a serialization hook checked before raising TypeError ( python/cpython#71549 — open since 2016, python/cpython#79292 , python/cpython#114285 , python/cpython#86931 ), the tracker accumulated requests for out-of-the-box support of concrete standard library types: decimal.Decimal ( python/cpython#67312 , python/cpython#118810 , python/cpython#145115 ), array.array ( python/cpython#70451 ), collections.deque ( python/cpython#64973 , python/cpython#73849 ), types.MappingProxyType ( python/cpython#79039 ), collections.namedtuple() as an object ( python/cpython#67661 ), and datetime.datetime ( python/cpython#65742 ); and for whole categories: sets, frozensets, bytearrays and iterators ( python/cpython#75338 ), generators ( python/cpython#78031 ), and dictionary views ( python/cpython#83377 ).
The idea has also been proposed independently for sixteen years, each time reinventing part of this design: a __json__() method on python-ideas in July 2010 and April 2020 and on discuss.python.org in 2022–2024 ; raw output and a standardized encoder protocol on python-ideas in 2019 ; a registration function on discuss.python.org in 2022 . Meanwhile the ecosystem adopted the convention piecemeal. TurboGears serializes objects via a no-argument __json__() — and its custom_encoders configuration takes precedence over it, the same ordering as this PEP.
Pyramid’s JSON renderer calls __json__(request) . Applications and libraries such as conda, Checkmk and TatSu define __json__ today. simplejson added an opt-in for_json() method instead — choosing that name precisely because dunder names are reserved for the language ( simplejson issue #52 ). In that issue’s discussion, a GitHub code search already found more __json__ definitions in the wild than for_json ones by 2016, and formalizing the protocol in a PEP was requested so that third-party libraries can rely on the same signature.
Only the standard library can define __json__ ; this PEP does, ending the fragmentation. The type-support requests could not simply be granted one by one. For most of the requested types the JSON representation is ambiguous : Decimal — a JSON number ( 1234567890.0987654321 ) or a JSON string ( "1234567890.0987654321" )? Both are common; each is wrong for some consumers. namedtuple — a JSON Array (it is a tuple) or a JSON Object (it has named fields)? array.array — a JSON Array of numbers, or a compact encoded string?
The sensible answer even depends on its type code. datetime — which of the many string representations (ISO 8601 variants, epoch seconds, RFC formats)? No standard library default can be correct, so the standard library should provide the mechanism by which each application declares its policy . That mechanism is this PEP. Rationale One system covering all of the collected needs The feature is deliberately a small system rather than a single hook: each part answers a different cluster of the requests above, and no part alone covers them all.
The __json__ protocol answers the general extension proposals and the third-party-type reports: the type’s author makes it serializable once, with no imports, inherited by subclasses. The registry answers the requests for types the requester does not control or whose representation is a policy choice ( Decimal , namedtuple , array.array , datetime ): the application declares its policy in one line. Raw output ( __raw_json__ / RawJSON ) answers the requests for representations that no basic-type conversion can express: pre-encoded fragments, full-precision numbers, float formatting, non-finite floats.
Duck typing of hook results answers the category requests (iterables, sets, generators, dictionary views, mappings): copyreg.json(set, sorted) is a complete solution for sets, and a hook may return any iterable or mapping-like object rather than materializing a list or dict. Standard library __json__ methods answer the requests for unambiguous containers ( deque , mappingproxy ) directly. The per-encoder dispatch_table scopes any of the above to one encoder when a process needs different policies for different outputs.
Three levels of customization The three parts correspond to the three levels at which serialization is decided, and deliberately have different shapes: Library level — __json__() is for the author o
The rest of this page is on the live site.