feat(python): add preserveUnknownFields option

Pydantic drops fields a model does not declare, so undeclared fields in
nested JSON request and response bodies were lost on validation and on
serialization back to the API.

Add python.preserveUnknownFields (default false). When enabled:

- generated models and error bodies allow extra fields, including
  schemas with additionalProperties: false; explicitly typed additional
  properties still validate
- model serializers read each declared field from the key Pydantic
  emitted and copy the remaining keys back out
- marshal_json keeps nested nulls and only excludes a top-level None
- UNSET ignores extra fields
- generated test assertions compare only the fields their examples
  declare, since mock responses can carry more

basemodel.py becomes a template, so the review SDK copy now passes
through the Python formatter.

The option is covered by an echo fragment exercised in the primary
(disabled), secondary and quaternary variants.

Author: 2ynn

.changesets/1792768307-aaecd177.yaml

@@ -0,0 +1,10 @@
+id: 1792768307-aaecd177
+features:
+    - core
+targets:
+    - pythonv2
+type: feat
+bump: patch
+description: add preserveUnknownFields to keep undeclared fields in JSON request and response models
+author: 2ynn
+date: "2026-10-23"

internal/features/tests.go

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

internal/features/tests_generated.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,6 +1729,7 @@ 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/perms.go

@@ -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/cli/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/csharp/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/go/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/javav2/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/mcp-typescript/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);
 }