Hi @sneakers-the-rat, thanks for the PR first of all.

About your proposal: while on one side this could offer the tools to handle what you asking at #13380, on the other side it will not address the more general issue #13399.

As i said on the issue discussion, a good and more robusts solution could be harder and require more work than you think.
Since the changes are on a critical function that is used by half of the possibile inputs ( Headers, Path, Query, etc) first i would write a lot more tests to be sure that the actual behaviour will be preserved.

Technical Comments:
I haven't take a look in depth, so there could be more but with your proposal there will be for sure a breaking change on

I attach a small simple test that should pass but it will not.
In that specific case you will have a different behaviour between alias and the original field name.

class SimpleForm(BaseModel):
    foo: Annotated[str, Field(default="bar")]
    alias_with: Annotated[str, Field(alias="with", default="nothing")]


@app.post("/simple-form")
def form_endpoint(model: Annotated[SimpleForm, Form()]) -> dict:
    return model.model_dump()


def test_casted_empty_defaults(fastapi_client: TestClient):
    form_content = {
        "foo": "",
        "alias_with": ""
    }
    response = fastapi_client.post("/simple-form", data=form_content)
    response_content = response.json()
    assert response_content["foo"] == "bar"  # Expected :'bar' -> Actual   :''
    assert response_content["alias_with"] == "nothing"  # ok

Thanks for your contribution.

As i said on the issue discussion, a good and more robusts solution could be harder and require more work than you think.

Great, yeah i was relying on the tests to be protective of any behavior that needs to be preserved, so if there are things that would break that aren't tested then of course list them and we can add tests.

on the other side it will not address the more general issue #13399.

I am not sure how what you described there is more general than what i intitially proposed or have PR'd here, but ofc please let me know what needs to be fixed. This PR passes all the tests in #13399 except for test_submit_form_with_no_values, which emits an warning because the pydantic model is invalid. Specifically, it's a serialization warning, where a model that is correctly constructed with the defaults can't be serialized - it being a warning, the correct value would be returned from the client anyway, the tests just treat warnings as failures.

The two points raised in that discussion were:

This leads to a loss of information regarding which fields have been explicitly set, since default values are now considered as having been provided.

This is what the PR fixes - it is now possible to detect which fields have been explicitly set vs which are defaults.

Consequently, validation is enforced on default values, which might not be the intended behavior and anyway different from the one from json body.

the current code forces validation. the code in this PR fixes this as well, since the warning is a serialization, not a validation warning - again since the model is misspecified.

The current code before this PR also fails this test. So if we want to make fixing that an additional bug we handle in this PR, i can do that, but in my opinion this is actually correct behavior for a misspecified model.

Since the changes are on a critical function that is used by half of the possibile inputs ( Headers, Path, Query, etc) first i would write a lot more tests to be sure that the actual behaviour will be preserved.

The change i have made only affects the Form input and is equivalent to the current behavior for the other types.

The old code was

if field.required:
    return
else:
    return deepcopy(field.default)

The new code is

if return_default and not field.required:
    return deepcopy(field.default)
else:
    return None

Notice how when return_default == True the behavior is identical, the ordering has just been reverse to group the "deepcopy the default" behavior in the same block as evaluating "return_default".

the default value of return_default is True, and it is only explicitly made false inside of _extract_form_body, which I hope is only called for Form data input.

I haven't take a look in depth, so there could be more but with your proposal there will be for sure a breaking change on

This is not a breaking change, as this also fails in the current code, but again i can fix the handling of aliases as an additional bug if we want to attach it to this PR as well.

Hello @sneakers-the-rat , i-m sorry, i have mixed tests, the following one is the right one for your case.

app = FastAPI()


@pytest.fixture(scope="module")
def fastapi_client():
    with TestClient(app) as test_client:
        yield test_client


class SimpleForm(BaseModel):
    foo: Annotated[str, Form(default="bar")]
    alias_with: Annotated[str, Form(alias="with", default="nothing")]


@app.post("/simple-form")
def form_endpoint(model:Annotated[SimpleForm, Form()]) -> dict:
    return model.model_dump()


def test_casted_empty_defaults(fastapi_client: TestClient):
    form_content = {
        "foo": "",
        "with": ""
    }
    response = fastapi_client.post("/simple-form", data=form_content)
    response_content = response.json()
    assert response_content["foo"] == "bar"  # Expected :'bar' -> Actual   :''
    assert response_content["alias_with"] == "nothing"  # ok

