How to directly serialize Decimals to JSON numbers? (FHIR spec decimal cmpliance) #14929

nishaalnaseer · 2026-02-15T13:10:11Z

nishaalnaseer
Feb 15, 2026

First Check

I added a very descriptive title here.
I used the GitHub search to find a similar question and didn't find it.
I searched the FastAPI documentation, with the integrated search.
I already searched in Google "How to X in FastAPI" and didn't find any information.
I already read and followed all the tutorial in the docs and didn't find an answer.
I already checked if it is not related to FastAPI but to Pydantic.
I already checked if it is not related to FastAPI but to Swagger UI.
I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

I commit to help with one of those options 👆

Example Code

The decimal primitive in the FHIR spec, a healthcare standard, requires trailing zeroes to be maintained with in JSON when its transmitted over the wire.

The simple JSON library does the serialization and deserialization as needed.

from decimal import Decimal

import simplejson


def main():
    string1 = simplejson.dumps({"value": Decimal("3.500")})
    print(f"string1 {string1}")

    object1 = simplejson.loads(string1, parse_float=Decimal)
    print(f"object1 {object1}")

    string2 = simplejson.dumps({"value": Decimal("9007199254740993.0")})
    print(f"string2 {string2}")

    object2 = simplejson.loads(string2, parse_float=Decimal)
    print(f"object2 {object2}")


if __name__ == '__main__':
    main()

Output:

string1 {"value": 3.500}
object1 {'value': Decimal('3.500')}
string2 {"value": 9007199254740993.0}
object2 {'value': Decimal('9007199254740993.0')}

After reading the webpages #5023 and https://fastapi.tiangolo.com/advanced/custom-response/#custom-response-class I proceeded to configure simplejson into my backend

from decimal import Decimal
from typing import Any, Callable

import simplejson
from fastapi import Response, Request, FastAPI
from fastapi.routing import APIRoute, APIRouter
from pydantic import BaseModel


class FHIRResponse(Response):
    media_type = "application/json"

    def render(self, content: Any) -> bytes:
        """Serialize data into JSON"""
        print(f"response {content}")
        print(f"type in response {type(content["value"])}")
        return simplejson.dumps(content).encode()


class FHIRRequest(Request):
    async def body(self) -> bytes:
        """Deserialize JSON"""
        if not hasattr(self, "_body"):
            body = await super().body()
            body = simplejson.loads(body, parse_float=Decimal)
            self._body = body
        return self._body


class FHIRRoute(APIRoute):
    def get_route_handler(self) -> Callable:
        original_route_handler = super().get_route_handler()

        async def custom_route_handler(request: Request) -> Response:
            request = FHIRRequest(request.scope, request.receive)
            return await original_route_handler(request)

        return custom_route_handler


app = FastAPI()
router = APIRouter(default_response_class=FHIRResponse)
router.route_class = FHIRRoute


class Foo(BaseModel):
    value: Decimal


@router.post("/")
async def foo(bar: Foo) -> Foo:
    print(f"value in function: {bar.value}")
    print(f"value type in function: {type(bar.value)}")
    return bar


app.include_router(router)


if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app)

Curl:

$ curl -X 'POST'   'http://127.0.0.1:8000/'   -d '{
  "value": 3.5000
}'
{"value": "3.5000"}

With console log as

value in function: 3.5000
value type in function: <class 'decimal.Decimal'>
response {'value': '3.5000'}
type in response <class 'str'>

First of all I'd like to say deserialization is not the issue as there within the function the type is being seen as a Decimal.
However when the object is being returned Decimal is being turned into a string somewhere in the middle before simplejson gets to serialize the Decimal.

There is a fix which is to return the JSONResponse directly.

@router.post("/")
async def foo(bar: Foo) -> JSONResponse:
    print(f"value in function: {bar.value}")
    print(f"value type in function: {type(bar.value)}")
    return JSONResponse(content=simplejson.dumps(bar.model_dump()))
$ curl -X 'POST'   'http://127.0.0.1:8000/'   -d '{
  "value": 3.5000
}'
"{\"value\": 3.5000}"

But how do i override the part where fastapi turns Decimal into a string?



### Description

How to directly serialise Decimal to JSON numbers to JSON number. FastAPI seems to serialize Decimals into strings somewhere in the middle and this doesnt help to achieve the desired target.

### Operating System

Windows

### Operating System Details

_No response_

### FastAPI Version

0.128.0

### Pydantic Version

2.12.5

### Python Version

3.14.0

### Additional Context

_No response_

Toygarmetu · 2026-02-21T08:26:57Z

Toygarmetu
Feb 21, 2026

The root issue: FastAPI calls jsonable_encoder on your return value before the response class's render() sees it, and jsonable_encoder converts Decimal → str by default.

Solution: Return a Response object directly to bypass jsonable_encoder

import simplejson
from fastapi import Response

class FHIRResponse(Response):
    media_type = "application/fhir+json"

    def render(self, content) -> bytes:
        return simplejson.dumps(content, use_decimal=True).encode("utf-8")

@app.get("/observation", response_class=FHIRResponse)
async def get_observation():
    data = {"valueDecimal": Decimal("3.5000")}
    return FHIRResponse(content=data)  # Return directly, not just the dict

