如何使用Pydantic生成严格JSON Schema 拦截未知属性校验
Pydantic 拦截未定义属性校验的配置方案
核心默认行为说明
Pydantic 的 BaseModel 默认采用忽略未知字段的策略:当待校验对象包含模型定义范围外的属性时,会自动静默丢弃这些字段,不会触发校验报错。要开启未知字段拦截,仅需调整模型内置的校验配置,无需额外编写自定义校验逻辑。
分版本配置方法
Pydantic v2 版本
v2 版本统一通过 model_config 属性传入 ConfigDict 配置项实现规则调整,对应模型改造代码如下:
from pydantic import BaseModel, ConfigDict from typing import Optional class Query(BaseModel): # 禁止传入模型未定义的额外字段 model_config = ConfigDict(extra="forbid") id: str name: Optional[str]
配置生效后,当待校验对象包含类似 foo: bar 这类未在模型中声明的属性时,会直接抛出 ValidationError,标记额外字段不符合校验规则。同时模型自动生成的JSON Schema也会同步加上 "additionalProperties": false 的约束,保证Schema定义和实际校验逻辑一致。
Pydantic v1 版本
v1 版本通过模型内部嵌套的 Config 类实现规则配置,对应改造代码如下:
from pydantic import BaseModel from typing import Optional class Query(BaseModel): # 禁止传入模型未定义的额外字段 class Config: extra = "forbid" id: str name: Optional[str]
配置项的可选规则说明
extra 配置支持三个固定取值,对应不同的未知字段处理逻辑:
ignore:默认值,静默丢弃所有未知字段,不做报错也不保留allow:保留所有未知字段,将其作为模型实例的普通属性存储forbid:只要出现未知字段,直接判定校验失败
实际校验效果:传入包含未知字段的对象
{"id": "test-id", "name": "test-name", "foo": "bar"}时,会直接触发校验异常,提示Extra inputs are not permitted,不会静默通过校验。
内容的提问来源于stack exchange,提问作者sorin
相关产品推荐
相关产品推荐

