You need to enable JavaScript to run this app. 如何使用Pydantic生成严格JSON Schema 拦截未知属性校验
优惠活动
大模型
产品
解决方案
定价
更多

如何使用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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.08 22:15:05