Backtestspydanticrun-20260923-170312#13599

Issue #13599 Merged fix PR # Run 23 Sep 2026 · run-20260923-170312 pydantic/pydantic

PEP 695 type aliases don't work with callable discriminators

Better

Our patch was judged better than the merged fix.

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

The two patches are functionally near-identical: both thread `definitions` through `apply_discriminator` into `_convert_schema` and add a `_resolve_ref` helper that resolves a `definition-ref` via `handler` (schema-gen path) or `definitions.get()` (deferred/callable path). Both fix the reported root cause—an unresolved PEP 695 type-alias `definition-ref` at the union root/choice level when a callable Discriminator is used on a field. Correctness is essentially a wash. B's code is marginally cleaner (LookupError encapsulated inside `_resolve_ref` so failure is uniformly signaled as None, no duplicated try/except at call sites, and a `cast` to `DefinitionReferenceSchema` for type-correct `schema_ref` access), whereas A keeps the more conservative `(handler is not None or definitions is not None)` guards and repeats the try/except at each call site. However, A's guard preservation is functionally equivalent (when both are None, B's `_resolve_ref` just returns None to the same effect), and B additionally drops the guard on the root branch so a both-None `definition-ref` now raises `MissingDefinitionForUnionRef` instead of falling through—a benign but slightly broader behavior change. The decisive difference is test quality, which ranks above craft: A's test exercises both union branches (asserts Foo for `{'type':'foo'}` AND Bar for `{'type':'bar'}`), asserts `isinstance`, and uses a realistic discriminator handling both dict and attribute access (`v['type'] if isinstance(v, dict) else v.type`). B's test checks only the single 'foo' branch with a dict-only lambda (`lambda v: v['type']`), so it never verifies tag selection actually distinguishes choices. With correctness tied, A's meaningfully more thorough test edges out B's cleaner-but-slightly-broader implementation.

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

18m 14s14 turns

Wall-clock time in the container

Full test suite

No new failures

6,545 passed · 366 skipped · 6,911 total

Contamination audit

Unknown

See the audit notes for this run

Patch size

59vs 60 merged

Changed lines, ours vs merged

Initial Checks

  • I confirm that I'm using Pydantic V2

Description

New type aliases prefixed with the type keyword are not supported as the type annotation for a callable discriminator.

M1, M2, M4 ok
M3

pydantic.errors.PydanticUserError: `Tag` not provided for choice {'type': 'definition-ref', 'schema_ref': '__main__.TaggedAnyA:2210408548368'} used with `Discriminator`

Example Code from #12843 also doesn’t work.

Example Code

import traceback
from sys import stderr

from pydantic import BaseModel, Discriminator, Field, Tag
from typing_extensions import Annotated, Any, Literal, TypeAlias


class A(BaseModel):
    type_: str

class A1(A):
    type_: Literal['A1'] = Field(alias='type')

class A2(A):
    type_: Literal['A2'] = Field(alias='type')

def _discriminator(data: Any) -> str:
    if isinstance(data, dict):
        return data['type']
    return data.type_

discriminator = Discriminator(_discriminator)

type AnyA = A1 | A2
AnyA_old: TypeAlias = A1 | A2

type TaggedAnyA = Annotated[A1, Tag('A1')] | Annotated[A2, Tag('A2')]
TaggedAnyA_old: TypeAlias = Annotated[A1, Tag('A1')] | Annotated[A2, Tag('A2')]


_data = {"a" : {'type': 'A1'}}
try:
    class M1(BaseModel):
        a: AnyA = Field(discriminator='type_')

    M1.model_validate(_data)
except Exception as e:
    traceback.print_exc()
else:
    print("OK", file=stderr)

try:
    class M2(BaseModel):
        a: AnyA_old = Field(discriminator='type_')

    M2.model_validate(_data)
except Exception as e:
    traceback.print_exc()
else:
    print("OK", file=stderr)

try:
    class M3(BaseModel):
        a: TaggedAnyA = Field(discriminator=discriminator)

    M3.model_validate(_data)
except Exception as e:
    traceback.print_exc()
else:
    print("OK", file=stderr)

try:
    class M4(BaseModel):
        a: TaggedAnyA_old = Field(discriminator=discriminator)

    M4.model_validate(_data)
except Exception as e:
    traceback.print_exc()
else:
    print("OK", file=stderr)

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.14.7 (tags/v3.14.7:823f032, Aug  5 2026, 10:51:32) [MSC v.1944 64 bit (AMD64)]
                     platform: Windows-11-10.0.26200-SP0
             related packages: mypy-2.3.0 typing_extensions-4.16.0
                       commit: unknown

The two patches

Our patch+50 −9
pydantic/_internal/_discriminated_union.pyindex 94c82026..64f23145 100644@@ -65,7 +65,7 @@ def apply_discriminator(         if isinstance(discriminator.discriminator, str):             discriminator = discriminator.discriminator         else:-            return discriminator._convert_schema(schema)+            return discriminator._convert_schema(schema, definitions=definitions)      return _ApplyInferredDiscriminator(discriminator, definitions or {}).apply(schema) pydantic/types.pyindex f32a2ab8..3edb410d 100644@@ -3112,13 +3112,27 @@ class Discriminator:             return self._convert_schema(original_schema, handler)      def _convert_schema(-        self, original_schema: core_schema.CoreSchema, handler: GetCoreSchemaHandler | None = None+        self,+        original_schema: core_schema.CoreSchema,+        handler: GetCoreSchemaHandler | None = None,+        definitions: dict[str, core_schema.CoreSchema] | None = None,     ) -> core_schema.TaggedUnionSchema:-        if handler is not None and original_schema['type'] == 'definition-ref':+        def _resolve_ref(schema: core_schema.CoreSchema) -> core_schema.CoreSchema | None:+            # `schema` is a 'definition-ref'. Resolve it using whichever is available.+            if handler is not None:+                return handler.resolve_ref_schema(schema)+            if definitions is not None:+                return definitions.get(schema['schema_ref'])+            return None++        if (handler is not None or definitions is not None) and original_schema['type'] == 'definition-ref':             # Same logic as `_ApplyInferredDiscriminator._apply_to_root()`             try:-                def_schema = handler.resolve_ref_schema(original_schema)+                def_schema = _resolve_ref(original_schema)             except LookupError:  # pragma: no cover+                def_schema = None++            if def_schema is None:                 from pydantic._internal._discriminated_union import MissingDefinitionForUnionRef                  raise MissingDefinitionForUnionRef(original_schema['schema_ref'])@@ -3144,14 +3158,16 @@ class Discriminator:             if metadata is not None:                 tag = metadata.get('pydantic_internal_union_tag_key') or tag             if tag is None:-                # `handler` is None when this method is called from `apply_discriminator()` (deferred discriminators)-                if handler is not None and choice['type'] == 'definition-ref':+                # `handler` is None when this method is called from `apply_discriminator()` (deferred discriminators);+                # in that case `definitions` may be provided instead.+                if (handler is not None or definitions is not None) and choice['type'] == 'definition-ref':                     # If choice was built from a PEP 695 type alias, try to resolve the def:                     try:-                        choice = handler.resolve_ref_schema(choice)+                        resolved_choice = _resolve_ref(choice)                     except LookupError:-                        pass-                    else:+                        resolved_choice = None+                    if resolved_choice is not None:+                        choice = resolved_choice                         metadata = cast('CoreMetadata | None', choice.get('metadata'))                         if metadata is not None:                             tag = metadata.get('pydantic_internal_union_tag_key')tests/types/unions/test_discriminated_union.pyindex fccb82fb..3cf18e2d 100644@@ -2338,6 +2338,31 @@ def test_discriminated_union_type_alias_type_separate_callable_discriminator() -     assert m.g == Bar(type='bar')  +def test_discriminated_union_type_alias_type_separate_field_callable_discriminator() -> None:+    """https://github.com/pydantic/pydantic/issues/13599"""++    class Foo(BaseModel):+        type: Literal['foo']++    class Bar(BaseModel):+        type: Literal['bar']++    FooBar = TypeAliasType('FooBar', Annotated[Foo, Tag('foo')] | Annotated[Bar, Tag('bar')])++    def get_disc(v: Any) -> str:+        return v['type'] if isinstance(v, dict) else v.type++    class Main(BaseModel):+        f: FooBar = Field(discriminator=Discriminator(get_disc))++    m = Main(f={'type': 'foo'})+    assert isinstance(m.f, Foo)+    assert m.f == Foo(type='foo')++    m2 = Main(f={'type': 'bar'})+    assert isinstance(m2.f, Bar)++ @pytest.mark.xfail(     reason="Nested references aren't flattened (see comment in `_ApplyInferredDiscriminator._handle_choice()`)", ) 
Merged fix · PR #+47 −13
pydantic/_internal/_discriminated_union.pyindex 94c82026c..64f231459 100644@@ -65,7 +65,7 @@ def apply_discriminator(         if isinstance(discriminator.discriminator, str):             discriminator = discriminator.discriminator         else:-            return discriminator._convert_schema(schema)+            return discriminator._convert_schema(schema, definitions=definitions)      return _ApplyInferredDiscriminator(discriminator, definitions or {}).apply(schema) pydantic/types.pyindex f32a2ab80..50f94cf43 100644@@ -3112,13 +3112,29 @@ class Discriminator:             return self._convert_schema(original_schema, handler)      def _convert_schema(-        self, original_schema: core_schema.CoreSchema, handler: GetCoreSchemaHandler | None = None+        self,+        original_schema: core_schema.CoreSchema,+        handler: GetCoreSchemaHandler | None = None,+        definitions: dict[str, core_schema.CoreSchema] | None = None,     ) -> core_schema.TaggedUnionSchema:-        if handler is not None and original_schema['type'] == 'definition-ref':+        def _resolve_ref(schema: core_schema.CoreSchema) -> core_schema.CoreSchema | None:+            # `handler` is set when this method is called while generating the schema for the field+            # (e.g. via `Annotated[<type>, Discriminator(...)]`). `definitions` is set instead when+            # this method is called from `apply_discriminator()` (deferred/callable discriminators).+            if handler is not None:+                try:+                    return handler.resolve_ref_schema(schema)+                except LookupError:  # pragma: no cover+                    return None+            elif definitions is not None:+                schema_ref = cast(core_schema.DefinitionReferenceSchema, schema)['schema_ref']+                return definitions.get(schema_ref)+            return None++        if original_schema['type'] == 'definition-ref':             # Same logic as `_ApplyInferredDiscriminator._apply_to_root()`-            try:-                def_schema = handler.resolve_ref_schema(original_schema)-            except LookupError:  # pragma: no cover+            def_schema = _resolve_ref(original_schema)+            if def_schema is None:                 from pydantic._internal._discriminated_union import MissingDefinitionForUnionRef                  raise MissingDefinitionForUnionRef(original_schema['schema_ref'])@@ -3144,14 +3160,11 @@ class Discriminator:             if metadata is not None:                 tag = metadata.get('pydantic_internal_union_tag_key') or tag             if tag is None:-                # `handler` is None when this method is called from `apply_discriminator()` (deferred discriminators)-                if handler is not None and choice['type'] == 'definition-ref':+                if choice['type'] == 'definition-ref':                     # If choice was built from a PEP 695 type alias, try to resolve the def:-                    try:-                        choice = handler.resolve_ref_schema(choice)-                    except LookupError:-                        pass-                    else:+                    resolved_choice = _resolve_ref(choice)+                    if resolved_choice is not None:+                        choice = resolved_choice                         metadata = cast('CoreMetadata | None', choice.get('metadata'))                         if metadata is not None:                             tag = metadata.get('pydantic_internal_union_tag_key')tests/types/unions/test_discriminated_union.pyindex fccb82fbb..637679102 100644@@ -2338,6 +2338,27 @@ def test_discriminated_union_type_alias_type_separate_callable_discriminator() -     assert m.g == Bar(type='bar')  +def test_discriminated_union_type_alias_type_separate_callable_discriminator_field() -> None:+    """https://github.com/pydantic/pydantic/issues/13599"""++    class Foo(BaseModel):+        type: Literal['foo']++    class Bar(BaseModel):+        type: Literal['bar']++    FooBar = TypeAliasType('FooBar', Annotated[Foo, Tag('foo')] | Annotated[Bar, Tag('bar')])++    discriminator = Discriminator(lambda v: v['type'])++    class Main(BaseModel):+        f: FooBar = Field(discriminator=discriminator)++    m = Main(f={'type': 'foo'})++    assert m.f == Foo(type='foo')++ @pytest.mark.xfail(     reason="Nested references aren't flattened (see comment in `_ApplyInferredDiscriminator._handle_choice()`)", ) 

What the agent reported

Done. Three intended files changed, no scratch files, tmp_repro.py removed.

Summary

What was wrong

PEP 695 type aliases (type X = ... / TypeAliasType) failed with callable discriminators applied via Field(discriminator=Discriminator(callable)), raising PydanticUserError:Tagnot provided for choice {...definition-ref...}.

The cause: for a PEP 695 alias, the field's core schema is a top-level definition-ref pointing to the union stored in the definitions dict. apply_discriminator() (pydantic/_internal/_discriminated_union.py) routed callable discriminators to Discriminator._convert_schema(schema) without forwarding the definitions dict. _convert_schema could unwrap definition-ref schemas only when a handler was present — but the Field/deferred path has handler=None. So the top-level definition-ref was never unwrapped; it got wrapped in a single-item union whose sole choice was the raw definition-ref with no Tag → the error. (String discriminators and old-style TypeAlias worked because they take a different code path / inline the members. The existing #12843 test passed because it uses Annotated[..., Discriminator(...)], which goes through the handler path that was already patched.)

What I changed

  • pydantic/types.py: Discriminator._convert_schema now accepts a definitions param and resolves definition-ref schemas (top-level union ref and per-choice refs) from either the handler or the definitions dict, via a small _resolve_ref helper. Behavior for the existing handler-present path is unchanged (when called from __get_pydantic_core_schema__, definitions is None, so the guard conditions are identical to before). Unresolvable top-level refs still raise MissingDefinitionForUnionRef (enabling deferral).
  • pydantic/_internal/_discriminated_union.py: apply_discriminator now forwards definitions to _convert_schema.
  • tests/types/unions/test_discriminated_union.py: added test_discriminated_union_type_alias_type_separate_field_callable_discriminator (issue #13599).

Test evidence

  • New regression test failed before the fix with the exact reported PydanticUserError (raised at Main class definition).
  • After the fix, ./bt-test tests/types/unions/test_discriminated_union.py tests/test_type_alias_type.py: 98 passed, 4 xfailed (the 4 pre-existing xfails unchanged; no previously passing test regressed; new test passes).
  • Reviewer confirmed the diff is minimal, targets the exact scenario, and does not alter the handler path.

Requirements checklist (from the report)

  • M3 — type TaggedAnyA (PEP 695 alias) + callable Discriminator via Field(discriminator=...): fixed with test evidence (this is the reported failure; regression test covers the runtime-equivalent TypeAliasType form, which the test file uses throughout for PEP 695 coverage).
  • M4 — old-style TypeAlias + callable discriminator: already worked; still passes (covered by existing suite; unchanged by the diff).
  • M1 / M2 — string-discriminator (Field(discriminator='type_')) with PEP 695 and old-style aliases: already worked; still pass (inferred-discriminator path, untouched; confirmed by the passing suite).
  • "Example Code from #12843 also doesn't work" — the #12843 Annotated[..., Discriminator] form was already covered by test_discriminated_union_type_alias_type_separate_callable_discriminator (passing); the reporter's remaining failure was the Field(discriminator=...) variant, which is what this fix and the new test address.

All changes are left uncommitted in the working tree.