JSON 能被 json.loads 解析,只能说明语法成立,不能说明字段齐全、类型正确、值在业务允许范围内。整理结果少负责人字段、把任务写成数字,甚至把“待确认”填进日期,仍可能混进后续流程。下面用完全虚构的待办样本和本地 Python 演示校验方法;样本为教程编写,不调用模型或网络接口,不代表验证了任何产品能力。
先约定输出契约,再接收结果。示例约定顶层为数组,每一项必须且只能有四个字段:task 为非空字符串,纯空白不算任务;owner 只能是 role_a、role_b 或 null;due 为严格 YYYY-MM-DD 有效日期或 null;status 为 todo、doing、done 之一,不能为 null。字段缺失和值未知是两回事:未知负责人、日期保留字段并填 null,不写字符串形式的 null、空字符串或猜测值;状态不明则退回确认,不替它猜成 todo。空数组在结构上允许,但不能据此证明原文没有待办。可以把契约写进整理要求,例如只返回符合契约的 JSON 数组、不得补造负责人或日期、不确定时用 null、不添加解释或 Markdown 围栏;这只是输出要求,不能代替接收端校验。
检查器 validate.py 使用标准库:先解析 JSON,再检查字段与值;通过 object_pairs_hook 拒绝重复键,避免同名字段被后值覆盖后悄悄通过;错误包含数组位置和字段路径;不自动修补数据,也不执行 JSON 中的文本。代码先检查类型再检查集合成员,数组、布尔值等错误类型不会触发成员检查异常;日期先限定格式,再检查实际日历日期,2026-02-30 不会因长得像日期而通过;JSON 的 null 会被 Python 解析成 None。
- import json
- import re
- import sys
- from datetime import date
- from pathlib import Path
- def unique_object(pairs):
- result = {}
- for key, value in pairs:
- if key in result:
- raise ValueError(f"duplicate key: {key}")
- result[key] = value
- return result
- def validate(data):
- if not isinstance(data, list):
- return ["$: expected array"]
- errors = []
- required = {"task", "owner", "due", "status"}
- owners = {"role_a", "role_b"}
- statuses = {"todo", "doing", "done"}
- for index, item in enumerate(data):
- path = f"$[{index}]"
- if not isinstance(item, dict):
- errors.append(f"{path}: expected object")
- continue
- for key in sorted(required - item.keys()):
- errors.append(f"{path}.{key}: missing")
- for key in sorted(item.keys() - required):
- errors.append(f"{path}.{key}: unexpected field")
- for key in sorted(required & item.keys()):
- value = item[key]
- error = None
- if key == "task":
- if not isinstance(value, str) or not value.strip():
- error = "expected non-empty string"
- elif key == "owner" and value is not None:
- if not isinstance(value, str) or value not in owners:
- error = "expected role_a, role_b or null"
- elif key == "status":
- if not isinstance(value, str) or value not in statuses:
- error = "expected todo, doing or done"
- elif key == "due" and value is not None:
- if not isinstance(value, str) or not re.fullmatch(
- r"[0-9]{4}-[0-9]{2}-[0-9]{2}", value
- ):
- error = "expected YYYY-MM-DD or null"
- else:
- try:
- date.fromisoformat(value)
- except ValueError:
- error = "invalid calendar date"
- if error:
- errors.append(f"{path}.{key}: {error}")
- return errors
- def main():
- if len(sys.argv) != 2:
- print("usage: python validate.py FILE.json", file=sys.stderr)
- return 2
- try:
- text = Path(sys.argv[1]).read_text(encoding="utf-8")
- data = json.loads(text, object_pairs_hook=unique_object)
- errors = validate(data)
- if errors:
- raise ValueError("\n".join(errors))
- except (OSError, UnicodeError, ValueError) as exc:
- print(f"FAIL: {exc}", file=sys.stderr)
- return 1
- print(f"OK: {len(data)} item(s)")
- return 0
- if __name__ == "__main__":
- sys.exit(main())
复制代码
正确样本 valid.json:
- [
- {"task": "整理演示资料目录", "owner": "role_a", "due": "2026-11-20", "status": "todo"},
- {"task": "确认演示图的说明文字", "owner": null, "due": null, "status": "todo"}
- ]
复制代码
故意写错的 invalid.json:
- [
- {"task": "整理演示资料目录", "due": null, "status": "waiting", "priority": 1},
- {"task": 7, "owner": "role_c", "due": "2026-02-30", "status": ["todo"]}
- ]
复制代码
三个文件放在同一目录,在该目录运行:
- python -B validate.py valid.json
- python -B validate.py invalid.json
复制代码
2026年11月17日在本地 Python 3.15.0 环境实际运行,无需安装依赖。第一条命令的标准输出为:
退出码为 0。第二条命令的标准错误输出汇总为以下错误项:
FAIL: $[0].owner: missing
$[0].priority: unexpected field
$[0].status: expected todo, doing or done
$[1].due: invalid calendar date
$[1].owner: expected role_a, role_b or null
$[1].status: expected todo, doing or done
$[1].task: expected non-empty string
退出码为 1,不能把这批数据继续当作校验成功。结构问题一次汇总;语法错误或重复键会在解析阶段直接失败。命令参数数量错误返回 2,文件读取或编码错误同样会明确报告并返回 1,没有用空数组掩盖失败。
通过之后,仍要回查原始材料。这段代码能发现缺少 owner 字段,发现不了原文有三项、结果只整理了两项。负责人即使在允许名单中,也可能分配错;日期合法,也可能不是原文约定的日期。因此把失败数据退回修正,把通过的数据与原始材料逐项核对,再决定是否进入业务流程。未知值也不等于已解决:null 是待确认信息的明确表示,不是自动安排负责人或到期提醒的依据。本例没有实现事实比对、任务去重、权限控制或生产环境的输入大小限制,结构合规只是其中一道检查。 |