[2ynn]

Why

Pydantic drops fields a model does not declare. Python SDKs therefore lose undeclared fields in nested JSON request and response bodies: they are not sent to the API, and they disappear from response models, so a response cannot be sent back unchanged.

What changed

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;
• each model serializer reads every declared field from the key Pydantic emitted (alias or field name, including the alias-keyed output a nested model is serialized from again) and removes it, then copies the remaining keys, the unknown fields, back into the output. serialize_with_info exposes the dump's by_alias option next to exclude_none (current_by_alias), so serialize_model(self, handler) keeps its two-argument signature. With the option disabled the serializer reads fields as before;
• marshal_json keeps nested nulls and excludes only a top-level None; optional fields left unset are still omitted;
• UNSET ignores extra fields;
• generated test assertions compare only the fields their examples declare, through a drop_unexpected_fields test helper, because mock responses can carry more. Declared additional properties keep their exact key set, and their values are compared the same way.

Known limitations

• When a payload contains both a field's API name and an undeclared key equal to its Python name (displayName and display_name), API-name dumps (model_dump(by_alias=True), the request body) keep both keys, but Python-name dumps (the default model_dump()) show the undeclared value in place of the declared one. Plain Pydantic behaves the same with extra="allow" and populate_by_name=True.
• Additional properties assigned under a key the model already emits replace the declared value in the output.
• Flattened operation arguments accept only declared fields, so undeclared top-level request fields need flattenRequests: false; nested objects keep theirs. The option description states this.
• Unknown fields are carried in JSON bodies only; form, multipart, query and header serialization use declared fields.
• As in fix(python): honour include/exclude filters in model dumps #149, a dump that combines exclude_none=True with include, exclude, exclude_unset or exclude_defaults can still write excluded required fields back as None.

types/basemodel.py becomes a template (basemodel.py.stmpl) that skips formatting, so SDKs with the option disabled keep the same file. The review SDK gains only preserveUnknownFields: false in gen.yaml.

Test coverage

• New unknown-fields uber fragment: an echo operation whose body nests objects, arrays, maps, discriminated and plain unions, allOf, open/typed/closed additional properties (including additional properties typed as an object schema), empty objects, open enums and nullable fields, plus a flattened variant and an error response.
• New test ID unknown-fields-json-round-trip, skipped for other targets. The tertiary TypeScript overlay removes the echo operation because its inline success and error bodies get the same generated name in that configuration.
• primary (option disabled): unknown fields are still dropped.
• secondary (enabled, flattenRequests: false): request/response round trips for dicts and models, response-only and error-body extras, dump filters, typed additional-properties validation, top-level None handling.
• quaternary (enabled, flattenRequests: true): nested unknown fields through flattened arguments, sync and async; drop_unexpected_fields ignores unknown fields inside typed additional-property values but still reports extra map entries and changed values.

Stack

1. fix(python): serialize unrecognized open enum values #145: unrecognized enum serialization (merged)
2. fix(python): honour include/exclude filters in model dumps #149: honour include/exclude filters in model dumps (merged)
3. This PR: preserveUnknownFields
4. feat(python): add modelSerializationMethods option #147: modelSerializationMethods

Testing

• TARGET=primary make test-pythonv2 (option disabled): 728 passed.
• TARGET=secondary make test-pythonv2: 330 passed, 1 skipped.
• TARGET=quaternary make test-pythonv2: 257 passed, 1 skipped. The typed additional-properties helper test fails with the previous drop_unexpected_fields.
• TARGET=review make build-pythonv2: integrity validation passes.
• Python model serializer snapshot tests pass unchanged.
• prettier, make check-template-pythonv2 and make lint pass.
• git diff --check passes.
• TARGET=tertiary make test-pythonv2 (option disabled): 214 passed, 1 skipped.

Public-safety check

• This change contains no credentials, customer documents, private repository URLs, private filesystem paths, or unredacted private logs.
• Title, body, comments, and commit messages name no customers or customer-derived identifiers, private paths or trackers, or workflow provenance, and are understandable without private context (.claude/skills/public-repo-communication/SKILL.md).
• Generated fixtures and review SDK changes are public-safe.
• I reviewed git diff --check.

[cubic-dev-ai]

All reported issues were addressed across 31 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[speakeasy-generator-bot]

Generator Snapshot Testing

Snapshot tests are running.

Snapshot results: https://github.com/speakeasy-api/openapi-generation-snapshots/issues/135#issuecomment-6451260182

[TristanSpeakEasy]

Looks good, keeping this opt-in and retaining validation for typed additional properties makes sense.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}