JSON、YAML、XML 的区别,以及互相转换时会丢失什么

JSON、YAML 和 XML 的数据模型不同,因此格式之间的转换不是换一种写法,而是按规则做映射。注释、锚点、属性、数组形态和值的类型,是转换中最容易丢失的内容。

ConvertBox发布

不是同一份数据的三种写法,而是三种数据模型

JSON、YAML 和 XML 常被说成是同一份数据的不同写法,可以随意互换。实际上三者各有自己的数据模型,凡是模型对不上的地方,转换工具都得自己定一条规则。JSON 的值恰好有六种。YAML 1.2 能表达 JSON 能表达的一切,并且在设计上保证 JSON 文档本身就是合法的 YAML,此外还增加了注释、引用和多种字符串写法。XML 则是一种文档格式:由带名称的元素组成的树,元素可以带属性和文本,语法里没有数字、布尔值或数组的概念。

JSONYAMLXML
值的类型字符串、数字、布尔值、null、数组、对象与 JSON 相同的类型,根据未加引号的值的写法推断只有文本,类型由模式或读取方决定
注释无从 # 到行尾<!-- ... -->
属性无无有:<user id="7">
复用一段内容无锚点与别名:&base、*base只能借助 DTD 实体
文本与标记混排不支持不支持支持:<p>Hello <b>world</b></p>
语法规则只能用双引号,不允许末尾逗号缩进即结构,不能用制表符缩进每个标签都要闭合,只能有一个根元素

解析器有多严格,错误藏在哪里

JSON(RFC 8259)是三者中书写要求最严格的:键和字符串必须用双引号,末尾多一个逗号就是错误,也没有注释。好处是文档要么解析成功,要么明确失败。当本站的 JSON 格式化工具显示错误而不是结果时,说明确实存在问题,原因通常是末尾逗号、单引号、注释,或者从 JavaScript 控制台粘贴过来的 NaN 之类的值。

XML 对格式良好的要求同样严格:每个标签都要闭合,属性值必须加引号,根元素有且只有一个。在此之上,还可以用 XSD 这样的模式语言检查元素是否按正确的顺序和类型出现,这是 JSON 和 YAML 都没有内置的能力。YAML 恰好相反。它写起来容易,但结构来自缩进,所以多缩进两格的一行仍然是合法的 YAML,只是含义变了,而且没有任何警告。把 YAML 文件转换成 JSON 是查看解析器实际理解结果的实用办法,因为花括号和方括号会把嵌套关系明确地写出来。

每种格式的常规使用场景

  • JSON 用于程序之间的数据交换:Web API、浏览器存储、日志记录、包清单。主流语言都能原生解析,类型集合也与程序使用的类型一致。
  • YAML 用于由人手工编辑的文件:Kubernetes 清单、Docker Compose 文件、CI 流水线定义、Ansible playbook。注释和锚点让很长的配置保持可读。
  • XML 用于文档和受模式约束的数据交换:SOAP 服务、RSS 和 Atom 订阅源、SVG,以及 .docx 和 .xlsx 文件内部的各个部件。当文本与标记混排,或者接收方要用 XSD 校验时,选择 XML。
  • 一条经验法则:程序写、程序读,用 JSON;由人维护,用 YAML;标准或对接方规定了元素名称,用 XML。

YAML 的类型推断与挪威问题

YAML 根据未加引号的值的写法判断类型,而且规则随版本而变。YAML 1.1 把 yes、no、on、off 及其大写形式当作布尔值,所以国家代码列表里代表挪威的 NO 会被读成 false。YAML 1.2 只保留了 true 和 false,但包括 PyYAML 在内的一些常用解析器仍然遵循 1.1 的规则。因此同一个文件在两个工具里可能是不同的含义。

应对办法在哪里都一样:凡是可能被读成其他类型的字符串,都加上引号。本站的 JSON to YAML 转换工具在输出时会这样做,给 '012'、'true'、'2024-01-01' 这类字符串以及 YAML 1.1 的 yes、no、on、off 加上单引号,因此结果在旧解析器中也能原样读出。

未加引号的 YAMLYAML 1.1 解析器(如 PyYAML)ConvertBox YAML to JSON(js-yaml,YAML 1.2 规则)
country: NOfalse"NO"
enabled: yestrue"yes"
zip: 01210(按八进制解读)12
version: 1.201.21.2
released: 2024-01-01日期值"2024-01-01T00:00:00.000Z"

JSON 与 YAML:往返转换会丢掉什么

从 JSON 转到 YAML 不会丢失数据,因为每个 JSON 值都有对应的 YAML 写法。可能改变的只是一些附带细节:本站的转换工具会先用浏览器的 JSON 解析器读取输入,所以 1.0 会被写成 1,超过 2^53(9007199254740991)的整数末尾几位会改变,重复的键只保留最后一个,看起来像整数的键会被移到对象的最前面。

信息是在 YAML 转 JSON 的方向上消失的。注释会被丢弃。锚点(&base)和别名(*base)会被展开成完整的副本,合并键(<<: *base)会被替换成合并后的内容,所以得到的 JSON 是正确的,但五个服务共用同一段配置这一事实不再保留。块标量变成普通字符串,非字符串的键变成字符串,.inf 和 .nan 因为 JSON 没有对应的数字而变成 null。另外,YAML to JSON 工具不接受用 --- 分隔的多文档流,也不接受 CloudFormation 的 !Ref 这类应用专用标签,需要一次转换一个文档。请把 YAML 文件作为唯一的原始版本:转成 JSON 再转回来,得到的是等价的数据,而不是原来的文件。

JSON 与 XML:属性、重复元素和类型

XML 没有数组,JSON 没有属性,所以每个转换工具都要采用一套约定,而不同工具的约定并不相同。表中列出的是本站两个转换工具使用的约定。

在 JSON to XML 方向上,工具会把全部内容包在名为 root 的元素里,不生成属性,并把元素名称中不合法的字符替换成下划线:first name 这样的键会变成 first_name,用中文写的键会全部变成下划线。如果目标格式规定了元素名称、命名空间或属性,例如 SOAP 或 RSS,就需要手工修改结果,或者使用可以显式指定映射的库。

输入输出需要注意
JSON "tag": ["a", "b"]<tag>a</tag> <tag>b</tag>数组变成重复的元素,没有外层包裹
XML <tag>a</tag> 只出现一次"tag": "a"一个元素得到字符串,两个元素得到数组
JSON "age": 30, "ok": true<age>30</age> <ok>true</ok>再转回 JSON 时两者都是字符串 "30" 和 "true"
JSON "items": []没有任何输出空数组不留痕迹
XML <user id="7">Ann</user>"user": {"@attributes": {"id": "7"}, "#text": "Ann"}属性保存在一个保留键之下
XML <p>Hello <b>big</b> world</p>"p": {"b": "big"}子元素之间的文本被丢弃

转换真实文件之前值得做的检查

  • 给看起来像数字、布尔值或日期的 YAML 字符串加上引号,例如版本号、邮政编码、国家代码和时间。
  • 超过 15 位的标识符按字符串传递,基于 JavaScript 的工具会对大于 2^53 的整数做舍入。
  • XML 转成 JSON 之后,对于可能重复出现的元素,代码要同时能处理单个值和数组两种情况。
  • 如果签名或校验和针对的是精确的字节内容,请先校验再格式化或转换,因为任何重新序列化都会改变字节。

本指南涉及的工具

相关指南

全部指南