Retain unknown fields
Accept payloads that may contain forward-compatible or vendor-specific keys while preserving those values for later processing.
Pydantic · Pipe
extra
The extra configuration controls how Pydantic handles input keys that are not declared model fields. Choose ignore, forbid, or allow; the default is ignore.
How it works
The extra configuration controls what happens to input keys that are not declared as model fields. Set it through ConfigDict to ignore those keys, reject them with validation errors, or preserve them in __pydantic_extra__.
Syntax
model_config = ConfigDict(extra='ignore' | 'forbid' | 'allow')Parameters
| Name | Type | Description |
|---|---|---|
extra | Literal['ignore', 'forbid', 'allow'] | Controls whether extra input is ignored, accepted, or rejected during model initialization. Supported values are ignore, forbid, and allow; the default is ignore. |
Key points
- The setting applies to input keys that are not declared as model fields.
- Pydantic supports exactly three policies:
ignore,forbid, andallow. ignoreis used when no explicitextrapolicy is supplied.- Ignored keys do not appear in the constructed model.
forbidconverts unknown input into a validation error.allowpreserves unknown values under the model's__pydantic_extra__attribute.
Common mistakes
- If no policy is configured, undeclared input is silently discarded.
- The
forbidpolicy makes unknown keys validation failures rather than merely ignoring them.
Example: Allow extra model data
from pydantic import BaseModel, ConfigDict
class User(BaseModel):
model_config = ConfigDict(extra='allow')
name: str
user = User(name='Ada', role='admin')
assert user.__pydantic_extra__ == {'role': 'admin'}Unknown input is accepted and retained in the model's extra-data dictionary.
When to use it
Reject unexpected data
Enforce a strict input contract at API or configuration boundaries by rejecting unexpected keys.
Ignore incidental fields
Build models that intentionally tolerate evolving payloads without exposing unknown keys as declared fields.
Interview questions
QWhat does the extra configuration control?
extra defines how Pydantic handles input that does not correspond to a declared field. Its supported policies are ignore, forbid, and allow, with ignore as the default.
Follow-up: What happens under allow? Extra values are stored on the instance in __pydantic_extra__.
QWhat is the default behavior for undeclared input?
With extra='ignore', extra input is accepted during initialization but omitted from the resulting model. This is the default behavior.
Follow-up: How would you reject such input? Set model_config = ConfigDict(extra='forbid'), which causes a ValidationError.
QWhat does extra='allow' do?
extra='allow' accepts undeclared input and stores it in the model's __pydantic_extra__ dictionary. Declared fields continue to be handled as normal model fields.
Follow-up: How can a model inspect retained unknown values? Read the instance's __pydantic_extra__ attribute.
Related
BaseModelConfigDictValidationError__pydantic_extra__