Right now is possible to use the given format and in some way, this is the one used for File and UploadFile.
Technically your changes will be reflected on the body params extraction phase on inputs that comes from:

• 'multipart/form-data'
• 'application/x-www-form-urlencoded'

With your implementation you are disabling any possible handling of

And this will allow original values to come back in

This is exactly what i reported in last test.

Ah i see.

These lines:

seem incorrect: the purpose they seem to serve is to get any additional fields that are passed in the form body, but are not included in the form model. currently they are too general - the test is "if key not in values", which would make sense in the old behavior where defaults would be auto-filled (and explains a bit why they were).

It should actually be if key not in body_fields (but since body_fields can't do in checks like that, the aliases have to be extracted out).

I added your test and now it passes.

The core of the problem appears to be regarding empty string input, so i added an additional test that tests empty string input against all the possible ways of specifying a form. The docs show the ability to specify form data in two ways:

1. as parameters in the endpoint signature:

@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
    return {"username": username}

1. as pydantic models:

class FormData(BaseModel):
    username: str
    password: str

@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

(I actually can't find the example case you're using of specifying Annotated[type, Form()] within a pydantic model in the docs. That seems like it should be technically possible, but from a data modeling POV would be a violation of separation of concerns - the model shouldn't care about the encoding of its inputs, that's something that should be handled outside the model, in the framework. regardless, the current version in the PR supports it.)

So when extracting the data, the current check of whether the field is a Form() type is inadequate:

We also care about whether the containing field is a Form() (i.e., in the (2) case of specifying form input with a model where the model fields are not themselves Form()s)

So see the test run for 7fade13:
https://github.com/fastapi/fastapi/actions/runs/13743551022/job/38435686000 - the test above passes with the Form() field annotations, but fails for the rest of the methods of specifying a form.

So I revised the prior impl semantics of return_default to instead explicitly specify whether we are in the context of extracting form data. This, again, only applies to form input and does not affect other input types.

To be clear, again - this is a bug in the current implementation, not introduced by this PR. The tests in test_empty_string_inputs fail in the current implementation.

The correct solution would probably be to remove all handling of special form cases from _get_multidict_value and move them all into _extract_form_body, but i didn't want to change the code too much since this is my first contrib.

I would also like to add this to the form data docs since it is a basic part of handling form data with fastapi - how to handle missing values, checkboxes, etc. but i wanted to wait until we had general approval on this approach. lmk when we get there and i'll add docs

will add docs tomorrow, i had already written a short example in the discussion, so i can improve that and include it in docs.

Happy to change any names, and also I will spend a bit of time this afternoon describing this behavior in the docs :)

📝 Docs preview for commit cad08bb at: https://64e076c0.fastapitiangolo.pages.dev

Modified Pages

• https://64e076c0.fastapitiangolo.pages.dev/tutorial/request-form-models/ - (before)

📝 Docs preview for commit fec0a06 at: https://5ac52580.fastapitiangolo.pages.dev

Modified Pages

• https://5ac52580.fastapitiangolo.pages.dev/tutorial/request-form-models/ - (before)

OK I added docs for this here: f63e983

While i was doing that, i realize i couldn't really write satisfying docs because the feature is arguably incomplete - We still needed a way to detect if we're being validated as a form (or being used elsewhere in the program) which was the whole root of the problem, so I added this into the field validation wrapper:

self._type_adapter.validate_python(
    value, from_attributes=True, context={"fastapi_field": self}
),

where we just pass the fastapi ModelField in the validation context. This should be a totally non-breaking change with near-zero perf consequences: all it does is allow a validator to opt-in to receiving the field as an additional field: https://docs.pydantic.dev/dev/concepts/validators/#validation-context

the reason that was necessary is hopefully obvious from the added docs, because otherwise it would be impossible to add special validation behavior only when handling form data without using inspect and getting the enclosing frames (awkward!).

Previously I had proposed a special @form_validator decorator that would serve this purpose, but haven't heard back on that, can still implement that.

I recognize that is a late addition to the PR, but it is still directly related to the purpose of the pr (being able to handle form data when it differs from e.g. json or model use within python). I can remove it if we don't like that.

edit: by the way! very cool docs setup. I tried to add pydantic v1 examples but it doesn't look like they're showing up in the docs preview, not sure what i am doing wrong there but they are in the docs src

If we want to get this reviewed by Sebastián and merged, our task is to prepare this PR so that the reviewing process would be as simple as possible for him.

I think for this we need to:

