来源:
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 契约总览¶
CCB 的 JSON 契约不是由一份万能 Schema 定义的。运行时加载器和测试决定行为；
DynamicDataLoader 注册决定顶层 type 的分派；Schema、验证器和生成清单记录能够
被机器证明的部分。旧文档和数据样例可以提供线索，但不能覆盖这些契约。
当前机器覆盖¶
- JSON 对象类型注册表索引 190 个唯一注册类型和 191 次注册调用。
- 183 个注册类型在受审计的 6,731 个 tracked JSON 文件中有顶层实例候选。
- 7 个注册类型没有实例候选；清单没有发现“出现但未注册”的顶层字符串类型。
- 190 个类型的通用 Schema 状态都是
none；不得把对象类型清单称为完整 JSON Schema。 - 189 个类型的字段契约仍为
unclassified，effect_on_condition目前为partial。
这些数字描述的是提交
71f403ecea0dcf16be8fe93c661acbe2a4906cc6 的生成清单，不保证任意对象的每个字段、
默认值、继承规则或跨 ID 引用都已分类。
一个对象如何获得意义¶
- JSON 解析器先证明文件语法和根容器可读。
- 顶层对象的字符串
type进入注册分派。 - 对应 loader/factory 读取字段，并在源码中决定 mandatory、optional、默认值和错误。
- factory、finalize/check 阶段以及交叉引用检查可能进一步拒绝对象。
- 运行时测试证明具体行为和兼容性。
因此，“在数据中出现过”只说明存在词法实例；“旧文档提到过”也只是
lexical_only 证据。要确认字段，必须回到注册表指出的 loader、测试和验证器。
从哪里开始¶
- 查询
type是否注册：使用生成注册表。 - 修改继承对象：先阅读继承与 copy-from。
- 提交前检查：遵循JSON 验证与证据等级。
- 编写 EOC：从EOC 契约与生命周期开始。
- 制作可复现样例：使用完整 JSON/EOC Mod 教程。
如果本页与清单、Schema、注册源码或测试冲突，本页应标记 stale 并修复；不要为了匹配 正文而改变运行时契约。