fix(python): serialize unrecognized open enum values

UnrecognizedStr and UnrecognizedInt had no serialization schema, so
dumping a model holding an unknown open enum value emitted Pydantic
serialization warnings. In an optional nullable open enum field, the
value was serialized by the Unset member of the union and then dropped
from the output, so the request body omitted it.

Give both types an explicit serializer: Python-mode dumps return the
original object, JSON-mode dumps return a plain str or int, and values
of any other type are declined so union serialization tries the
remaining members.

Author: 2ynn

.changesets/1792768199-b0e4a14b.yaml

@@ -0,0 +1,10 @@
+id: 1792768199-b0e4a14b
+features:
+    - core
+targets:
+    - pythonv2
+type: fix
+bump: patch
+description: serialize unrecognized open enum values without warnings and keep them in optional nullable fields
+author: 2ynn
+date: "2026-10-23"

templates/templates/pythonv2/auxiliary/{{getSourcePath}}/types/basemodel.py

@@ -1,7 +1,7 @@
 from pydantic import ConfigDict, model_serializer
 from pydantic import BaseModel as PydanticBaseModel
-from pydantic_core import core_schema
-from typing import TYPE_CHECKING, Any, Literal, Optional, TypeVar, Union
+from pydantic_core import PydanticSerializationUnexpectedValue, core_schema
+from typing import TYPE_CHECKING, Any, Literal, Optional, Type, TypeVar, Union
 from typing_extensions import TypeAliasType, TypeAlias
 
 
@@ -35,6 +35,18 @@ def __bool__(self) -> Literal[False]:
     )
 
 
+def _unrecognized_serialization(cls: Type[Union[str, int]]) -> core_schema.PlainSerializerFunctionSerSchema:
+    def serialize(value: Any, info: core_schema.SerializationInfo) -> Any:
+        # Decline other values so union serialization tries the remaining members
+        if not isinstance(value, cls):
+            raise PydanticSerializationUnexpectedValue(f"Expected {cls.__name__}")
+        if not info.mode_is_json():
+            return value
+        return str(value) if isinstance(value, str) else int(value)
+
+    return core_schema.plain_serializer_function_ser_schema(serialize, info_arg=True)
+
+
 class UnrecognizedStr(str):
     @classmethod
     def __get_pydantic_core_schema__(cls, _source_type: Any, _handler: Any) -> core_schema.CoreSchema:
@@ -54,6 +66,7 @@ def validate_lax(v: Any) -> 'UnrecognizedStr':
                 core_schema.no_info_plain_validator_function(validate_lax)
             ]),
             strict_schema=core_schema.none_schema(),  # Always fails in strict mode
+            serialization=_unrecognized_serialization(cls),
         )
 
 
@@ -72,4 +85,5 @@ def validate_lax(v: Any) -> 'UnrecognizedInt':
                 core_schema.no_info_plain_validator_function(validate_lax)
             ]),
             strict_schema=core_schema.none_schema(),  # Always fails in strict mode
+            serialization=_unrecognized_serialization(cls),
         )

templates/templates/pythonv2/tests/primary/test_open_enum_union_discrimination.py

