如何用MyPy/Pydantic实现JSON:API 1.1多可选字段至少必填其一？

Python的静态类型系统（如typing或pydantic）没法完全通过类型定义实现你要的所有约束，但可以结合类型提示+自定义验证来满足JSON:API规范要求。

一、为什么单纯联合类型无效？ #

你尝试的Data|Errors|Meta|ExtensionMember联合类型只能表示顶层属于这几种类型之一，但无法处理两个核心约束：

• 无法强制至少包含一个指定成员（Python类型系统不支持“非空集合”类的约束）
• 无法禁止data与errors同时存在（联合类型仅关注类型归属，不做互斥校验）

二、用类型系统+运行时验证实现规范（以Pydantic为例） #

如果用Pydantic（Python主流类型验证库），可以通过可选字段+自定义验证器的组合，精准满足规范要求：

from pydantic import BaseModel, Field, field_validator
from typing import Optional, Dict, Any

# 先定义基础类型（示例结构，可根据实际需求调整）
class Data(BaseModel):
    id: str
    type: str

class Errors(BaseModel):
    detail: str

class Meta(BaseModel):
    timestamp: str

class JsonApiDocument(BaseModel):
    data: Optional[Data] = None
    errors: Optional[Errors] = None
    meta: Optional[Meta] = None
    # 扩展成员用字典承载，支持任意自定义字段
    extra: Dict[str, Any] = Field(default_factory=dict)

    @field_validator('data', 'errors')
    def check_mutually_exclusive(cls, value, values):
        # 校验data和errors不能同时存在
        opposite_field = 'errors' if cls.field_name == 'data' else 'data'
        if value is not None and values.get(opposite_field) is not None:
            raise ValueError("data与errors字段不能同时存在")
        return value

    @field_validator('data', 'errors', 'meta', 'extra', check_fields=False)
    def check_at_least_one_member(cls, _, values):
        # 校验至少存在一个必填成员
        has_valid_member = any([
            values.get('data') is not None,
            values.get('errors') is not None,
            values.get('meta') is not None,
            len(values.get('extra', {})) > 0
        ])
        if not has_valid_member:
            raise ValueError("文档顶层必须包含data、errors、meta或扩展成员中的至少一个")
        return _

这个方案的优势：

• 保留类型提示能力，编辑器可识别字段类型
• 用验证器精准实现两个核心约束
• 扩展成员的处理灵活，支持任意自定义顶层字段

三、纯静态类型的冗余方案（不推荐） #

如果只想依赖静态类型检查（无运行时验证），可以定义多个互斥的模型类再做联合：

from typing import Union, Dict, Any

class DataDocument(BaseModel):
    data: Data
    errors: None = None
    meta: Optional[Meta] = None
    extra: Dict[str, Any] = Field(default_factory=dict)

class ErrorsDocument(BaseModel):
    errors: Errors
    data: None = None
    meta: Optional[Meta] = None
    extra: Dict[str, Any] = Field(default_factory=dict)

class MetaOnlyDocument(BaseModel):
    meta: Meta
    data: None = None
    errors: None = None
    extra: Dict[str, Any] = Field(default_factory=dict)

class ExtensionOnlyDocument(BaseModel):
    extra: Dict[str, Any]
    data: None = None
    errors: None = None
    meta: None = None

JsonApiDocument = Union[DataDocument, ErrorsDocument, MetaOnlyDocument, ExtensionOnlyDocument]

但这种方式代码冗余严重，且无法强制扩展成员非空，最终仍需运行时校验，实用性极低。

四、结论 #

Python的类型系统无法仅靠静态定义满足JSON:API的所有顶层约束，类型提示+运行时自定义验证是最合理的方案。用Pydantic的验证器可以简洁高效地实现规范要求，同时保留类型系统的优势。

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