FastAPI and orjson: Interoperability Boundaries When Overriding json_loads for Concurrent Body Parsing

Integration risks when overriding FastAPI’s json_loads with orjson

FastAPI delegates body parsing to the callable set in FastAPI.json_loads. Replacing it with orjson.loads changes only the input side; Pydantic receives the same Python objects (dict, list, str, int, float, bool, None) that the standard json module would produce.

Confirmed facts

• orjson returns native Python types; it does not produce a custom wrapper that Pydantic would see.
• Pydantic validation runs after parsing, so any validator that inspects the raw Python value works unchanged.
• orjson is faster because it is implemented in Rust and avoids the GIL during parsing.

Likely explanation of interoperability boundaries

The risk surface lies in two places:

1. Request‑side type handling: orjson does not support the default hook that json.loads accepts via a custom JSONEncoder. If your API relies on passing a custom encoder to decode non‑JSON‑native objects (e.g., Decimal encoded as a string), orjson will raise TypeError instead of using the encoder.
2. Response‑side serialization: FastAPI’s default JSONResponse still uses the standard library json.dumps. If you only override json_loads, responses remain unchanged, but many teams also switch to ORJSONResponse for consistency. orjson’s output can differ in formatting (no trailing zeros, different handling of NaN/Infinity, and datetime representation unless you pass specific options).

Steps to verify compatibility

1. Unit‑test the parsing hook: create a test client that sends payloads exercising every custom Pydantic validator (including those that rely on pre=True, always=True, or that inspect raw strings). Assert that validation outcomes match those obtained with the default parser.
2. Property‑based comparison: for a set of random JSON‑serializable payloads, compare json.loads and orjson.loads outputs deep‑equality; flag any differences in type (e.g., int vs float) or value.
3. Response integrity check: if you plan to use ORJSONResponse, render a representative set of Pydantic models (including nested models, datetime fields, UUID, Decimal via custom encoder) and compare the byte‑for‑byte body with that produced by JSONResponse after applying the same orjson options (option=orjson.OPT_NAIVE_UTC|orjson.OPT_OMIT_MICROSECONDS).
4. Load test under concurrency: run a benchmark (e.g., with locust or hey) simulating many concurrent requests with payloads >1 MiB. Measure average latency and 99th‑percentile; ensure the reduction is consistent and does not increase error rates.

Missing diagnostic detail

If your codebase uses a custom JSONEncoder (via default) to encode non‑standard types during response serialization, you must confirm whether you intend to keep the standard JSONResponse or switch to ORJSONResponse. Knowing whether such an encoder is present determines if you need to adapt orjson options or retain the default response class.