• Exclude unnecessary changes (not related to the main purpose)
• Revise tests (remove unnecessary, simplify, add new if needed)
• Update description
• Resolve and hide comments in conversation (maybe even close this PR and open new to have clean comment history)

@sneakers-the-rat & @luzzodev: thanks so much for your time and effort put into this. I also understand your frustration with the PR reviewing process. As you mentioned, it really is a huge task going through all the PRs in detail. Considering the amount of users of the library, we are very wary of introducing new bugs with new features, or even with bug fixes, and so we really do need to be very careful whenever we merge any PR. That said, I agree that the process should be more fluent especially when it comes to bug fixes. I also want to say I really appreciate how much work you've both put into creating solid tests etc, this is really crucial for the code quality.

With respect to Sebastián reviewing the "final" PR (whenever e.g. Yurii or I sign off of it), I can assure you he would take a lot more than 5 milliseconds to go over it. In fact, he is very meticulous in his reviewing process and goes through every detail, thinks of every edge case and often finds issues even when I for instance thought it was 100% good to merge. He knows this library inside-out like no one else, and that's why his final review is so important. But at the same time we try to make his job as efficient as possible to have each PR address only one atomic fix/feature. Hence Yurii's requests.

Anyway let's try and keep the momentum for this PR, as it would be unfortunate to lose this work. Ideally, we should try and work off the original PR to ensure the original contributor gets recognition as well. @YuriiMotov: do you have time to work on this?

appreciate everyone has limited time, and i am not trying to be a burden or ornery about having things my way, but i still maintain that the change that's being objected to is directly related to, and necessary to resolve the underlying issue for this PR.

The change is this single line that gives the outer type to the validation context as fastapi_field. the validation context is an opt-in object that a validator only gets if it requests it, this is exactly what it's for, it provides additional useful information for validators that could be used outside this case, it doesn't conflict with any current fastapi behavior, and it's effectively impossible that there is another key fastapi_field in that dictionary that would make this conflict with downstream use.

The reason this is core to the purpose of this PR is pretty simple:

• a) situation: form data needs to be validated differently than JSON data in some cases, e.g. booleans from checkboxes
• b) problem: we don't have enough information to apply validation logic only to form data because
  • b1) we can't access the original values to do the form-specific validation, and
  • b2) we can't tell when we're receiving form data anyway
• c) solution: we provide that information by
  • c1) not prefilling default values and allowing the model to fill its defaults in the normal validation flow
  • c2) allowing a validator to determine when it's being called with form data.

if we don't have (c2) then we don't solve the problem - we might be able to tell when a value with a default is missing, but that doesn't really matter because there's no way to distinguish form data from other contexts like in-program validation or validation from JSON!

Again, I had proposed several other means of accomplishing this like a @form_validator decorator, or using the information we already have from the Form() annotation on a bool field to just automatically handle the differences between json and form data, so this one line change is the most minimal change i could find that accomplished (c2). I would prefer the other means, but alas minimizing PR size precluded better fixes.

Revise tests (remove unnecessary, simplify, add new if needed)

I wrote tests that covered exactly the changes in the PR, and through review was asked to add several more. The docstrings in the tests describe what they are testing, and hopefully the parameterization is obvious enough. lmk which tests are unnecessary or how you would simplify them, but i am not seeing anything unnecessary there reading again.

Update description

i did update the description as requested. also let me know what needs to be updated there because to me it just describes the changes and provides links to context.

Resolve and hide comments in conversation

sure if closing and reopening the same PR to clear its history is a thing that's done around here, i can do that, no problem.

• c2) allowing a validator to determine when it's being called with form data.

if we don't have (c2) then we don't solve the problem - we might be able to tell when a value with a default is missing, but that doesn't really matter because there's no way to distinguish form data from other contexts like in-program validation or validation from JSON!

I already suggested a way to do this without adding context: #13464 (comment)

I know you didn't like it, but "there's no way to distinguish ..." is not true

One could also directly parse the binary from the Request, but I personally find adding a free, zero-maintenance feature that allows us to consistently use FastAPI's own semantics of Annotated[Model, Form()] without needing to litter my code with duplicate models as a workaround is sort of a win-win, but yes i suppose that is true.

if this is actually the way all the maintainers want things to work, i'm sort of worn down after 6 months, so I removed the one controversial line

📝 Docs preview for commit 1b8d0d7 at: https://c3a274c0.fastapitiangolo.pages.dev

Modified Pages

• https://c3a274c0.fastapitiangolo.pages.dev/tutorial/request-form-models/ - (before)

This pull request has a merge conflict that needs to be resolved.