@@ -7,12 +7,14 @@
 - Smart union mode correctly discriminates between union members based on field matches
 """
 
+import warnings
+
 import pytest
 from typing import Union, Literal, Optional
 from pydantic import BaseModel, ValidationError, TypeAdapter, ConfigDict
 from .common_helpers import record_test
 
-from openapi import SDK
+from openapi import SDK, utils
 from openapi.models import shared, operations
 from openapi.types import UnrecognizedStr, UnrecognizedInt
 
@@ -1368,3 +1370,30 @@ def test_unions_discriminated_open_enum(self):
         assert res.res is not None
         assert isinstance(res.res.json_, shared.ObjectWithOpenEnumStatus2)
         assert res.res.json_.reason == "User requested deactivation"
+
+
+class TestOpenEnumScalarUnionSerialization:
+    @pytest.mark.parametrize("payload, wire", [
+        ({"stringOrNumber": 1.5}, '{"stringOrNumber":1.5}'),
+        ({"stringOrNumber": "future"}, '{"stringOrNumber":"future"}'),
+        ({"stringOrNumber": "known"}, '{"stringOrNumber":"known"}'),
+        ({"stringOrBoolean": True}, '{"stringOrBoolean":true}'),
+        ({"stringOrBoolean": "future"}, '{"stringOrBoolean":"future"}'),
+        ({"integerOrNumber": 2.5}, '{"integerOrNumber":2.5}'),
+        ({"integerOrNumber": 1}, '{"integerOrNumber":1}'),
+        ({"stringOrNull": "future"}, '{"stringOrNull":"future"}'),
+        ({"stringOrNull": "known"}, '{"stringOrNull":"known"}'),
+    ])
+    def test_scalar_member_serialization(self, payload, wire):
+        model = shared.OpenEnumScalarUnions.model_validate(payload)
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            assert utils.marshal_json(model, shared.OpenEnumScalarUnions) == wire
+            assert model.model_dump_json(by_alias=True, exclude_none=True) == wire
+            assert model.model_dump(by_alias=True, exclude_none=True) == payload
+
+    def test_unrecognized_values_keep_their_type_in_python_mode(self):
+        model = shared.OpenEnumScalarUnions.model_validate({"stringOrNumber": "future", "stringOrBoolean": "future"})
+        dumped = model.model_dump(by_alias=True, exclude_none=True)
+        assert type(dumped["stringOrNumber"]) is UnrecognizedStr
+        assert type(dumped["stringOrBoolean"]) is UnrecognizedStr

tests/specs/fragments/primary/open-enum-scalar-unions.yaml

@@ -0,0 +1,43 @@
+openapi: 3.1.0
+security:
+  - apiKeyAuth: []
+  - oauth2: []
+  - clientCredentials: [read, write]
+  - customSchemeAppId: []
+  - basicHttp: []
+  - accessToken: []
+  - {}
+components:
+  schemas:
+    OpenEnumScalarUnions:
+      x-speakeasy-include: true
+      type: object
+      description: >-
+        Properties whose type combines an open enum with a number, a boolean or
+        null. An unrecognized enum value must serialize as its plain string or
+        integer, and a number or boolean must keep its value and JSON type.
+      properties:
+        stringOrNumber:
+          anyOf:
+            - $ref: '#/components/schemas/OpenEnumScalarString'
+            - type: number
+        stringOrBoolean:
+          anyOf:
+            - $ref: '#/components/schemas/OpenEnumScalarString'
+            - type: boolean
+        integerOrNumber:
+          anyOf:
+            - $ref: '#/components/schemas/OpenEnumScalarInteger'
+            - type: number
+        stringOrNull:
+          anyOf:
+            - $ref: '#/components/schemas/OpenEnumScalarString'
+            - type: 'null'
+    OpenEnumScalarString:
+      type: string
+      enum: [known]
+      x-speakeasy-unknown-values: allow
+    OpenEnumScalarInteger:
+      type: integer
+      enum: [1, 2]
+      x-speakeasy-unknown-values: allow

zSDKs/sdk-pythonv2/.speakeasy/gen.lock

@@ -2,8 +2,8 @@
 
 from pydantic import ConfigDict, model_serializer
 from pydantic import BaseModel as PydanticBaseModel
-from pydantic_core import core_schema
-from typing import TYPE_CHECKING, Any, Literal, Optional, TypeVar, Union
+from pydantic_core import PydanticSerializationUnexpectedValue, core_schema
+from typing import TYPE_CHECKING, Any, Literal, Optional, Type, TypeVar, Union
 from typing_extensions import TypeAliasType, TypeAlias
 
 
@@ -37,6 +37,18 @@ def __bool__(self) -> Literal[False]:
     )
 
 
+def _unrecognized_serialization(cls: Type[Union[str, int]]) -> core_schema.PlainSerializerFunctionSerSchema:
+    def serialize(value: Any, info: core_schema.SerializationInfo) -> Any:
+        # Decline other values so union serialization tries the remaining members
+        if not isinstance(value, cls):
+            raise PydanticSerializationUnexpectedValue(f"Expected {cls.__name__}")
+        if not info.mode_is_json():
+            return value
+        return str(value) if isinstance(value, str) else int(value)
+
+    return core_schema.plain_serializer_function_ser_schema(serialize, info_arg=True)
+
+
 class UnrecognizedStr(str):
     @classmethod
     def __get_pydantic_core_schema__(cls, _source_type: Any, _handler: Any) -> core_schema.CoreSchema:
@@ -56,6 +68,7 @@ def validate_lax(v: Any) -> 'UnrecognizedStr':
                 core_schema.no_info_plain_validator_function(validate_lax)
             ]),
             strict_schema=core_schema.none_schema(),  # Always fails in strict mode
+            serialization=_unrecognized_serialization(cls),
         )
 
 
@@ -74,4 +87,5 @@ def validate_lax(v: Any) -> 'UnrecognizedInt':
                 core_schema.no_info_plain_validator_function(validate_lax)
             ]),
             strict_schema=core_schema.none_schema(),  # Always fails in strict mode
+            serialization=_unrecognized_serialization(cls),
         )