Optional fields and nullability - OpenAPI spec

[bunny-therapist]

The request/response bodies in my application are defined via pydantic models, and they have some optional fields, i.e., fields which do not have to appear in the body. The models define these as Optional[X] = None (where X is some type). The resulting OpenAPI specification describes these parameters as not required (there is no "required" text below the parameter name), and states their types as "null or X".

However, my actual intention is for these fields to either be present, with type X, or completely absent. So the field should be of type X (not "null or X"), just not required. I can't find any way to define this behavior. I believe OpenAPI itself makes a distinction between nullability and optional fields (nullable is a separate field from required), so I feel like there should be a way to do it. Is there? Should there be? If not, is it a shortcoming of Litestar or of pydantic?

[provinzkraut]

You'll simply have to remove the default value. Optional[X] is short for Union[X, None]. Union[X, None] = None means "A non-required parameter that can have a value of type X or None and defaults to None". If you want a required, nullable parameter, thats Union[X, None], or Optional[None].

[provinzkraut]

Sorry for the misunderstanding, I was going by what you said the model currently represents,
and that's now how the parameter is defined in the model. Optional[X] = None is non-required and nullable.

Anyway, you can't really model this in Python. If you define a model with an attribute, that attribute has to have some value. If you truly want this parameter to only be sometimes present, you'll need to define two different models and declare the body as a union of both of them.

If you do not want to do this, you'll have to provide some default value, which you will have to check against.

If you are using msgspec, you can achieve this by using UNSET (X | UNSET = UNSET), and if you're using Pydantic you'll have to come up with your own default (you could use litestar.types.Empty for example. Check out this handy table in the Pydantic docs about required and nullable fields in the pydantic docs).

[guacs]

Maybe this could be modeled using TypedDict since you can annotate fields with NotRequired. However, I'm not sure about how we handle them currently but it feels reasonable to say that it's non-required and non-nullable field if the model is a TypedDict and the field is annotated as NotRequired.

On the other hand, like @provinzkraut said, if you're using dataclasses or pydantic etc, then I don't think this is possible.

[bunny-therapist]

Apparently TypedDict does not give you any body specification in the OpenAPI spec. It just becomes "object", like it was an untyped dict.

[guacs]

@bunny-therapist can you show an MCVE?

I get the expected schema for the following example:

from typing import TypedDict

from typing_extensions import NotRequired

from litestar import Litestar
from litestar.handlers.http_handlers.decorators import get
from litestar.testing import create_test_client


class Foo(TypedDict):
    foo: int
    bar: NotRequired[str]


@get()
async def get_foo() -> Foo:
    ...


with create_test_client([get_foo]) as client:
    resp = client.get("/schema/openapi.json")

    print(resp.json())

{
    'info': {'title': 'Litestar API', 'version': '1.0.0'},
    'openapi': '3.1.0',
    'servers': [{'url': '/'}],
    'paths': {
        '/': {
            'get': {
                'summary': 'GetFoo',
                'operationId': 'GetFoo',
                'responses': {
                    '200': {
                        'description': 'Request fulfilled, document follows',
                        'headers': {},
                        'content': {'application/json': {'schema': {'$ref': '#/components/schemas/Foo'}}}
                    }
                },
                'deprecated': False
            }
        }
    },
    'components': {'schemas': {'Foo': {'properties': {'foo': {'type': 'integer'}, 'bar': {'type': 'string'}}, 'type': 'object', 'required': ['foo'], 'title': 'Foo'}}}
}

[bunny-therapist]

You are right, it works. I must have looked at the wrong endpoint or something.