开发者工具 · JSON 格式化程序和验证程序
为什么 JSON 没有评论：设计决策及其解决方法
· 背景
json 标准 验证
评论已被故意从 JSON 中删除。这篇文章解释了原因，为什么每次尝试添加它们都会创建一种新格式，以及当配置文件确实需要注释时您的选择是什么。
破坏构建的评论
破坏构建的注释 - 添加到 JSON 配置和在第一个斜杠处停止的解析器的有用注释。作者可能从 JavaScript 或支持 JSONC 的编辑器复制了模式，而部署工具则使用严格的 JSON。即使消费者拒绝第一个评论标记，语法突出显示也可以使注释看起来合法。
注释被拒绝，因为斜杠不是扫描器期望值或成员的 JSON 标记。 ToolAcre 不会默默地剥离 JSONC 或 JSON5 语法。传统的注释形属性是普通数据，即使严格的 JSON 语法接受它，也可能违反应用程序模式。关于 JSON 设计的不受支持的历史主张被省略或纠正，而不是在没有主要证据或可追溯的标准来源可用于验证的情况下作为既定事实呈现。
Crockford 删除评论的原因
Crockford 删除注释的原因 - 后来的解释说注释已被用来携带解析指令，破坏了实现之间的互操作性。相关的设计结果是标准 JSON 没有注释标记。有关私人动机、准确年代或普遍行业反应的主张需要此存储库未提供的历史来源。
因此，此处省略或纠正了不受支持的历史主张。可观察的标准和解析器行为就足够了：严格的 JSON 通过六种值类型和两个容器交换数据，无需注释通道。该限制阻止一个接收者将操作含义分配给另一个接收者忽略的文本，但它也使 JSON 不太适合手动维护配置。
验证者对评论的报告内容
验证器对评论报告的内容 — `//` 和 `/* */` 不在语法中，因此错误出现在带有行和列的第一个斜杠上。扫描仪并不反对纸条上的文字。它不能在该位置以 `/` 开头任何有效的 JSON 值、成员名称或分隔符。
对于 `{"port":8080, // local only "secure":false}`，逗号有效，下一个合法标记应该是带引号的属性名称或右大括号。斜杠违反了这一期望。仅删除注释会留下有效的分隔符和下一个成员；删除附近的标点符号可能会产生第二个错误。每次编辑后重新验证准确的严格输出。
添加评论的格式
添加注释的格式 — JSONC 允许围绕其他熟悉的 JSON 语法进行注释，而 JSON5 增加了便利性，例如不带引号的标识符键和尾随逗号。 Hjson 强调人工编辑和额外的宽松语法。 YAML 有自己的语法，包括注释，而不仅仅是添加了注释的 JSON 。
接受是特定于消费者的：编辑器设置和 TypeScript 配置可能使用允许注释的解析器，而包清单或 API 正文可能需要严格的 JSON。 Kubernetes 通常根据其工具使用 YAML 或 JSON。命名文档和文件处理中的实际格式；剥离扩展或调用每个对象符号“JSON”会隐藏兼容性边界。
严格 JSON 内的解决方法
严格 JSON 内部的解决方法 — 传统的 `_comment` 或 `//` 键将解释存储为普通字符串成员。它能够通过严格的解析，因为键和值都使用标准标记。多个注释需要唯一的键或数组，因为重复的成员名称不可靠并且可能会被解析器折叠。
解决方法更改数据模型。带有 `additionalProperties: false` 的模式可以拒绝注释，并且应用程序可以将其作为真实配置保留或传输。外部文档、相邻的自述文件或模式 `description` 通常提供更安全的解释渠道。仅当每个消费者明确允许并忽略它们时才使用评论形成员。
工作示例：带注释的设置文件
工作示例：带注释的设置文件 — 以包含 `"timeout":30` 上方的 `// seconds before retry` 的 JSONC 源开始。如果目标仅接受 JSON，请使用理解 JSONC 的解析器来生成数据，然后将该数据序列化为严格的 JSON。部署的工件变为 `{"timeout":30}`，而维护的源保留其解释。
不要使用正则表达式删除注释。斜杠序列可以合法地出现在字符串（例如 URL）内，块注释模式可以以文本替换错误处理的方式跨行。保持源和生成的工件不同，验证严格的结果并在构建中安排重新生成。这保留了作者注释，而不假装接收解析器支持它们。
这不包括什么
这不包括什么 - 如何配置单个解析器以接受注释，这是特定于工具的并且经常更改。一个库中的许可选项不会改变 JSON 语法或保证另一服务将接受相同的文本。检查解析器、版本和目标，而不是依赖编辑器的显示。
本文还避免了关于评论被删除的确切时间、谁首先采用每种解决方法或是否单独一个设计决策导致 JSON 受欢迎的不受支持的主张。这种历史断言需要独立的主要来源。此处省略或更正；支持的结论仅限于当前严格的语法、存储库行为以及命名格式之间的操作差异。
要点：JSON 是一种数据交换格式，而不是配置语言
要点：JSON 是一种数据交换格式，而不是一种富含注释的配置语言 - 并且验证器准确显示注释在哪里违反了严格的语法。当人们需要注释时，选择使用工具正式支持的格式或维护生成单独的严格工件的注释源。不要以为评论会被无害地忽略。
如果严格的 JSON 是强制性的，请将说明移至文档或使用模式批准的元数据，然后验证最终文档。 ToolAcre 有意报告第一个斜杠，而不是静默删除材料，因为静默转换可能会更改字符串或隐藏格式不匹配。历史背景应该保持同样的纪律：省略或纠正不受支持的主张，而可观察的语法和解析器行为则得出结论。