Backtestspydanticrun-20261003-150343#13660

Issue #13660 Merged fix PR #13667 Run 3 Oct 2026 · run-20261003-150343 pydantic/pydantic

None is not treated as Literal[None] when annotating the discriminator in discriminated unions.

Better

Our patch was judged better than the merged fix.

In this judgment, Patch A = our agent, Patch B = the merged fix.

Both patches fix the root cause the same way: `_infer_discriminator_values_for_inner_schema` now maps a `'none'` core schema to `[None]`. That makes `field: None` behave like `Literal[None]`.

Patch A makes this a small, targeted addition in the existing if/elif style. It also adds a `'nullable'` branch so that `Optional[Literal[...]]` contributes `None`. That branch is extra but low-risk and consistent with the issue's premise that `None` is equivalent to `Literal[None]`. Its tests are meaningful and would fail before the change:
- the exact scenario from the issue, including validation in both directions;
- the `union_tag_invalid` error output showing `None` among the expected tags;
- the `Optional[Literal]` case;
- a duplicate-mapping check confirming that `None` and `Literal[None]` collide as equivalent tags.

Patch B has the same core fix, plus a useful JSON-schema tweak that maps the `None` key to `'null'`. However, it adds considerable risk and churn:
1. It rewrites the whole function as a `match` statement. This is a stylistic redesign unrelated to the fix, and it requires Python 3.10+, which may conflict with the project's supported Python versions.
2. It changes the pydantic-core `TaggedUnionSchema` type hints (removing `Hashable`) and many unrelated signatures.
3. It changes `schema.get('root_model')` truthiness semantics into a literal match on `True`.
4. It weakens the existing `test_bool_discriminated_union` from a full-schema equality check to checking only the discriminator, which removes coverage for no reason.

Patch B's JSON-schema 'null' mapping is a nice touch, but it does not outweigh the risky rewrite and the reduced test coverage. Patch A is the cleaner, safer, better-tested fix.

The judge saw only the two patches, labelled A and B in random order, with issue links and version numbers removed. The reasoning above is shown verbatim.

Solve

7m 3s

Wall-clock time in the container

Full test suite

No new failures

12,348 passed · 500 skipped · 12,848 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

69vs 162 merged

Changed lines, ours vs merged

Initial Checks

  • I confirm that I'm using Pydantic V2

Description

Literal[None] and None should be semantically equivalent type annotations, to the point that flake8-pyi and ruff have warnings for the former: https://docs.astral.sh/ruff/rules/redundant-none-literal/

Pydantic does however not treat them as semantically equivalent for the purposes of discriminated unions.

Example Code

from typing import Annotated, Literal

from pydantic import BaseModel, Field


class A(BaseModel):
    field: Literal["A"] = "A"


class B(BaseModel):
    field: None = None


class Foo(BaseModel):
    a_or_b: Annotated[A | B, Field(discriminator="field")]

# Results in the error below. 
# If `: None` is replaced with `: Literal[None]` then there is no error.
# ...
# pydantic.errors.PydanticUserError: Model 'B' needs field 'field' to be of type `Literal`
# 
# For further information visit https://errors.pydantic.dev/2.13/u/discriminator-needs-literal

Python, Pydantic & OS Version

     pydantic version: 2.13.4
pydantic-core version: 2.46.4
  pydantic-core build: profile=release pgo=false
       python version: 3.12.8 (main, Jan  5 2025, 05:33:15) [Clang 19.1.6 ]
             platform: Linux-5.19.0-35-generic-x86_64-with-glibc2.35
     related packages: typing_extensions-4.16.0 email-validator-2.3.0
               commit: unknown

The two patches

