aws / aws/aws-pdk

[BUG] (type-safe-api) JSON Date serialization fails for Python handlers

Open
#930 2 comments 0 reactions 0 assignees View on GitHub
backlog bug needs-triage
Dominant language
TypeScript
Stars
451
Forks
84
Avg merge
20h 3m
Merged PRs (30d)
1

Description

### Describe the bug

Returning date fields (e.g. with `format: date` in OpenAPI spec) generates Python runtime code which throws errors because date/datetime objects are not serializable via standard Pydantic `model_dump()` + `json.dumps()`.

There seems to be [a TODO](https://github.com/aws/aws-pdk/blob/39b1465b2f98a315afe177b2a89cedb84b75b5f9/packages/type-safe-api/scripts/type-safe-api/generators/python/templates/client/models/models.ejs#L392) to switch to Pydantic [model_dump_json()](https://docs.pydantic.dev/latest/concepts/serialization/#modelmodel_dump_json) - which might fix the issue, but I'm not sure if it'd require solving other problems?

### Expected Behavior

Given an API which returns a date field in a JSON schema, e.g:

```yaml
/my-cool-api:
get:
operationId: myCoolApi
description: Do cool stuff
responses:
200:
description: Results
content:
'application/json':
schema:
$ref: '#/components/schemas/MyCoolContent'
components:
schemas:
MyCoolContent:
type: object
properties:
results:
type: array
items:
type: object
properties:
dt:
type: string
format: date
required:
- dt
package:
type: string
required:
- results
```

...the generated Python runtime includes a `MyCoolContentInner` model whose `dt` field is of type `date`. As I understand, the user's handler function implementation could return for example:

```python
def do_the_thing(input: MyCoolApiRequest, **kwargs) -> MyCoolApiOperationResponses:
return Response.success(
body=MyCoolContent(
results=[
MyCoolContentInner(dt=date(2025, 6, 6))
],
),
)

handler = my_cool_api_handler(interceptors=INTERCEPTORS)(do_the_thing)
```

...which would satisfy the generated typing of `MyCoolApiOperationResponses`.

### Current Behavior

Reading in date parameters is fine, but if a handler's `Response` body uses a model containing a `date` field then PDK's [generated MyCoolContentInner.to_json implementation](https://github.com/aws/aws-pdk/blob/39b1465b2f98a315afe177b2a89cedb84b75b5f9/packages/type-safe-api/scripts/type-safe-api/generators/python/templates/client/models/models.ejs#L392) will call [Pydantic model_dump](https://docs.pydantic.dev/latest/concepts/serialization/#modelmodel_dump) (which preserves the `date` object in the output), followed by built-in `json.dumps()` - which fails to stringify dates and throws an error like:

```
[ERROR] TypeError: Object of type date is not JSON serializable
```

### Reproduction Steps

I don't have a full shareable code example, but creating and deploying any TypeSafeApi that returns a field of OpenAPI `type: string, format: date` (spec similar to the above) should demonstrate it?

I think creating the handler directly in the API project (e.g. with `x-handler: language: python`) should be simplest and will still illustrate the problem.

### Possible Solution

Switching to Pydantic's `model_dump_json()` seems to resolve this as they [document](https://docs.pydantic.dev/latest/concepts/serialization/#modelmodel_dump_json) an explicit example of datetime handling.

### Additional Information/Context

_No response_

### PDK version used

0.23.45 (but as discussed, the code seems same in current mainline)

### What languages are you seeing this issue on?

Python

### Environment details (OS name and version, etc.)

macOS 15.5

Contributor guide

Open the contributing guide

Research direction

Start in packages/type-safe-api/scripts/type-safe-api/generators/python/templates/client/models/models.ejs at the TODO and generated to_json implementation. Reproduce the issue with the OpenAPI date field example and verify that a handler returning a model containing date values serializes successfully without the TypeError.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.