Claude API怎么输出固定JSON？Schema、缺失字段与拒绝截断处理

让Claude从文字提取工单内容，普通提示“返回JSON”可能仍夹带解释或遗漏字段。Structured outputs可用Schema约束输出形状，适合交给程序处理。本文使用一条虚构工单，提取问题和截止日期，并检查拒绝、截断与事实依据；它不等于模型能从不存在的信息中恢复真实日期。

第一步：定义字段及未知值

先明确消费者需要哪些字段、类型和缺失表示。本例issue是字符串，deadline允许字符串或null；用户没有提供期限就写null，不把“尽快”推成某个日期。不要为了格式统一先编一个默认时间，再把它误传到日历或任务系统。

schema = {
    "type":"object",
    "properties": {
        "issue":{"type":"string"},
        "deadline":{"type":["string","null"]}
    },
    "required":["issue","deadline"],
    "additionalProperties":False
}

Schema应尽量简单，当前支持的JSON Schema有范围限制，不能照搬所有复杂约束。SDK辅助解析可转换部分不支持条件并在本地校验，但原始Schema与最终发送约束不一定完全相同。先用最小字段跑通，再增加业务校验。

第二步：通过正确参数发送

import json, anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5", max_tokens=512,
    messages=[{"role":"user","content":
        "提取练习工单：导出按钮点击无反应，需要检查；没有提供截止日期。缺少信息用null，不推算。"}],
    output_config={"format":{"type":"json_schema","schema":schema}},
)

将上一步schema定义放在调用前，客户端使用已有环境认证，不写入真实密钥。当前官方参数是output_config.format，示例模型需按账号可用性核对。本文只验证代码语法，没有发出付费请求，也没有真实工单被提交。

JSON输出约束回答格式，strict工具调用约束工具名称与参数，是两个不同功能。本例不需要工具，因此不增加任何会修改外部系统的函数。不要把能返回JSON的调用当成已经完成了创建工单或安排截止日。

第三步：先检查结束原因，再解析

if response.stop_reason != "end_turn":
    raise RuntimeError("Review completion status: " + str(response.stop_reason))
text = "".join(b.text for b in response.content if b.type == "text")
data = json.loads(text)
if set(data) != {"issue", "deadline"}:
    raise ValueError("Unexpected fields")
if not isinstance(data["issue"], str):
    raise ValueError("issue must be text")
if data["deadline"] is not None and not isinstance(data["deadline"], str):
    raise ValueError("deadline must be text or null")

拒绝可能仍返回HTTP 200且内容不符合Schema，stop_reason为refusal；max_tokens表示可能截断。不能看见200就直接发布或解析半份结果。保留失败类型，依据原因处理，不用无限重试制造重复费用。正常结束也仍需要解析与校验。

第四步：核对业务事实与允许值

检查issue是否确实来自练习文字，deadline应为null。结构正确不保证事实准确；若模型生成一条看起来合理的日期，应该按缺失信息处理，而不是因为类型是string就接受。真正的日期还需校验格式、时区与日历有效性。

若以后添加enum分类，当前官方提示字符串枚举大小写可能有差异，应用应采用明确规范化策略，避免只靠大小写区分两个不同类别。金额、数量等字段还需独立业务验证，不能用格式约束代替来源核对。

第五步：维护Schema与异常流程

修改字段结构后为下游消费者更新版本，先用正常材料、缺失字段和无关输入测试。初次Schema有编译开销，不把首次请求速度直接当长期表现。输出格式会影响相关缓存行为，别承诺新格式完全不增加Token或处理成本。

需要文档citations时不能在同一请求与此格式组合，按官方兼容性选择单独流程。完成标准是结束状态、语法、字段和事实依据四项均通过；未通过的记录留待处理，不静默改成一个看似完整的业务对象。

若采用官方SDK辅助接口，可用client.messages.parse和Pydantic类型取得parsed_output；这与本例原始JSON解析路径不同，不要把两套参数混用。日期能通过格式校验，也不代表它在原文中存在，仍须保留缺失信息的业务检查。下游保存时记录本次请求状态与Schema版本，防止旧结果在新调用失败后被误当成功。

官方资料

资料核对日期：2026年11月9日。

• Anthropic：Structured outputs