Apply case-insensitive field matching to optional nested models (#903) - #905

Fixes #903

Problem

With case_sensitive=False and env_nested_delimiter, environment variables fail to populate a nested model field when that nested model is declared optional. The raw (lowercase) env-var key is preserved instead of being resolved to the actual field-name casing:

class NestedModel(BaseModel):
    Name: str

class ConfigModel(BaseModel):
    nested: Optional[NestedModel] = None

class Settings(BaseSettings):
    config: ConfigModel
    model_config = SettingsConfigDict(env_nested_delimiter="__", case_sensitive=False)

os.environ["config__nested__name"] = "value"
Settings()  # ValidationError: config.nested.Name Field required

Removing Optional makes it work, so the optional and non-optional paths diverged.

Cause

_replace_field_names_case_insensitively rewrites lowercased env keys back to the real field casing by recursing through nested models. The recursion gate used:

_lenient_issubclass(sub_model_field.annotation, BaseModel)

For a required field the annotation is NestedModel (→ True, recurses). For an optional field the annotation is Optional[NestedModel], a Union (→ False), so it never recursed and the lowercase key survived. The function already unwrapped Optional for the outer field but not for this inner recursion check.

Fix

Extract the existing Optional[T] unwrapping into a small _unwrap_optional_annotation helper and apply it both at the top of the function (dedup, same behavior) and at the recursion gate, so optional nested models are resolved the same way as required ones.

Tests

Added test_case_insensitive_deeply_nested_optional mirroring the issue's repro (a required outer model containing an optional inner model — the deeper case the existing test_case_insensitive_nested_optional didn't cover). Verified it fails without the fix and passes with it. Full suite passes with no regressions.

🤖 Generated with Claude Code