Form with optional Email fails, what is the best practise here?

[krono]

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

import sys, pytest
from pydantic import BaseModel, EmailStr
from fastapi import FastAPI, Form
from fastapi.testclient import TestClient

class Ce(BaseModel): 
  x: EmailStr | None = Field(None, min_length=6)

app = FastAPI()

@app.post('/post')
async def post(ce: Ce = Form()):
  return ce

client = TestClient(app)

def test_write_noneok():
    response = client.post("/post", data={})
    assert response.status_code == 200
    assert response.json()  == {'x':None}

def test_write_emptyok():
    response = client.post("/post", data={'x':''})
    assert response.status_code == 200
    assert response.json()  == {'x': None}

if __name__ == "__main__":
    sys.exit(pytest.main())

Description

I try to model a Html Form that has an optional email field.

The intention is to have it either be absent or validate with the properties set.

The pydantic model

class Ce(BaseModel): 
  x: EmailStr | None = Field(None, min_length=6)

works for manually instantiating a model, but fails when done via a HTML Form Post where the form has the email input not filled out.

It seems in this case, broswers send this datum as emty-string, such that not providing an email tries to instantiate the model as if it would be Ce(x="").

Can I remedy that besides making "" the default for the EmailStr field?
I wanto model an optional email address.

(Expanded version of code here)

Operating System

Linux, macOS

Operating System Details

No response

FastAPI Version

0.136.3

Pydantic Version

2.13.4

Python Version

Python 3.14.5

Additional Context

No response

[strangeleo02]

Because HTML browsers submit empty form inputs as an empty string ("") rather than omitting them or sending null, Pydantic attempts to validate "" against your EmailStr and min_length constraints, resulting in a validation error.

The best solution is to use Pydantic's BeforeValidator to intercept the data before standard validation runs, converting any empty string into None.

If you apply constraints like min_length at the top level of the Annotated type (e.g. Field(min_length=6)), Pydantic will attempt to apply the constraint to None values as well. This leads to a TypeError (e.g., object of type 'NoneType' has no len()).

To prevent this, the constraint should be nested inside the EmailStr member of the Union type. This ensures that the length constraint is only evaluated when the value is a string.

Solution using a nested reusable Annotated type

You can create a reusable pre-validator function and combine it with Annotated to define a custom type. This keeps your models clean and allows you to reuse the logic across multiple optional form fields.

import sys
from typing import Annotated
import pytest
from fastapi import FastAPI, Form
from fastapi.testclient import TestClient
from pydantic import BaseModel, BeforeValidator, EmailStr, Field


# 1. Create a reusable function to transform empty strings to None
def empty_to_none(v: any) -> any:
    return None if v == "" else v


# 2. Define a reusable Annotated type
# The min_length constraint is nested specifically inside the EmailStr type definition
OptionalEmail = Annotated[
    Annotated[EmailStr, Field(min_length=6)] | None, BeforeValidator(empty_to_none)
]


class Ce(BaseModel):
    # Use your clean, reusable type here
    x: OptionalEmail = None


app = FastAPI()


# FastAPI automatically parses incoming form fields into the Pydantic model
@app.post("/post")
async def post(ce: Ce = Form()):
    return ce


# --- Test Suite ---

client = TestClient(app)


def test_write_noneok():
    # Case 1: Field is entirely absent from the form submission
    response = client.post("/post", data={})
    assert response.status_code == 200
    assert response.json() == {"x": None}


def test_write_emptyok():
    # Case 2: Field is present but empty (browser default behavior)
    response = client.post("/post", data={"x": ""})
    assert response.status_code == 200
    assert response.json() == {"x": None}


def test_write_valid_email():
    # Case 3: Field has valid data
    response = client.post("/post", data={"x": "user@example.com"})
    assert response.status_code == 200
    assert response.json() == {"x": "user@example.com"}


def test_write_invalid_email():
    # Case 4: Field has invalid data (fails min_length or EmailStr)
    response = client.post("/post", data={"x": "a@b"})
    assert response.status_code == 422  # Validation Error


if __name__ == "__main__":
    sys.exit(pytest.main([__file__]))

[krono]

excellen. Thank you.