Our patch+68 −1
pydantic/_internal/_discriminated_union.pyindex 64f23145..ce08dc67 100644@@ -438,6 +438,16 @@ class _ApplyInferredDiscriminator:         if schema['type'] == 'literal':             return schema['expected'] +        elif schema['type'] == 'none':+            # A field annotated as `None` is equivalent to `Literal[None]`+            none_values: list[Any] = [None]+            return none_values++        elif schema['type'] == 'nullable':+            # `Optional[X]` (or `X | None`) is equivalent to `Union[X, Literal[None]]`+            nullable_values: list[Any] = self._infer_discriminator_values_for_inner_schema(schema['schema'], source)+            return [*nullable_values, None]+         elif schema['type'] == 'union':             # Generally when multiple values are allowed they should be placed in a single `Literal`, but             # we add this case to handle the situation where a field is annotated as a `Union` of `Literal`s.tests/types/unions/test_discriminated_union.pyindex 63767910..234fbbf7 100644@@ -6,7 +6,7 @@ from copy import deepcopy from dataclasses import dataclass from enum import Enum, IntEnum from types import SimpleNamespace-from typing import Annotated, Any, ClassVar, Generic, Literal, TypeVar, Union+from typing import Annotated, Any, ClassVar, Generic, Literal, Optional, TypeVar, Union  import pytest from dirty_equals import HasRepr, IsStr@@ -2604,3 +2604,60 @@ def test_union_tags_in_errors():             'type': 'dict_type',         },     ]+++def test_discriminated_union_none_discriminator() -> None:+    """A discriminator field annotated as `None` behaves like `Literal[None]`."""++    class A(BaseModel):+        field: Literal['A'] = 'A'++    class B(BaseModel):+        field: None = None++    class Foo(BaseModel):+        a_or_b: Annotated[Union[A, B], Field(discriminator='field')]++    assert isinstance(Foo(a_or_b={'field': 'A'}).a_or_b, A)+    assert isinstance(Foo(a_or_b={'field': None}).a_or_b, B)++    with pytest.raises(ValidationError) as exc_info:+        Foo(a_or_b={'field': 'C'})+    assert exc_info.value.errors(include_url=False) == [+        {+            'ctx': {'discriminator': "'field'", 'expected_tags': "'A', None", 'tag': 'C'},+            'input': {'field': 'C'},+            'loc': ('a_or_b',),+            'msg': "Input tag 'C' found using 'field' does not match any of the expected tags: 'A', None",+            'type': 'union_tag_invalid',+        }+    ]+++def test_discriminated_union_optional_literal_discriminator() -> None:+    """A discriminator field annotated as `Optional[Literal[...]]` behaves like `Literal[..., None]`."""++    class A(BaseModel):+        field: Optional[Literal['A']]++    class B(BaseModel):+        field: Literal['B']++    ta = TypeAdapter(Annotated[Union[A, B], Field(discriminator='field')])++    assert isinstance(ta.validate_python({'field': 'A'}), A)+    assert isinstance(ta.validate_python({'field': None}), A)+    assert isinstance(ta.validate_python({'field': 'B'}), B)+++def test_discriminated_union_none_discriminator_duplicate() -> None:+    class A(BaseModel):+        field: None++    class B(BaseModel):+        field: Literal[None]++    with pytest.raises(TypeError, match="Value None for discriminator 'field' mapped to multiple choices"):++        class Foo(BaseModel):+            a_or_b: Annotated[Union[A, B], Field(discriminator='field')] 
Merged fix · PR #13667+77 −85
pydantic-core/python/pydantic_core/core_schema.pyindex 85f6a8c04..cb87ad5ae 100644@@ -7,7 +7,7 @@ from __future__ import annotations as _annotations  import sys import warnings-from collections.abc import Callable, Generator, Hashable, Mapping+from collections.abc import Callable, Generator, Mapping from datetime import date, datetime, time, timedelta from decimal import Decimal from fractions import Fraction@@ -2761,8 +2761,8 @@ def union_schema(  class TaggedUnionSchema(TypedDict, total=False):     type: Required[Literal['tagged-union']]-    choices: Required[dict[Hashable, CoreSchema]]-    discriminator: Required[str | list[str | int] | list[list[str | int]] | Callable[[Any], Hashable]]+    choices: Required[dict[Any, CoreSchema]]+    discriminator: Required[str | list[str | int] | list[list[str | int]] | Callable[[Any], Any]]     custom_error_type: str     custom_error_message: str     custom_error_context: dict[str, str | int | float]pydantic/_internal/_discriminated_union.pyindex 64f231459..554a4974d 100644@@ -1,6 +1,5 @@ from __future__ import annotations as _annotations -from collections.abc import Hashable, Sequence from typing import TYPE_CHECKING, Any, cast  from pydantic_core import CoreSchema, core_schema@@ -132,7 +131,7 @@ class _ApplyInferredDiscriminator:          # `_tagged_union_choices` is built during the call to `apply`, and will hold the choices to be included         # in the output TaggedUnionSchema that will replace the union from the input schema-        self._tagged_union_choices: dict[Hashable, core_schema.CoreSchema] = {}+        self._tagged_union_choices: dict[Any, core_schema.CoreSchema] = {}          # `_used` is changed to True after applying the discriminator to prevent accidental reuse         self._used = False@@ -303,7 +302,7 @@ class _ApplyInferredDiscriminator:      def _infer_discriminator_values_for_choice(  # noqa C901         self, choice: core_schema.CoreSchema, source_name: str | None-    ) -> list[str | int]:+    ) -> list[Any]:         """This function recurses over `choice`, extracting all discriminator values that should map to this choice.          `model_name` is accepted for the purpose of producing useful error messages.@@ -323,7 +322,7 @@ class _ApplyInferredDiscriminator:             )          elif choice['type'] == 'tagged-union':-            values: list[str | int] = []+            values: list[Any] = []             # Ignore str/int "choices" since these are just references to other choices             subchoices = [x for x in choice['choices'].values() if not isinstance(x, (str, int))]             for subchoice in subchoices:@@ -374,7 +373,7 @@ class _ApplyInferredDiscriminator:      def _infer_discriminator_values_for_typed_dict_choice(         self, choice: core_schema.TypedDictSchema, source_name: str | None = None-    ) -> list[str | int]:+    ) -> list[Any]:         """This method just extracts the _infer_discriminator_values_for_choice logic specific to TypedDictSchema         for the sake of readability.         """@@ -388,7 +387,7 @@ class _ApplyInferredDiscriminator:      def _infer_discriminator_values_for_model_choice(         self, choice: core_schema.ModelFieldsSchema, source_name: str | None = None-    ) -> list[str | int]:+    ) -> list[Any]:         source = 'ModelFields' if source_name is None else f'Model {source_name!r}'         field = choice['fields'].get(self.discriminator)         if field is None:@@ -399,7 +398,7 @@ class _ApplyInferredDiscriminator:      def _infer_discriminator_values_for_dataclass_choice(         self, choice: core_schema.DataclassArgsSchema, source_name: str | None = None-    ) -> list[str | int]:+    ) -> list[Any]:         source = 'DataclassArgs' if source_name is None else f'Dataclass {source_name!r}'         for field in choice['fields']:             if field['name'] == self.discriminator:@@ -410,7 +409,7 @@ class _ApplyInferredDiscriminator:             )         return self._infer_discriminator_values_for_field(field, source) -    def _infer_discriminator_values_for_field(self, field: CoreSchemaField, source: str) -> list[str | int]:+    def _infer_discriminator_values_for_field(self, field: CoreSchemaField, source: str) -> list[Any]:         if field['type'] == 'computed-field':             # This should never occur as a discriminator, as it is only relevant to serialization             return []@@ -429,53 +428,48 @@ class _ApplyInferredDiscriminator:             )         return self._infer_discriminator_values_for_inner_schema(field['schema'], source) -    def _infer_discriminator_values_for_inner_schema(-        self, schema: core_schema.CoreSchema, source: str-    ) -> list[str | int]:+    def _infer_discriminator_values_for_inner_schema(self, schema: core_schema.CoreSchema, source: str) -> list[Any]:         """When inferring discriminator values for a field, we typically extract the expected values from a literal         schema. This function does that, but also handles nested unions and defaults.         """-        if schema['type'] == 'literal':-            return schema['expected']--        elif schema['type'] == 'union':-            # Generally when multiple values are allowed they should be placed in a single `Literal`, but-            # we add this case to handle the situation where a field is annotated as a `Union` of `Literal`s.-            # For example, this lets us handle `Union[Literal['key'], Union[Literal['Key'], Literal['KEY']]]`-            values: list[Any] = []-            for choice in schema['choices']:-                choice_schema = choice[0] if isinstance(choice, tuple) else choice-                choice_values = self._infer_discriminator_values_for_inner_schema(choice_schema, source)-                values.extend(choice_values)-            return values--        elif schema['type'] == 'default':-            # This will happen if the field has a default value; we ignore it while extracting the discriminator values-            return self._infer_discriminator_values_for_inner_schema(schema['schema'], source)--        elif schema['type'] == 'function-after':-            # After validators don't affect the discriminator values-            return self._infer_discriminator_values_for_inner_schema(schema['schema'], source)--        elif schema['type'] == 'model' and schema.get('root_model'):-            # Support RootModel[Literal[...]] as discriminator field type-            return self._infer_discriminator_values_for_inner_schema(schema['schema'], source)--        elif schema['type'] in {'function-before', 'function-wrap', 'function-plain'}:-            validator_type = repr(schema['type'].split('-')[1])-            raise PydanticUserError(-                f'Cannot use a mode={validator_type} validator in the'-                f' discriminator field {self.discriminator!r} of {source}',-                code='discriminator-validator',-            )--        else:-            raise PydanticUserError(-                f'{source} needs field {self.discriminator!r} to be of type `Literal`',-                code='discriminator-needs-literal',-            )+        match schema:+            case {'type': 'literal', 'expected': expected}:+                return expected+            case {'type': 'none'}:+                return [None]+            case {'type': 'union', 'choices': choices}:+                # Generally when multiple values are allowed they should be placed in a single `Literal`, but+                # we add this case to handle the situation where a field is annotated as a `Union` of `Literal`s.+                # For example, this lets us handle `Union[Literal['key'], Union[Literal['Key'], Literal['KEY']]]`+                values: list[Any] = []+                for choice in choices:+                    choice_schema = choice[0] if isinstance(choice, tuple) else choice+                    choice_values = self._infer_discriminator_values_for_inner_schema(choice_schema, source)+                    values.extend(choice_values)+                return values+            case {'type': 'default', 'schema': inner_schema}:+                # This will happen if the field has a default value; we ignore it while extracting the discriminator values+                return self._infer_discriminator_values_for_inner_schema(inner_schema, source)+            case {'type': 'function-after', 'schema': inner_schema}:+                # After validators don't affect the discriminator values+                return self._infer_discriminator_values_for_inner_schema(inner_schema, source)+            case {'type': 'model', 'root_model': True, 'schema': inner_schema}:+                # Support RootModel[Literal[...]] as discriminator field type+                return self._infer_discriminator_values_for_inner_schema(inner_schema, source)+            case {'type': 'function-before' | 'function-wrap' | 'function-plain' as schema_type}:+                validator_type = repr(schema_type.split('-')[1])+                raise PydanticUserError(+                    f'Cannot use a mode={validator_type} validator in the'+                    f' discriminator field {self.discriminator!r} of {source}',+                    code='discriminator-validator',+                )+            case _:+                raise PydanticUserError(+                    f'{source} needs field {self.discriminator!r} to be of type `Literal`',+                    code='discriminator-needs-literal',+                ) -    def _set_unique_choice_for_values(self, choice: core_schema.CoreSchema, values: Sequence[str | int]) -> None:+    def _set_unique_choice_for_values(self, choice: core_schema.CoreSchema, values: list[Any]) -> None:         """This method updates `self.tagged_union_choices` so that all provided (discriminator) `values` map to the         provided `choice`, validating that none of these values already map to another (different) choice.         """pydantic/json_schema.pyindex c61378a5f..c2183e193 100644@@ -1384,6 +1384,8 @@ class GenerateJsonSchema:                 # Use the JSON representation so that the discriminator mapping                 # can be matched against the serialized payload value                 k = 'true' if k else 'false'+            elif k is None:+                k = 'null'             try:                 # Use str(k) since keys must be strings for json; while not technically correct,                 # it's the closest that can be represented in valid JSONtests/test_json_schema.pyindex 2d67f01ae..9cca32928 100644@@ -3986,40 +3986,36 @@ def test_bool_discriminated_union() -> None:     class Model(BaseModel):         setting: Enabled | Disabled = Field(discriminator='enabled') -    assert Model.model_json_schema() == {-        '$defs': {-            'Disabled': {-                'properties': {'enabled': {'const': False, 'title': 'Enabled', 'type': 'boolean'}},-                'required': ['enabled'],-                'title': 'Disabled',-                'type': 'object',-            },-            'Enabled': {-                'properties': {-                    'config': {'title': 'Config', 'type': 'string'},-                    'enabled': {'const': True, 'title': 'Enabled', 'type': 'boolean'},-                },-                'required': ['enabled', 'config'],-                'title': 'Enabled',-                'type': 'object',-            },-        },-        'properties': {-            'setting': {-                'discriminator': {-                    'mapping': {'false': '#/$defs/Disabled', 'true': '#/$defs/Enabled'},-                    'propertyName': 'enabled',-                },-                'oneOf': [{'$ref': '#/$defs/Enabled'}, {'$ref': '#/$defs/Disabled'}],-                'title': 'Setting',-            }-        },-        'required': ['setting'],-        'title': 'Model',-        'type': 'object',+    assert Model.model_json_schema()['properties']['setting']['discriminator'] == {+        'mapping': {'false': '#/$defs/Disabled', 'true': '#/$defs/Enabled'},+        'propertyName': 'enabled',     }  +def test_none_discriminated_union() -> None:+    """https://github.com/pydantic/pydantic/issues/13660"""++    class A(BaseModel):+        field: Literal['A'] = 'A'++    class B(BaseModel):+        field: None = None++    class Model(BaseModel):+        a_or_b: Annotated[A | B, Field(discriminator='field')]++    assert Model.model_json_schema()['properties']['a_or_b']['discriminator'] == {+        'mapping': {'A': '#/$defs/A', 'null': '#/$defs/B'},+        'propertyName': 'field',+    }++    m = Model.model_validate({'a_or_b': {'field': None}})+    assert isinstance(m.a_or_b, B)++    m2 = Model.model_validate({'a_or_b': {'field': 'A'}})+    assert isinstance(m2.a_or_b, A)++ def test_nested_discriminated_union():     class BlackCatWithHeight(BaseModel):         color: Literal['black']