YAML – JSON Schema

YAML 和 JSON：互操作性与模式

YAML 被设计为 JSON（JavaScript 对象表示法）的超集。这意味着，除了极少数例外，任何有效的 JSON 文档也是有效的 YAML 文档。这种互操作性是其关键特性，使得 YAML 可以在 JSON 普遍存在的环境中被使用。

YAML 的核心模式（Core Schema）定义了直接对应 JSON 类型的数据类型：null、布尔值、整型、浮点数、字符串、数组（YAML 中的序列）和对象（YAML 中的映射）。

将 YAML 核心模式类型映射到 JSON

解析遵循核心模式（或 JSON 模式，JSON 模式是其子集）的 YAML 文档时，其数据类型可以直观地转换为 JSON 类型。

1. 空值 (Null)

YAML 使用 null 或 ~（波浪号）表示空值。键对应的空值也可以解释为 null。

# YAML
optional_field: null
another_null: ~
empty_implies_null:

对应的 JSON：

{
  "optional_field": null,
  "another_null": null,
  "empty_implies_null": null
}

2. 布尔值 (Boolean)

在其核心模式中，YAML 使用 true 和 false（小写）表示布尔值。

# YAML
is_active: true
has_errors: false

对应的 JSON：

{
  "is_active": true,
  "has_errors": false
}

3. 整型值 (Integer)

YAML 支持十进制、十六进制 (0x...) 和八进制 (0o...) 整型。

# YAML
count: 123
negative_value: -45
hex_value: 0xFF  # 十进制的 255
octal_value: 0o77 # 十进制的 63

对应的 JSON：

{
  "count": 123,
  "negative_value": -45,
  "hex_value": 255,
  "octal_value": 63
}

4. 浮点数 (Floating-Point Numbers)

YAML 支持标准十进制表示法和科学（指数）表示法来表示浮点数。还支持 .inf（无穷大）和 .nan（非数字）等特殊值。

# YAML
pi_approx: 3.14159
scientific_notation: 1.23e-4 # 0.000123
positive_infinity: .inf
negative_infinity: -.inf
not_a_number: .nan

对应的 JSON（注意：JSON 标准本身没有明确定义 Infinity 或 NaN 字面量，但许多解析器可以处理它们，或者根据转换器的严格性，它们可能表示为 null 或字符串。YAML 规范对 .inf 和 .nan 的定义是健壮的）：

{
  "pi_approx": 3.14159,
  "scientific_notation": 0.000123,
  "positive_infinity": "Infinity", // 或者取决于 JSON 序列化器，可能为 null 或报错
  "negative_infinity": "-Infinity",// 或者可能为 null 或报错
  "not_a_number": "NaN"         // 或者可能为 null 或报错
}

为了最大限度地兼容 JSON，如果要求严格遵循 JSON，通常最好将 YAML 的 .inf 和 .nan 转换为 null 或由消费应用程序约定的特定字符串，因为官方 JSON 语法缺少这些。

5. 字符串、序列和映射

YAML 字符串（普通、单引号、双引号、块式）映射到 JSON 字符串。YAML 序列映射到 JSON 数组，YAML 映射映射到 JSON 对象。

# YAML
message: "Hello, YAML!"
items: ["apple", "banana", "cherry"]
configuration:
  host: localhost
  port: 8080

对应的 JSON：

{
  "message": "Hello, YAML!",
  "items": ["apple", "banana", "cherry"],
  "configuration": {
    "host": "localhost",
    "port": 8080
  }
}

超越 JSON 的 YAML 特性

虽然 YAML 是 JSON 的超集，但它包含 JSON 中不存在的特性，例如：

• 注释 (#)
• 用于数据重用的锚点 (&) 和别名 (*)
• 显式标签 (!!str, !mycustomtype)
• 块式标量（字面量 | 和折叠 >）
• 单个流中的多个文档（用 --- 分隔）

将包含这些特性的 YAML 转换为 JSON 时，它们通常会被解析或省略：注释被移除，锚点/别名被展开，自定义标签如果 JSON 转换器不知道如何处理可能会被剥离或导致错误，块式标量被转换为标准 JSON 字符串。多个文档需要单独处理。

实际应用

强大的 JSON 兼容性意味着：

• 在需要 JSON 的地方，尤其是配置时，通常可以使用 YAML。
• 许多工具和库可以在 YAML 和 JSON 之间无缝转换。
• YAML 可以提供一种更易于人类阅读的方式来编写和维护最终将被消费为 JSON 的数据。

理解这种关系有助于在利用 YAML 的可读性和高级特性的同时，确保在需要时与基于 JSON 的系统兼容。