Different behaviour between pydantic and SQLModel when serializing and deserializing a datetime field with schema_extra

[hapm]

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 SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" 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 SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from datetime import datetime

from pydantic import Field as PdField, BaseModel
from sqlmodel import Field as SmField, SQLModel


def test_sqlmodel_json_serialization_and_deserialization_of_datetime():
    # Create a model class locally to avoid pytest collection issues
    class TestModel(SQLModel):
        timestamp: datetime = SmField(schema_extra={"validation_alias": "test"})
    
    # Create a model instance with a datetime
    original_datetime = datetime(2023, 1, 1, 12, 0, 0)
    model = TestModel(timestamp=original_datetime)
    
    # Serialize to JSON
    json_str = model.model_dump_json()
    
    # Deserialize from JSON
    deserialized_model = TestModel.model_validate_json(json_str)
    
    # Check that the datetime is preserved correctly
    assert isinstance(deserialized_model.timestamp, datetime)
    assert deserialized_model.timestamp == original_datetime


def test_pydantic_json_serialization_and_deserialization_of_datetime():
    # Create a model class locally to avoid pytest collection issues
    class TestModel(BaseModel):
        timestamp: datetime = PdField(strict=True)
    
    # Create a model instance with a datetime
    original_datetime = datetime(2023, 1, 1, 12, 0, 0)
    model = TestModel(timestamp=original_datetime)
    
    # Serialize to JSON
    json_str = model.model_dump_json()
    
    # Deserialize from JSON
    deserialized_model = TestModel.model_validate_json(json_str)
    
    # Check that the datetime is preserved correctly
    assert isinstance(deserialized_model.timestamp, datetime)
    assert deserialized_model.timestamp == original_datetime


def test_sqlmodel_json_serialization_and_deserialization_of_datetime_with_empty_schema_extras():
    # Create a model class locally to avoid pytest collection issues
    class TestModel(SQLModel):
        timestamp: datetime = SmField(schema_extra={})
    
    # Create a model instance with a datetime
    original_datetime = datetime(2023, 1, 1, 12, 0, 0)
    model = TestModel(timestamp=original_datetime)
    
    # Serialize to JSON
    json_str = model.model_dump_json()
    
    # Deserialize from JSON
    deserialized_model = TestModel.model_validate_json(json_str)
    
    # Check that the datetime is preserved correctly
    assert isinstance(deserialized_model.timestamp, datetime)
    assert deserialized_model.timestamp == original_datetime

Description

I create a simple model with a strict datetime field. When I serialize the model to json and deserialize it back I expect SQLModel to behave the same as the BaseModel in pydantic, but the SQLModel test raises an exception:

integration_tests/test_sqlmodel_datetime_bug.py::test_sqlmodel_json_serialization_and_deserialization_of_datetime failed: def test_sqlmodel_json_serialization_and_deserialization_of_datetime():
        # Create a model class locally to avoid pytest collection issues
        class TestModel(SQLModel):
            timestamp: datetime = SmField(schema_extra={"strict": True})
    
        # Create a model instance with a datetime
        original_datetime = datetime(2023, 1, 1, 12, 0, 0)
        model = TestModel(timestamp=original_datetime)
    
        # Serialize to JSON
        json_str = model.model_dump_json()
    
        # Deserialize from JSON
>       deserialized_model = TestModel.model_validate_json(json_str)
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
E       pydantic_core._pydantic_core.ValidationError: 1 validation error for TestModel
E       timestamp
E         Input should be a valid datetime [type=datetime_type, input_value='2023-01-01T12:00:00', input_type=str]
E           For further information visit https://errors.pydantic.dev/2.11/v/datetime_type

integration_tests/test_sqlmodel_datetime_bug.py:20: ValidationError

After trying around some scenarios I found that setting any schema_extra breaks the behavior. An empty or no schema_extra behaves as expected as the last test shows.

Operating System

Linux

Operating System Details

No response

SQLModel Version

0.0.25

Python Version

Python 3.13.7

Additional Context

No response

[malewicz1337]

The issue occurs because when you use schema_extra (or json_schema_extra) in SQLModel's Field, it interferes with Pydantic's datetime serialization mode. By default, Pydantic serializes datetimes as ISO format strings in JSON but can also deserialize them back from strings. However, when schema_extra is present, it appears to trigger stricter validation that doesn't allow string-to-datetime conversion during deserialization.

Solution

Don't use schema_extra={"strict": True} for datetime validation. Instead, use Pydantic's proper validation configuration:

from datetime import datetime
from sqlmodel import Field, SQLModel
from pydantic import field_validator

class TestModel(SQLModel):
    timestamp: datetime = Field()
    
    @field_validator('timestamp', mode='before')
    @classmethod
    def validate_timestamp(cls, v):
        if isinstance(v, str):
            return datetime.fromisoformat(v)
        if isinstance(v, datetime):
            return v
        raise ValueError('timestamp must be a datetime or ISO format string')

Or simply use the field without schema_extra:

class TestModel(SQLModel):
    timestamp: datetime = Field()

Why This Happens

1. Pydantic serializes datetime objects to ISO format strings in JSON
2. On deserialization, Pydantic normally converts these strings back to datetime objects
3. Adding schema_extra (even empty {}) seems to alter the field's validation behavior in SQLModel
4. This prevents the automatic string → datetime conversion, causing the validation error

Recommendation

Avoid using schema_extra for datetime fields in SQLModel unless absolutely necessary. If you need custom validation, use Pydantic's field_validator decorator instead.

[YuriiMotov]

This is only related to schema_extra={"strict": True}.
It has already been reported here: #816

In your first code example you use schema_extra={"validation_alias": "test"} and in this case everything works as expected.
You have

E           pydantic_core._pydantic_core.ValidationError: 1 validation error for TestModel
E           test
E             Field required [type=missing, input_value={'timestamp': datetime.da...time(2023, 1, 1, 12, 0)}, input_type=dict]
E               For further information visit https://errors.pydantic.dev/2.11/v/missing

(missing value for required field test)

That's because you specified validation_alias and now Pydantic expects to find value for timestamp field in the test field of input dict.
But .model_dump() doesn't use validation_alias. So, the output will be {'timestamp': datetime.da...time(2023, 1, 1, 12, 0)} (contains timestamp field, doesn't contain test field) - this works correctly.

I'll close this as a duplicate of #816. Let's track this there