来源:
data/reference/json/ccb_json_object_types.json
tools/json_api/contract-inventory.schema.json
tools/json_api/generate_contracts.py
tools/json_api/test_generate_contracts.py
src/init.cpp
src/generic_factory.h
tests/json_load_test.cpp
doc/JSON/JSON_INHERITANCE.md
doc/JSON/JSON_STYLE.md
commit c663ceb2c1bd
api-contract
JSON 验证与证据等级¶
不同检查证明不同事实。不要把“能解析”报告成“能完整加载”，也不要把词法出现次数当作 字段必填性的证据。
推荐顺序¶
- 运行仓库 JSON formatter，确认格式符合项目输出。
- 重新生成契约清单并执行 Schema、计数、源码位置和示例指针测试。
- 运行
json-check。当前chkjson检查data/json中对象/数组语法以及顶层字符串type；它不是所有 loader 的完整语义加载器。 - 构建测试程序。测试启动会加载 core/测试数据；再运行目标类型的 Catch2 测试。
- 对外部 Mod，在真实 CCB 可执行文件中创建测试世界并加载该 Mod；记录版本、依赖和日志。
在 CCB 主仓库运行：
# validation: json-contract
python3 tools/json_api/generate_contracts.py --check
python3 -m unittest discover -s tools/json_api -p 'test_*.py'
# validation: json-load
make -j2 json-check
证据等级¶
| 标记 | 能证明什么 | 不能证明什么 |
|---|---|---|
mandatory / optional |
loader 中有明确字段读取证据 | 所有条件分支和跨字段约束 |
partial |
已分类一部分契约 | 未列出的字段安全或可省略 |
unclassified |
尚无可发布的源码分类 | 字段不存在 |
lexical_only |
数据或旧文档中有同名文本 | 最小示例有效、字段必填、语义相同 |
schema: none |
没有通用 validator-backed Schema | loader 不会验证 |
生成器只读取 git ls-files 返回的 tracked 路径，并固定 190/275/306 的覆盖计数。计数变化
必须伴随注册/解析器变化和生成 diff；不得手改生成清单或生成参考页。