JSON、YAML、XML 的区别,以及互相转换时会丢失什么
JSON、YAML 和 XML 的数据模型不同,因此格式之间的转换不是换一种写法,而是按规则做映射。注释、锚点、属性、数组形态和值的类型,是转换中最容易丢失的内容。
ConvertBox发布
不是同一份数据的三种写法,而是三种数据模型
JSON、YAML 和 XML 常被说成是同一份数据的不同写法,可以随意互换。实际上三者各有自己的数据模型,凡是模型对不上的地方,转换工具都得自己定一条规则。JSON 的值恰好有六种。YAML 1.2 能表达 JSON 能表达的一切,并且在设计上保证 JSON 文档本身就是合法的 YAML,此外还增加了注释、引用和多种字符串写法。XML 则是一种文档格式:由带名称的元素组成的树,元素可以带属性和文本,语法里没有数字、布尔值或数组的概念。
| JSON | YAML | XML | |
|---|---|---|---|
| 值的类型 | 字符串、数字、布尔值、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 加上单引号,因此结果在旧解析器中也能原样读出。
| 未加引号的 YAML | YAML 1.1 解析器(如 PyYAML) | ConvertBox YAML to JSON(js-yaml,YAML 1.2 规则) |
|---|---|---|
| country: NO | false | "NO" |
| enabled: yes | true | "yes" |
| zip: 012 | 10(按八进制解读) | 12 |
| version: 1.20 | 1.2 | 1.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 之后,对于可能重复出现的元素,代码要同时能处理单个值和数组两种情况。
- 如果签名或校验和针对的是精确的字节内容,请先校验再格式化或转换,因为任何重新序列化都会改变字节。