By returning FHIRResponse(content=data) instead of return data, FastAPI skips jsonable_encoder and your render() method receives the original Decimal objects intact. simplejson with use_decimal=True then serializes them as JSON numbers preserving trailing zeros.

Alternative with orjson:

import orjson

class FHIRResponse(Response):
    def render(self, content) -> bytes:
        return orjson.dumps(content, option=orjson.OPT_PASSTHROUGH_DECIMAL,
                           default=lambda x: float(x) if isinstance(x, Decimal) else x)

The key insight: response_class=FHIRResponse only sets the default for documentation and content-type headers — it does not prevent jsonable_encoder from running. Returning the response object directly does.

0 replies

YuriiMotov · 2026-02-23T21:31:08Z

YuriiMotov
Feb 23, 2026
Collaborator

Since FastAPI 0.130.0, jsonable_encoder is not used if you declare response_model and don't specify response_class for route (see docs).
So, you can now override serialization logic for Decimal this way:

from decimal import Decimal

from fastapi import FastAPI
from fastapi.routing import APIRouter
from pydantic import BaseModel, field_serializer

app = FastAPI()
router = APIRouter()


class Foo(BaseModel):
    value: Decimal

    @field_serializer("value", mode="plain")
    def serialize_value(self, value: Decimal) -> float:
        return float(value)


@router.post("/")
async def foo() -> Foo:
    return Foo(value=Decimal("0.01"))


app.include_router(router)

Or, using custom type with serializer:

from decimal import Decimal
from typing import Annotated, TypeAlias

from fastapi import FastAPI
from fastapi.routing import APIRouter
from pydantic import BaseModel, PlainSerializer

app = FastAPI()
router = APIRouter()


MyDecimal: TypeAlias = Annotated[Decimal, PlainSerializer(lambda v: float(v))]

class Foo(BaseModel):
    value: MyDecimal


@router.post("/")
async def foo() -> Foo:
    return Foo(value=Decimal("0.01"))


app.include_router(router)

BTW, could you please explain why we may need to serialize Decimal as float?

0 replies

christiansousadev · 2026-03-12T14:27:41Z

christiansousadev
Mar 12, 2026

Hi @YuriiMotov and @nishaalnaseer,

To answer the "why": In healthcare standards like FHIR (Fast Healthcare Interoperability Resources), the number of decimal places represents the precision of the measurement.

For example, in a lab result, 3.5 and 3.500 are technically different from a clinical governance perspective. 3.500 implies a higher degree of precision in the equipment used. If we serialize Decimal("3.500") as a float or a standard JSON number, most encoders will truncate it to 3.5, losing the metadata of the measurement's precision.

The Solution for FastAPI 0.130.0+:

The challenge is that standard JSON numbers in many libraries don't support trailing zeros. If the FHIR server requires them, the standard practice is indeed using simplejson or keeping it as a strictly formatted string if the receiver expects a JSON number primitive.

However, if you want to keep the Unit of Work clean while using Pydantic, the best way to handle this without letting jsonable_encoder interfere is using a custom Response class that overrides the default encoder entirely, or using Response directly as mentioned by @Toygarmetu.

If you want to maintain the response_model benefits but ensure the output is compliant, you can use a custom encoder at the app level:

Python
from fastapi.responses import JSONResponse
import simplejson

class HighPrecisionJSONResponse(JSONResponse):
def render(self, content: Any) -> bytes:
# simplejson preserves Decimal precision when dumps is called
return simplejson.dumps(
content,
ignore_nan=True,
use_decimal=True # Critical for FHIR compliance
).encode("utf-8")

@app.get("/observation", response_class=HighPrecisionJSONResponse)
async def get_observation():
# Return the data - HighPrecisionJSONResponse will handle the rest
return {"value": Decimal("3.5000")}

2 replies

YuriiMotov Mar 12, 2026
Collaborator

@christiansousadev, have you checked it before posting?

christiansousadev Mar 12, 2026

@christiansousadevVocê verificou isso antes de postar?

Yes, I tested it locally before posting

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

How to directly serialize Decimals to JSON numbers? (FHIR spec decimal cmpliance) #14929

Uh oh!

{{title}}

Uh oh!

Replies: 3 comments 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

How to directly serialize Decimals to JSON numbers? (FHIR spec decimal cmpliance) #14929

Uh oh!

nishaalnaseer Feb 15, 2026

First Check

Commit to Help

Example Code

Replies: 3 comments · 2 replies

Uh oh!

Toygarmetu Feb 21, 2026

Uh oh!

Uh oh!

YuriiMotov Feb 23, 2026 Collaborator

Uh oh!

christiansousadev Mar 12, 2026

Uh oh!

YuriiMotov Mar 12, 2026 Collaborator

Uh oh!

christiansousadev Mar 12, 2026

nishaalnaseer
Feb 15, 2026

Replies: 3 comments 2 replies

Toygarmetu
Feb 21, 2026

YuriiMotov
Feb 23, 2026
Collaborator

christiansousadev
Mar 12, 2026

YuriiMotov Mar 12, 2026
Collaborator