从 JSON 样本与电子表格推导 JSON Schema

目标与适用范围

从代表性的 JSON 样本或 XLSX 行数据生成可审阅的 JSON Schema 草案，再检查类型、必填性、空值和异常值，确认后才用于后续契约工作。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 准备多份有代表性的 JSON 文档，或准备包含表头和样本行的 XLSX 工作簿，不要只提供一条理想记录。

• 先确定根结构、标识符和日期约定、单位，以及空白、未知值和 null 的表示方式。

• 保留异常行和预期边界用例，并指定能审批必填性与可空策略的审阅人。

• 决策点: 证据来自 JSON、XLSX，还是两者都有？. JSON 样本使用 json-schema-generator，工作表表头和行使用 xlsx-sheet-to-json-schema。如果两种来源描述同一载荷，应保留两份草案并明确对照差异，不要静默选择其中一个。

• 决策点: 字段在样本中反复出现，就能证明它必填吗？. 不能。出现频率只能说明观测到的情况，不是业务规则。还要检查可选记录、缺失列、空单元格和生产方约定，再决定是否必填。

• 决策点: 结果是草案，还是已经批准的契约？. 在逐字段检查类型、可空性、枚举候选、约束和异常值，并记录假设之前，只把生成结果当作草案。

按步骤完成工作流

1. 盘点样本证据

把代表性记录与一次性异常分开，记录 JSON 文件或工作表、样本范围，并在推导前保留原始输入。 使用 json-schema-generator, xlsx-sheet-to-json-schema.

2. 从 JSON 样本推导

用多条有意义的样本运行 JSON 分支，并把生成草案、样本集合、观测类型和手动 schema 修改一起保存。 使用 json-schema-generator.

3. 从工作表行推导

利用表头和有代表性的 XLSX 行推导属性名、基础类型、可空行为、枚举候选和基础约束，同时记录空单元格与格式陷阱。 使用 xlsx-sheet-to-json-schema.

4. 对照并批准草案

逐字段比较两个分支的结果，在有意修改后重新推导，并在交给校验或类型生成前记录类型、必填性、空值和异常样本的决定。 使用 json-schema-generator, xlsx-sheet-to-json-schema.

交付前验收结果

• 草案记录了 JSON 样本或工作簿、工作表和行范围、推导分支，以及使用过的手动设置。
• 每个字段都有类型、必填性、可空性、枚举或约束候选和异常值的明确审阅结论。
• 已检查正常、缺失、null、空集合、混合类型和异常样本，并记录草案能否用于校验或类型代码生成。
• 最终记录清楚标注推导假设，不把草案描述成权威业务契约。

常见问题

• 推导出的 schema 能自动成为生产契约吗？ 不能。它只是根据观测样本整理出的结构化提案。采用前必须由契约负责人审阅业务必填性、兼容性、空值政策、格式和特殊值。
• 应该准备多少样本？ 样本应覆盖正常变化、缺失字段、null、空集合、边界值和已知异常。数量本身不是目标，关键是样本有代表性且来源可追溯。
• JSON 样本和 XLSX 工作表不一致怎么办？ 不要静默合并冲突。先映射字段名，确认它们是否属于不同版本或业务对象，再为每个决定记录来源优先级。
• 工具能准确识别日期和标识符吗？ 工具可以根据观测值提出类型或约束建议，但日期格式、数字标识符、代码和前导零仍需结合业务规则人工检查。