如何在Pydantic中定义仅接受空字符串或指定Dict结构的模型字段

要实现dataStores字段仅接受「空字符串」或「符合结构的DataStoreDict字典」两种值，核心是限制联合类型中字符串分支的取值范围，不能直接使用宽泛的str类型。

最简实现（Pydantic V1/V2 通用） #

用Literal['']替代联合类型中的str，该类型会强制约束字符串取值只能是空串，其余任意字符串都会直接触发校验失败：

from typing import List, Union, Literal
from pydantic import BaseModel

class DataStoreInBulk(BaseModel):
    name: str
    href: str

class DataStoreDict(BaseModel):
    dataStore: List[DataStoreInBulk] 

class DataStoresModel(BaseModel):
    dataStores: Union[DataStoreDict, Literal['']] = ''

校验规则说明 #

• 传入{"dataStores": ""}：校验通过，字段值为空字符串
• 传入符合DataStoreDict结构的字典：校验通过，自动解析为对应模型实例
• 传入非空字符串（比如"sf"、"test"等）：校验不通过，抛出值不匹配的错误

自定义校验实现（支持扩展逻辑） #

如果后续需要给字段加额外校验规则，可以用对应版本的字段校验器实现：

Pydantic V2 写法 #

from typing import List, Union
from pydantic import BaseModel, field_validator

class DataStoreInBulk(BaseModel):
    name: str
    href: str

class DataStoreDict(BaseModel):
    dataStore: List[DataStoreInBulk] 

class DataStoresModel(BaseModel):
    dataStores: Union[DataStoreDict, str] = ''

    @field_validator('dataStores')
    @classmethod
    def check_datastores_value(cls, value):
        if isinstance(value, str) and value != "":
            raise ValueError("dataStores为字符串时仅允许取值为空字符串")
        return value

Pydantic V1 写法 #

from typing import List, Union
from pydantic import BaseModel, validator

class DataStoreInBulk(BaseModel):
    name: str
    href: str

class DataStoreDict(BaseModel):
    dataStore: List[DataStoreInBulk] 

class DataStoresModel(BaseModel):
    dataStores: Union[DataStoreDict, str] = ''

    @validator('dataStores')
    def check_datastores_value(cls, value):
        if isinstance(value, str) and value != "":
            raise ValueError("dataStores为字符串时仅允许取值为空字符串")
        return value

注意：定义联合类型时，要把结构化模型类型DataStoreDict放在前面，字面量/字符串类型放在后面，避免Pydantic类型匹配顺序导致的校验异常。

内容的提问来源于stack exchange，提问作者krishna lodha