开发者工具·语法转换器

YAML 在 JSON 转换中丢失的功能：注释、锚点和标签

2026年8月4日 · 工作原理

yaml json 数据格式

YAML 具有注释、锚点、别名、合并键、标签和多文档流； JSON 没有这些。这篇文章解释了转换器对每个文件的作用以及为什么转换回来永远不会恢复原始文件。

文件返回的时间更长，并且没有任何注释 - YAML 配置转换为 JSON 并返回，以及所有未保存的内容

即使在每个注释消失后，YAML 文件也可以从 JSON 返回更长时间。共享一个映射的锚点被解析为重复的对象数据，因此序列化器独立写入每个副本。这些价值观可能仍然一致，但创作结构和解释已经消失。

这就是为什么 YAML-to-JSON-to-YAML 往返应被判断为数据转换，而不是源保存。 ToolAcre 读取受限值图并写入新文档。它从不保留包含注释、锚点名称、引用选择或块标量表示的具体语法树。

注释被 YAML 解析器丢弃，因为 JSON 没有注释节点。以 `#` 开头的行可以解释为什么存在超时或谁拥有服务；一旦删除，任何算法都无法推断出措辞或位置。转换回来会创建有效的 YAML ，而无需该操作上下文。

在版本控制中保留原始文件并在替换之前检查差异。如果目标只是检查解析值，则 JSON 很有用。如果目标是在保留注释的同时重新格式化，则此通用值转换器是错误的表示。

锚点和别名在安全限制内被接受，然后被解析。 `base: &b {x: 1}` 和 `copy: *b` 成为包含 `x: 1` 的两个对象路径。输出 YAML 使用 `noRefs`，因此共享对象标识不会创建新的锚点。即使重复值仍然存在，紧凑关系也消失了。

递归别名被拒绝，因为 JSON 无法表达循环。别名扩展受到别名计数、嵌套和扩展节点测量的限制；一个将字符串化为超过一百万个值的简短文档被停止。这可以保护选项卡而不要求任意 YAML 支持。

该大纲假设 YAML 1.1 合并键已展平。 ToolAcre 仅加载 js-yaml 的 JSON 或 Core 架构，这两种架构均不启用合并类型。在这些模式下， `<<` 键是普通数据，而不是合并映射的指令。因此，将扁平合并呈现为交付行为是错误的。

如果您的源依赖于合并键语义，请在拥有该约定的应用程序中解析它，或者在转换之前显式重写值。用作普通 `<<` 值的别名仍可能解析为对象，但键仍然是 `<<`；这并不等同于将其成员合并到父级中。

受限模式识别的标准显式标记可以选择基本类型，例如 `!!str` 或 `!!int`。自定义和更丰富的标签（包括二进制、时间戳、集合、有序映射、JavaScript 函数和 Python 对象构造函数）将被拒绝。它们不会被字符串化，也不会被执行。

接受由 `---` 分隔的 YAML 流。一份文档成为一种价值；其中几个成为一个数组，并带有命名文档计数的警告。尾随分隔符可以根据所选模式创建一个空的最终文档。这里的目标没有流模型，因此数组是声明的约定。

使用带有重试和超时的 `defaults: &d`、解释超时的注释，然后使用 `service:` 和 `inherited: *d`。 JSON 包含默认值和重复的继承对象；评论和锚点名称不存在。将 JSON 转换回来会发出两个映射而不是锚关系。

添加 `---` 后跟另一个文档，JSON 根成为文档数组。添加 `!!binary` 并使用受限架构提示停止转换。这三个变化区分了已解析的支持数据、结构约定和完全无支持的构造。

普通对象插入顺序通常保持可见，但它不是源样式的保存，并且选择排序键会故意更改它。引号、流式与块式、标量拼写和注释都不再存在。重复的映射键会保留最后一个值并发出警告，而不是保留两个无效条目。

作者通过引用 YAML 1.1 消费者可能误读的值来保护不明确的字符串，但这种安全选择可能与作者的原始风格不同。数据相等性是对普通 JSON 形值的合理测试；文本平等则不然。

每当含义位于 JSON 形值之外时，YAML 到 JSON 就会有损：注释、别名、不支持的标签、流边界本身和样式。 ToolAcre 使一些损失变得可见，并拒绝危险或循环结构，而不是假装保留它们。

在采用工作流程之前转换代表性文件。检查警告、区分解析值并保留编写的 YAML。该面板是解析器所看到内容的绝佳镜头，但它不是保留注释的编辑器或完整的 YAML 对象模型转换器。

对于迁移审核，请将值更改与仅源更改分开。 JSON 深度比较可以确定普通值是否幸存，而文本差异则显示必须更改的注释、锚点和样式。两张支票都不能替代另一张。将值比较称为无损会忽略源信息；将每个文本更改称为数据故障将忽略有效的重新序列化。