When declaring response types, some pairs of types, when used in Union in response headers, and sometimes in JSON bodies, are ambiguous:
- for
Annotated[str | list[str], ${any no-explode param}], a scalar value can be interpreted as str or a single element `list[str].
- for
Annotated[list[str] | dict[str, str], ${any no-explode param}], raw value name,value can be interpreted as ['name', 'value'] or {'name':'value'}.
- for
str | ${any other scalar}
- In case of headers, all scalar values are syntactically strings, so it's only possible to tell them apart by trying each type argument of Union. Pydantic will attempt each type from left to right and stop at first successful validation. When generating code, bare string should be moved to the end in such case.
- in case of JSON body, primitive python types are serialized without quotes, but other scalar types supported by pydantic are simple strings.
- for
Union[float, int] or Union[int, float] integral values serialized as float (e.g. 2.0) will be interpreted depending on order of type arguments.
When generating code, most of these problems can be avoided by re-ordering types, but warnings/errors are still needed for human authors.
When declaring response types, some pairs of types, when used in
Unionin response headers, and sometimes in JSON bodies, are ambiguous:Annotated[str | list[str], ${any no-explode param}], a scalar value can be interpreted asstror a single element `list[str].Annotated[list[str] | dict[str, str], ${any no-explode param}], raw valuename,valuecan be interpreted as['name', 'value']or{'name':'value'}.str | ${any other scalar}Union[float, int]orUnion[int, float]integral values serialized as float (e.g.2.0) will be interpreted depending on order of type arguments.When generating code, most of these problems can be avoided by re-ordering types, but warnings/errors are still needed for human authors.