feat(python): add forward-compatible model serialization

.changesets/1792668682-0165685a.yaml

@@ -0,0 +1,10 @@
+id: 1792668682-0165685a
+features:
+    - core
+targets:
+    - pythonv2
+type: feat
+bump: patch
+description: add opt-in model serialization helpers and unknown-field preservation; fix open enum JSON serialization
+author: ThomasRooney
+date: "2026-10-22"

internal/features/tests.go

@@ -781,6 +781,7 @@ const (
 	TestJsonlStreamTimeoutStillBoundsSlowStream
 	TestJsonlStreamWithTimeoutStreamsToCompletion
 	TestSharedEnumConstructorDefault
+	TestUnknownFieldsJsonRoundTrip
 )
 
 func GetAllTests() []Test {

templates/perms.go

@@ -1543,6 +1543,7 @@ var fileMode = map[string]fs.FileMode{
 	"templates/pythonv2/auxiliary/tests/conftest.py.stmpl":                                                         0o644,
 	"templates/pythonv2/auxiliary/tests/helpers.py.stmpl":                                                          0o644,
 	"templates/pythonv2/auxiliary/tests/test_client.py.stmpl":                                                      0o644,
+	"templates/pythonv2/auxiliary/tests/unknown_fields.py.stmpl":                                                   0o644,
 	"templates/pythonv2/auxiliary/{{getSourcePath}}":                                                               0o20000000755,
 	"templates/pythonv2/auxiliary/{{getSourcePath}}/__init__.py.stmpl":                                             0o644,
 	"templates/pythonv2/auxiliary/{{getSourcePath}}/_version.py.stmpl":                                             0o644,
@@ -1552,7 +1553,7 @@ var fileMode = map[string]fs.FileMode{
 	"templates/pythonv2/auxiliary/{{getSourcePath}}/types":                                                         0o20000000755,
 	"templates/pythonv2/auxiliary/{{getSourcePath}}/types/__init__.py":                                             0o644,
 	"templates/pythonv2/auxiliary/{{getSourcePath}}/types/base64fileinput.py":                                      0o644,
-	"templates/pythonv2/auxiliary/{{getSourcePath}}/types/basemodel.py":                                            0o644,
+	"templates/pythonv2/auxiliary/{{getSourcePath}}/types/basemodel.py.stmpl":                                      0o644,
 	"templates/pythonv2/auxiliary/{{getSourcePath}}/utils":                                                         0o20000000755,
 	"templates/pythonv2/auxiliary/{{getSourcePath}}/utils/__init__.py.stmpl":                                       0o644,
 	"templates/pythonv2/auxiliary/{{getSourcePath}}/utils/annotations.py":                                          0o644,
@@ -1668,6 +1669,7 @@ var fileMode = map[string]fs.FileMode{
 	"templates/pythonv2/tests/client-credentials/test_client_credentials_hook.py":                                  0o644,
 	"templates/pythonv2/tests/common":                                                                              0o20000000755,
 	"templates/pythonv2/tests/common/common_helpers.py":                                                            0o644,
+	"templates/pythonv2/tests/common/unknown_fields_cases.py":                                                      0o644,
 	"templates/pythonv2/tests/custom-http":                                                                         0o20000000755,
 	"templates/pythonv2/tests/custom-http/test_auth_additional.py":                                                 0o644,
 	"templates/pythonv2/tests/oauth2-password":                                                                     0o20000000755,
@@ -1702,6 +1704,7 @@ var fileMode = map[string]fs.FileMode{
 	"templates/pythonv2/tests/primary/test_telemetry.py.stmpl":                                                     0o644,
 	"templates/pythonv2/tests/primary/test_timeout_additional.py":                                                  0o644,
 	"templates/pythonv2/tests/primary/test_unions_additional.py":                                                   0o644,
+	"templates/pythonv2/tests/primary/test_unknown_fields_additional.py":                                           0o644,
 	"templates/pythonv2/tests/primary/test_validation_errors.py":                                                   0o644,
 	"templates/pythonv2/tests/primary/test_x_ndjson_additional.py":                                                 0o644,
 	"templates/pythonv2/tests/quaternary":                                                                          0o20000000755,
@@ -1711,6 +1714,7 @@ var fileMode = map[string]fs.FileMode{
 	"templates/pythonv2/tests/quaternary/test_globals_additional.py":                                               0o644,
 	"templates/pythonv2/tests/quaternary/test_jsonl_streaming_additional.py":                                       0o644,
 	"templates/pythonv2/tests/quaternary/test_servers.py":                                                          0o644,
+	"templates/pythonv2/tests/quaternary/test_unknown_fields_additional.py":                                        0o644,
 	"templates/pythonv2/tests/quaternary/test_validation_errors.py":                                                0o644,
 	"templates/pythonv2/tests/secondary":                                                                           0o20000000755,
 	"templates/pythonv2/tests/secondary/test_auth_additional.py":                                                   0o644,
@@ -1725,13 +1729,15 @@ var fileMode = map[string]fs.FileMode{
 	"templates/pythonv2/tests/secondary/test_pagination.py":                                                        0o644,
 	"templates/pythonv2/tests/secondary/test_redirects_additional.py":                                              0o644,
 	"templates/pythonv2/tests/secondary/test_servers.py":                                                           0o644,
+	"templates/pythonv2/tests/secondary/test_unknown_fields_additional.py":                                         0o644,
 	"templates/pythonv2/tests/security-options":                                                                    0o20000000755,
 	"templates/pythonv2/tests/security-options/test_auth_additional.py":                                            0o644,
 	"templates/pythonv2/tests/tertiary":                                                                            0o20000000755,
 	"templates/pythonv2/tests/tertiary/test_auth_additional.py":                                                    0o644,
 	"templates/pythonv2/tests/tertiary/test_body_typeddict_suffix.py":                                              0o644,
 	"templates/pythonv2/tests/tertiary/test_relative_imports.py":                                                   0o644,
 	"templates/pythonv2/tests/tertiary/test_servers.py":                                                            0o644,
+	"templates/pythonv2/tests/tertiary/test_unknown_fields_additional.py":                                          0o644,
 	"templates/pythonv2/testusage":                                                                                 0o20000000755,
 	"templates/pythonv2/testusage/pylintrc":                                                                        0o644,
 	"templates/pythonv2/testusage/pyproject.toml.stmpl":                                                            0o644,

templates/templates/cli/features.ts

@@ -359,6 +359,7 @@ function isTestSkipped(test: string): boolean {
     "parameters-path-parameter-formats",
     "shared-enum-constructor-default",
     "open-union-invalid-json-is-an-error",
+    "unknown-fields-json-round-trip",
   ].includes(test);
 }
 

templates/templates/csharp/features.ts

@@ -430,6 +430,7 @@ function isTestSkipped(test: string): boolean {
     "event-stream-absent-required-union",
     "event-stream-equivalent-number-lexemes",
     "event-stream-null-and-undeclared-fields",
+    "unknown-fields-json-round-trip",
   ].includes(test);
 }
 

templates/templates/go/features.ts

@@ -427,6 +427,7 @@ function isTestSkipped(test: string): boolean {
     "event-stream-absent-required-union",
     "event-stream-equivalent-number-lexemes",
     "event-stream-null-and-undeclared-fields",
+    "unknown-fields-json-round-trip",
   ].includes(test);
 }
 

templates/templates/javav2/features.ts

@@ -478,6 +478,7 @@ function isTestSkipped(test: string): boolean {
     "event-stream-absent-required-union",
     "event-stream-equivalent-number-lexemes",
     "event-stream-null-and-undeclared-fields",
+    "unknown-fields-json-round-trip",
   ].includes(test);
 }
 

templates/templates/mcp-typescript/features.ts

@@ -687,6 +687,7 @@ function isTestSkipped(test: string): boolean {
     "event-stream-absent-required-union",
     "event-stream-equivalent-number-lexemes",
     "event-stream-null-and-undeclared-fields",
+    "unknown-fields-json-round-trip",
   ].includes(test);
 }
 

templates/templates/php/features.ts

@@ -572,6 +572,7 @@ function isTestSkipped(test: string): boolean {
     "event-stream-absent-required-union",
     "event-stream-equivalent-number-lexemes",
     "event-stream-null-and-undeclared-fields",
+    "unknown-fields-json-round-trip",
   ].includes(test);
 }
 

templates/templates/pythonv2/auxiliary/tests/unknown_fields.py.stmpl

@@ -0,0 +1,31 @@
+{{- if and (sdkHasTests .Global.AST) .Global.Config.PreserveUnknownFields -}}
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def drop_unexpected_fields(actual: Any, expected: Any) -> Any:
+    if isinstance(actual, BaseModel) and type(actual) is type(expected):
+        trimmed = actual.model_copy(
+            update={
+                name: drop_unexpected_fields(getattr(actual, name), getattr(expected, name))
+                for name in type(actual).model_fields
+            }
+        )
+        if actual.__pydantic_extra__ is not None and "__pydantic_extra__" not in type(actual).__annotations__:
+            expected_extra = expected.__pydantic_extra__ or {}
+            trimmed.__pydantic_extra__ = {
+                key: drop_unexpected_fields(value, expected_extra[key])
+                for key, value in actual.__pydantic_extra__.items()
+                if key in expected_extra
+            }
+        return trimmed
+    if isinstance(actual, list) and isinstance(expected, list) and len(actual) == len(expected):
+        return [drop_unexpected_fields(a, e) for a, e in zip(actual, expected)]
+    if isinstance(actual, dict) and isinstance(expected, dict):
+        return {
+            key: drop_unexpected_fields(value, expected[key]) if key in expected else value
+            for key, value in actual.items()
+        }
+    return actual
+{{- end}}

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

@@ -1,17 +1,62 @@
 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
 
 
 class BaseModel(PydanticBaseModel):
     model_config = ConfigDict(
-        populate_by_name=True, arbitrary_types_allowed=True, protected_namespaces=()
+        populate_by_name=True, arbitrary_types_allowed=True, protected_namespaces=(){{if .Global.Config.PreserveUnknownFields}}, extra="allow"{{end}}
     )
 
+{{if .Global.Config.ModelSerializationMethods}}
+    def to_dict(
+        self,
+        *,
+        mode: Literal["json", "python"] = "python",
+        use_api_names: bool = True,
+        exclude_unset: bool = True,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+        warnings: bool = True,
+    ) -> dict[str, Any]:
+        return self.model_dump(
+            mode=mode,
+            by_alias=use_api_names,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+            exclude_none=exclude_none,
+            warnings=warnings,
+            context={SERIALIZATION_METHODS_DUMP: True},
+        )
+
+    def to_json(
+        self,
+        *,
+        indent: Optional[int] = 2,
+        use_api_names: bool = True,
+        exclude_unset: bool = True,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+        warnings: bool = True,
+    ) -> str:
+        return self.model_dump_json(
+            indent=indent,
+            by_alias=use_api_names,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+            exclude_none=exclude_none,
+            warnings=warnings,
+            context={SERIALIZATION_METHODS_DUMP: True},
+        )
+
+{{end}}
 
 class Unset(BaseModel):
+{{- if .Global.Config.PreserveUnknownFields}}
+    model_config = ConfigDict(extra="ignore")
+{{end}}
     @model_serializer(mode="plain")
     def serialize_model(self):
         return UNSET_SENTINEL
@@ -22,6 +67,9 @@ def __bool__(self) -> Literal[False]:
 
 UNSET = Unset()
 UNSET_SENTINEL = "~?~unset~?~sentinel~?~"
+{{- if .Global.Config.ModelSerializationMethods}}
+SERIALIZATION_METHODS_DUMP = "speakeasy_serialization_methods_dump"
+{{- end}}
 
 
 T = TypeVar("T")
@@ -35,6 +83,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 info.mode == "python":
+            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 +114,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 +133,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/auxiliary/{{getSourcePath}}/utils/serializers.py.stmpl

@@ -278,7 +278,7 @@ def marshal_json(val, typ):
 
     m = marshaller(body=val)
 
-    d = m.model_dump(by_alias=True, mode="json", exclude_none=True)
+    d = m.model_dump(by_alias=True, mode="json", exclude_none={{if .Global.Config.PreserveUnknownFields}}getattr(m, "body") is None{{else}}True{{end}})
 
     if len(d) == 0:
         return ""

templates/templates/pythonv2/config.ts

@@ -325,6 +325,24 @@ function getConfigFields(
       ValidationRegex: /^(true|false)$/.source,
       ValidationMessage: "true or false only",
     },
+    modelSerializationMethods: {
+      Name: "modelSerializationMethods",
+      Required: false,
+      DefaultValue: false,
+      Description:
+        "Add to_dict and to_json convenience methods to models, using API field names and excluding unset fields by default.",
+      ValidationRegex: /^(true|false)$/.source,
+      ValidationMessage: "true or false only",
+    },
+    preserveUnknownFields: {
+      Name: "preserveUnknownFields",
+      Required: false,
+      DefaultValue: false,
+      Description:
+        "Preserve undeclared fields in JSON request and response models, including nested models and schemas with additionalProperties: false. Explicitly typed additional properties retain their validation. Flattened operation arguments accept only declared fields, so undeclared top-level request fields require flattenRequests: false; nested models passed as arguments keep theirs. Disabled by default.",
+      ValidationRegex: /^(true|false)$/.source,
+      ValidationMessage: "true or false only",
+    },
     responseSchemaValidation: {
       Name: "responseSchemaValidation",
       Required: false,

templates/templates/pythonv2/includes/sanitization.ts

@@ -257,12 +257,12 @@ function sanitizeSDKAccess(sdk: SDK): string {
   let formattedName = "";
   if (group.includes(".") && ".".repeat(group.length) !== group) {
     const pieces = group.split(".");
-    formattedName = sanitizeFieldName(pieces[0]);
+    formattedName = sanitizeSubSDKFieldName(pieces[0]);
     for (const i of pieces.slice(1)) {
-      formattedName += "." + sanitizeFieldName(i);
+      formattedName += "." + sanitizeSubSDKFieldName(i);
     }
   } else {
-    formattedName = sanitizeFieldName(group);
+    formattedName = sanitizeSubSDKFieldName(group);
   }
 
   if (formattedName != "") {
@@ -311,6 +311,20 @@ registerTemplateFunc("sanitizeSDKFileName", sanitizeSDKFileName);
 
 // @ts-ignore
 function sanitizeFieldName(name: string): string {
+  name = sanitizeAttributeName(name);
+
+  if (
+    context.Global.Config.ModelSerializationMethods &&
+    ["to_dict", "to_json"].includes(name)
+  ) {
+    name += "_";
+  }
+
+  return name;
+}
+registerTemplateFunc("sanitizeFieldName", sanitizeFieldName);
+
+function sanitizeAttributeName(name: string): string {
   name = sanitizeName(name);
   if (name.endsWith("_")) {
     name = name.substring(0, name.length - 1);
@@ -326,7 +340,6 @@ function sanitizeFieldName(name: string): string {
 
   return name;
 }
-registerTemplateFunc("sanitizeFieldName", sanitizeFieldName);
 
 function useConflictResistantModelImports(): boolean {
   return !!context.Global.Config.FixFlags?.[
@@ -413,9 +426,7 @@ function doesModuleNameConflictAcrossNamespaces(
 
 // @ts-ignore
 function sanitizeSubSDKFieldName(name: string): string {
-  name = sanitizeFieldName(name);
-
-  return name;
+  return sanitizeAttributeName(name);
 }
 registerTemplateFunc("sanitizeSubSDKFieldName", sanitizeSubSDKFieldName);