三个 schema 特性控制模型能输出什么:required 控制哪些字段必须出现,nullable 类型控制字段能否为 null,enum 把值限制在固定集合内。用对了它们能防止编造、确保数据干净。
required:控制是否出现
对象级别的 required 数组列出必须出现的字段名。在 properties 里但不在 required 里的就是可选的——可能出现也可能不出现。
属性默认可选。没有单个属性上的 optional: true 标记,没有单独的 optional 数组。可选性完全由 required 数组决定。
Nullable:显式表达”不可用”
可空字段用联合类型:"type": ["string", "null"]。意思是这个字段可以是 string 或者 null。它给模型一个合法的方式说”这个信息不存在”,而不用编造一个值。
标准 JSON Schema 里没有 nullable: true 关键字(那是 OpenAPI 的,不是 JSON Schema 的)。没有 "type": "string?" 简写。联合数组 ["string", "null"] 才是正确语法。
required vs nullable:两回事
- 非 required = 字段可以不存在(输出里没有这个 key)
- Nullable = 字段存在但值为 null
{}(字段不在)和 {"field": null}(字段在,值是 null)是不同的。对于提取任务,nullable + 非 required 提供了最大灵活性:模型可以包含字段并给数据、包含字段并给 null、或者整个省略。
反模式:把可能不存在的字段设为 required 且类型为 string。模型被迫产出某个字符串——于是它编造。改用 nullable:"type": ["string", "null"],不放进 required。这样信息确实不存在时模型返回 null。
enum:限制取值
enum 把字段约束到固定值集合:"enum": ["invoice", "contract", "receipt"]。只有这些精确值是合法的。
和直觉相反,JSON Schema 的 enum 可以包含混合类型——["low", 1, "high", null] 是合法的。但 enum 加上 type 会同时约束两者:"type": "string", "enum": ["active", "inactive"] 确保只接受这两个字符串。
一个实用模式:给 enum 加一个 "other" 逃生出口(["invoice", "contract", "receipt", "other"]),配一个 detail 字段。这样遇到意外类别时不用把它硬塞进最接近但不对的类别里。
一句话总结: required 控制字段是否出现(默认可选),nullable ["type", "null"] 防止因缺失数据而编造,enum 加 “other” 逃生出口优雅地处理意外类别。