Required nullable fields generate non-nullable types

[skylarmb]

Using openapi-python-generator 2.1.2 with OpenAPI 3.1, a required property declared like this:

description:
  type:
    - string
    - 'null'

is generated as str rather than Optional[str] / str | None.

Current behavior:

• required + nullable field -> non-nullable Python type
• non-required + nullable field -> nullable Python type

This is a bug because required only means the field must be present in the payload. It does not mean the value cannot be null. For a required nullable schema, the generated Python type should still accept None; otherwise the generated Pydantic models reject valid API responses containing null.

[skylarmb]

I dug into this locally and wanted to share the rough shape of a fix, not to prescribe the implementation details.

It looks like the problem is specifically in the schema.type list case: when the schema is something like ['string', 'null'] and the property is marked required, generation seems to pick the first type (string) and drop the nullability.

Approximately, the fix seems like it would look like:

def _is_null_type(type_value: object) -> bool:
    return (
        type_value == "null"
        or str(type_value) == "DataType.NULL"
        or getattr(type_value, "value", None) == "null"
    )

elif isinstance(schema.type, list) and len(schema.type) > 0:
    has_null = any(_is_null_type(t) for t in schema.type)
    non_null_types = [t for t in schema.type if not _is_null_type(t)]
    first_type = non_null_types[0] if non_null_types else schema.type[0]

    # existing logic to map first_type -> str / datetime / int / etc.
    converted_type = ...

    # required means present, not non-null
    if has_null and required and converted_type != "None":
        converted_type = f"Optional[{converted_type}]"

In other words, the nullable union member should still affect the generated Python type even when the field is required.

[skylarmb]

I worked around this for now by overriding the template and using --custom-template-path argument

{#
  Forked from openapi-python-generator's default template:
  https://github.com/MarcoMuellner/openapi-python-generator/blob/main/src/openapi_python_generator/language_converters/python/templates/models_pydantic_2.jinja2

  Changes from upstream:
  - Work around openapi-python-generator issue #135, where required nullable
    OpenAPI 3.1 fields (for example `type: [string, 'null']`) are rendered as
    non-nullable Python annotations.
  - When a field is required and its original OpenAPI type includes `null`,
    re-wrap the generated annotation in Optional[...] unless the converter
    already emitted a nullable type. This preserves the correct Pydantic v2
    semantics: the field must be present, but its value may be null.
#}
from typing import *
from pydantic import BaseModel, Field
{% for property in properties %}
{% if property.type.import_types is not none %}
{% for import_type in property.type.import_types %}
{{ import_type }}
{% endfor %}
{% endif %}
{% endfor %}

class {{ schema_name }}(BaseModel):
    """
    {% if schema.title %}{{ schema.title }}{% else %}{{ schema_name }}{% endif %} model
    {% if schema.description %}
    {{ schema.description }}
    {% endif %}
    {% if parent_comment %}
    {{ parent_comment }}
    {% endif %}
    """
    model_config = {
        "populate_by_name": True,
        "validate_assignment": True
    }
    {% for property in properties %}
    {% set annotation = property.type.converted_type %}
    {% set required_nullable = property.required and "null" in property.type.original_type and "Optional[" not in annotation and "None" not in annotation %}

    {{ property.name | normalize_symbol }} : {% if required_nullable %}Optional[{{ annotation }}]{% else %}{{ annotation | safe }}{% endif %} = Field(validation_alias="{{ property.name }}" {% if not property.required %}, default = {{ property.default }} {% endif %})
    {% endfor %}