Copyright © 2020-2026 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
[JSON-LD11] 是一种基于 JSON 的格式，用于序列化链接数据 [LINKED-DATA]。 近年来，[YAML] 已成为一种更 简洁的格式， 用来表示此前以 [JSON] 序列化的信息， 包括 API 规范、数据模式和链接数据。
本文档将 YAML-LD 定义为一组基于 YAML 的约定， 这些约定指定如何基于 JSON-LD 的语法、语义和 API， 将链接数据序列化为 YAML。
由于 YAML 比 JSON 表达能力更强， 无论是在可用的数据类型方面，还是在文档结构方面 （见 [RFC9512]）， 本文档标识了对 YAML 的约束， 使任何 YAML-LD 文档都可以用 JSON-LD 表示。
本节描述本文档在其发布时的状态。当前 W3C 出版物列表和本技术报告的最新修订版本可在 W3C 标准和草案 索引中找到。
本规范最初由 JSON-LD 社区组开发。
本文档由 JSON-LD 工作组作为 工作草案发布，并使用 推荐 路线。
作为 工作草案发布并不意味着 W3C 及其成员的认可。
这是一个草案文档，可能随时由其他文档更新、替换或废弃。 除作为进行中的工作外，不应引用本文档。
本文档由一个依据 W3C 专利 政策运作的小组制作。 W3C 维护了一份 任何专利 披露的公开列表， 这些披露与该小组的交付成果相关；该页面还包含 披露专利的说明。实际知晓某项专利且认为该专利包含 必要权利要求的个人， 必须按照 W3C 专利政策第 6 节 披露相关信息。
本文档受 2025 年 8 月 18 日 W3C 流程文档管辖。
YAML-LD 将 JSON-LD 的数据模型和处理模型应用于 YAML， 从而使关联数据能够使用 YAML 语法编写，同时仍可 表示为 JSON-LD。
它适用于由人类和软件代理读取和编写的文档， 包括基于大型语言模型的软件代理。
下面给出了一个 YAML-LD 入门示例。
"@context":
schema: https://schema.org/
dbo: http://dbpedia.org/ontology/
dbp: http://dbpedia.org/property/
dbr: http://dbpedia.org/resource/
xsd: http://www.w3.org/2001/XMLSchema#
dbp:discovered:
"@type": xsd:date
dbp:star:
"@type": "@id"
"@id": dbr:Proxima_Centauri_b
"@type": dbo:Planet
schema:description: >-
The closest known exoplanet to Earth,
orbiting in Proxima Centauri's habitable zone.
dbp:discovered: 2016-08-24
dbp:star: dbr:Proxima_Centauri本节为非规范性内容。
要理解本规范的基础，必须熟悉以下内容：
本文档主要面向以下两类受众。
在相关技术中，构建大多数支持 YAML-LD 的应用时 需要熟悉 JSON-LD；而只有在希望将 YAML-LD 转换为 RDF 图，或反向转换时，才需要熟悉 RDF。
其他专业人员，包括 IT 及非 IT 领域人员，他们希望阅读和/或制作 YAML-LD 格式的链接数据文档。此类文档可以：
对这些用户而言，不要求熟悉 JSON-LD，但理解链接数据 原则可能会有帮助。
本节为非规范性内容。
本文档使用以下在外部规范中定义的术语， 并定义 JSON-LD 专用术语。
YAML-LD 流是一个YAML 流， 由YAML-LD 文档组成。 在磁盘上或通过网络传输时，YAML-LD 始终以YAML-LD 流的形式交换 （每个文件或 HTTP 正文对应一个流），其中包含一个或多个YAML-LD 文档。
YAML-LD 文档是指任何 YAML 文档，对其 转换为 [JSON] 会产生 一个有效的 JSON-LD 文档，并且该文档可解释为 [LINKED-DATA]。
术语 JSON 文档表示一种资源的序列化， 该资源符合 [JSON] 语法。
术语 JSON-LD 文档，以及 值对象 引自 [JSON-LD11]。
术语 内部 表示，以及 documentLoader 引自 [JSON-LD11-API]。
术语 数组、 布尔值、 映射、 映射条目、 null，以及 字符串 引自 [INFRA]。
术语 数值 引自 [ECMASCRIPT]。
术语 YAML、 YAML 表示图、 YAML 流、 YAML 指令、 TAG 指令、 YAML 文档、 YAML 序列 （即 块序列 或 流式序列）、 YAML 映射 （即 块映射或 流式映射）、 节点、 标量、 节点锚点、 节点标签， 以及 别名 节点， 均引自 [YAML]。
术语 RDF 字面量、 带语言标签的 字符串、 数据类型 IRI，以及 语言标签 引自 [RDF11-CONCEPTS]。
本文档中的术语 片段和 片段 标识符 应按照 [URI] 中的含义解释。
术语 链接数据 引自 [LINKED-DATA]。
本节为非规范性内容。
本规范使用以下命名空间前缀：
| 前缀 | IRI |
|---|---|
| ex | https://example.org/ |
| i18n | https://www.w3.org/ns/i18n# |
| rdf | http://www.w3.org/1999/02/22-rdf-syntax-ns# |
| rdfs | http://www.w3.org/2000/01/rdf-schema# |
| xsd | http://www.w3.org/2001/XMLSchema# |
| schema | https://schema.org/ |
| prov | http://www.w3.org/ns/prov# |
namespace-prefixes.yamlld
。
这些前缀在本文档中用作
紧凑 IRI 的一部分，
作为所得 IRI 的简写，
例如使用 schema:url
表示 https://schema.org/url。
除标记为非规范性的章节外，本规范中的所有创作指南、图表、示例和注释均为非规范性内容。 本规范中的其他所有内容均为规范性内容。
本文档中的关键词 MAY、MUST、MUST NOT、RECOMMENDED 和 SHOULD 应按照 BCP 14 [RFC2119] [RFC8174] 中的描述解释，但仅当它们像此处所示以全大写形式出现时才如此。
如果一个 YAML-LD 文档遵循本规范中的规范性陈述， 并且可以转换为 [JSON-LD11] 表示， 然后在不丢失语义信息的情况下再转换回符合要求的 YAML-LD 文档， 则该文档符合本规范的 YAML-LD 基本配置文件。
为方便起见，针对文档的规范性陈述通常表述为 关于文档属性的陈述。
YAML-LD 支持 JSON-LD 1.1 [JSON-LD11] 及 后续版本。
YAML-LD 基于 YAML
Ain't Markup Language (YAML™) version 1.2.2 [YAML]。
YAML-LD 处理器 MUST 使用 YAML 1.2（或更高的向后兼容版本）
实现；请参见 8.
互操作性考量，了解
YAML 1.1 所产生的互操作性问题。
实现者 MAY 使用 %YAML 指令
在给定文档中指定 YAML 版本。
为符合要求，实现 MUST 满足以下测试套件中的所有测试用例：
……但忽略以下测试用例：
json-ld-1.0 的测试用例。
由于 YAML 是 JSON 的超集，用 JSON-LD 测试套件中的测试用例来测试 YAML-LD 实现应当是很简单的。
本节为非规范性内容。
[YAML] 是 [JSON] 的超集，即， 每个有效的 JSON 文档也都是有效的 YAML 文档。 YAML 还提供了许多额外功能，其中最主要的是，由于最大限度地减少了 标点符号要求，因此提高了人类可读性。
如下方比较表所示，YAML 比 JSON 更灵活。
| 功能 | [JSON] | [YAML] | YAML-LD |
|---|---|---|---|
| 允许的编码 | |||
| UTF-8 | ✅ | ✅ | ✅ |
| UTF-16 | ❌ | ✅ | ❌ |
| UTF-32 | ❌ | ✅ | ❌ |
| 原生数据类型 | |||
{} 对象 |
✅ | ✅ | ✅ |
[] 数组 |
✅ | ✅ | ✅ |
| 字符串 | ✅ | ✅ | ✅ |
| 数字 | ✅ |
✅
整数 浮点 数 |
✅ |
| 布尔值 | ✅ | ✅ | ✅ |
| null | ✅ | ✅ | ✅ |
| 功能 | |||
| 使用分隔符的字符串、数组和对象 | ✅ | ✅ | ✅ |
| 无标点符号的字符串、数组和对象 | ❌ | ✅ | ✅ |
| 自定义类型 | ❌ | ✅ 通过标签 | 仅限核心架构 |
| 每个文件的文档数 | 1 | ⩾ 1，通过 YAML 流 | ⩾ 1（取决于 extractAllScripts 标志，请参阅流处理） |
| 注释 | ❌ | ✅ | ✅ 视为空白 |
| 锚点和别名 | ❌ | ✅ | ✅ 锚点名称不承载语义信息 |
| 循环 | ❌ | ✅ | ❌ 不允许 |
| 映射键类型 | string |
YAML 中可表示的任何类型，从 字符串到映射 | string |
json-vs-yaml.yamlld
。
[eriksson-hallberg] 表明， 尽管对于某些深度嵌套的文档，YAML 可能比等效的 JSON 更大， 但对于许多结构较为扁平的文档，它比美化打印的 JSON 更小，同时仍具有人类可读性。 这种组合可以减少大型语言模型和其他软件代理 必须处理的文本量，而无需单独使用压缩编码。
本规范的目标是允许将 JSON-LD 文档 处理并序列化为 YAML，然后再转换回 JSON-LD，而不会 丢失任何语义信息。
这始终是可行的，因为
示例 1 的 JSON-LD 序列化：
{
"@context": {
"schema": "https://schema.org/",
"dbo": "http://dbpedia.org/ontology/",
"dbp": "http://dbpedia.org/property/",
"dbr": "http://dbpedia.org/resource/",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"dbp:discovered": {
"@type": "xsd:date"
},
"dbp:star": {
"@type": "@id"
}
},
"@id": "dbr:Proxima_Centauri_b",
"@type": "dbo:Planet",
"schema:description": "距离地球最近的已知系外行星，运行于比邻星的宜居带内。",
"dbp:discovered": "2016-08-24",
"dbp:star": "dbr:Proxima_Centauri"
}YAML 不是标记语言 （YAML™）1.2.2 版分多个步骤描述了 YAML 处理，这些步骤重现于图 1中。 此处理在采用 YAML 语法的字符流（右侧）与所谓的 “原生数据结构”（左侧）之间进行双向转换。 在 JSON-LD 中，该数据结构是 JSON-LD 的内部表示。
本节描述 YAML-LD 对 YAML 处理步骤施加的要求， 方向为加载方向（图 1中从右向左）。 转储按相反方向进行，从兼容 JSON 的内部表示生成 符合要求的 YAML-LD 流。
呈现是图 1中的 YAML 字符流。
在不属于封闭生态系统的系统之间交换的 JSON 文本 必须使用 UTF-8 编码。
YAML-LD 流必须使用
UTF-8 编码；
否则，必须检测到
invalid-encoding
错误，并中止处理。
YAML 允许同一个 YAML 呈现流包含多个序列化树， 其形式为由标记分隔的一系列文档。
YAML-LD 流可以包含多个 YAML-LD 文档，如下所示。
"@context":
dbo: http://dbpedia.org/ontology/
dbr: http://dbpedia.org/resource/
"@id": dbr:Proxima_Centauri
"@type": dbo:Star
---
"@context":
dbo: http://dbpedia.org/ontology/
dbr: http://dbpedia.org/resource/
"@id": dbr:Proxima_Centauri_b
"@type": dbo:Planet有关 YAML 流的互操作性注意事项， 请参阅 YAML 媒体类型中的相关章节。
锚点名称属于序列化细节，并在 组合完成后被丢弃。
在本规范中，锚点是指 YAML 的
节点锚点机制
（使用别名节点，在
序列化中使用 & 和 *），
以便在序列化图中通过引用重用同一个逻辑节点。
它与 HTML
超链接
或 URL 片段标识符无关。
请参阅 [YAML]
§6.9.2 节点锚点。
因此，锚点 名称 不得用于传达相关信息， 在处理文档时可以更改， 并且在 YAML-LD 处理期间可以丢弃。
锚点在 @context 块中特别有用。
当多个术语共享同一个术语定义时——例如，所有
以 IRI 为值的属性——可以为共享定义设置一次锚点，并
为每个术语使用别名，从而避免重复。
以下示例将 IRI 强制转换定义锚定为
&iri，并将其重用于三个属性：
"@context":
dbo: http://dbpedia.org/ontology/
dbp: http://dbpedia.org/property/
dbr: http://dbpedia.org/resource/
dbp:star: &iri
"@type": "@id"
dbp:discoveryMethod: *iri
dbp:discoverySite: *iri
"@id": dbr:Proxima_Centauri_b
dbp:star: dbr:Proxima_Centauri
dbp:discoveryMethod: dbr:Doppler_spectroscopy
dbp:discoverySite: dbr:European_Southern_Observatory解析所有锚点和别名后，等效的 JSON-LD 为：
{
"@context": {
"dbo": "http://dbpedia.org/ontology/",
"dbp": "http://dbpedia.org/property/",
"dbr": "http://dbpedia.org/resource/",
"dbp:star": {
"@type": "@id"
},
"dbp:discoveryMethod": {
"@type": "@id"
},
"dbp:discoverySite": {
"@type": "@id"
}
},
"@id": "dbr:Proxima_Centauri_b",
"dbp:star": "dbr:Proxima_Centauri",
"dbp:discoveryMethod": "dbr:Doppler_spectroscopy",
"dbp:discoverySite": "dbr:European_Southern_Observatory"
}YAML-LD 文档的序列化中可以包含锚定节点和别名节点， 但其表示 图不得包含循环； 否则，必须检测到 loading-document-failed 错误，并中止处理。
组合表示图时，每个别名节点 必须解析为其目标锚点所标识的节点。 构造 JSON-LD 内部表示时， 对该节点的每个引用 必须被视为该节点的副本。
组合完整的表示图时，YAML-LD 使用
YAML 核心架构进行标量类型
解析。
无法在 [JSON] 中表示的浮点值——
具体而言，包括
无穷大（.inf、-.inf、+.inf）和
非数字（.nan）——在构造 JSON-LD 内部
表示时，必须导致引发
loading-document-failed
错误。
YAML 核心架构未定义
时间戳类型；
2018-04-01 等标量会解析为普通字符串。
但是，许多 YAML 库默认实现 YAML 1.1 时间戳解析，
并会静默地将此类标量转换为原生日期或日期时间对象。
YAML-LD 处理器不得执行此类转换，并且必须将这些值视为字符串。
构造在 图 1中生成的原生数据结构 是 JSON-LD 内部表示。
[JSON-LD11-API] 定义了
extractAllScripts
标志，该标志允许解析 HTML 文档中
多个包含 JSON-LD 内容的 <script> 标签。
符合要求的 YAML-LD 实现从 YAML-LD 流构造 JSON-LD 内部 表示时，必须应用此标志。
true，则内部表示必须是
一个包含流中每个文档的构造值的数组，
即使该流仅包含一个文档也是如此。
false，则必须仅构造流中的第一个文档。
对象结构表示为一对花括号，其中包含零个或多个 名称/值对（或成员）。 名称是字符串。
因此，YAML-LD 中的所有映射键都必须是 string。
否则，将引发 mapping-key-error 错误，如以下示例所示：
"@context":
- https://json-ld.org/contexts/dollar-convenience.jsonld
- dbo: http://dbpedia.org/ontology/
dbp: http://dbpedia.org/property/
dbr: http://dbpedia.org/resource/
prov: http://www.w3.org/ns/prov#
xsd: http://www.w3.org/2001/XMLSchema#
dbp:discovered:
"@type": xsd:date
dbp:star: &iri
"@type": "@id"
prov:wasDerivedFrom: *iri
{ $id: dbr:Proxima_Centauri_b, $type: dbo:Planet, dbp:star: dbr:Proxima_Centauri }:
dbp:discovered: 2016-08-24
prov:wasDerivedFrom: https://dbpedia.org/page/Proxima_Centauri_b本节为非规范性内容。
JSON-LD 1.1 中的 @json 关键字将JSON 字面量定义为一个值对象，
其中
@type 为 @json，且 @value 包含 JSON 数据。处理器
会将此类值视为 JSON 字面量，而不会
将其进一步解释为 JSON-LD。请考虑以下示例。
"@context":
schema: https://schema.org/
dbr: http://dbpedia.org/resource/
"@id": dbr:Proxima_Centauri_b
schema:additionalProperty:
"@type": "@json"
"@value":
semiMajorAxis: 0.0485
orbitalPeriod: 11.186
equilibriumTemperature: 234
eccentricity: 0.11请看展开形式。
[
{
"@id": "http://dbpedia.org/resource/Proxima_Centauri_b",
"https://schema.org/additionalProperty": [
{
"@type": "@json",
"@value": {
"semiMajorAxis": 0.0485,
"orbitalPeriod": 11.186,
"equilibriumTemperature": 234,
"eccentricity": 0.11
}
}
]
}
]
虽然该关键词名为 @json，但它并不要求
@value 的值在 YAML-LD 中使用 JSON 语法书写。如本例所示，metadata
值对象在展开过程中会以其 JSON-LD 形式保留下来——这是该关键词所要求的。
YamlLdErrorCode 表示有效 YAML-LD
错误代码的集合，
它扩展了 JsonLdErrorCode
定义。
WebIDLenum YamlLdErrorCode {
"invalid-encoding",
"mapping-key-error",
"profile-error"
};
invalid-encodingmapping-key-errorprofile-error本节为非规范性内容。
参见 JSON-LD 1.1 中的安全考量
和 +yaml 结构化语法后缀。
本节为非规范性内容。
本节为非规范性内容。
关于在 [YAML] 中序列化
JSON
文档的一般互操作性考量，参见 YAML
以及 +yaml 结构化语法后缀的互操作性考量。
此处提供的考量和分析，包括互操作性 与安全考量，均基于 YAML 1.2.2 规范。
许多流行的 YAML 库默认使用 YAML 1.1 解析。
YAML 1.1 实现会导致互操作性问题；尤其是，
所谓的 “Norway problem” 会出现，因为 YAML 1.1 将
no、No、NO、yes、
on、off 以及类似值视为布尔值，
而 YAML 1.2 Core Schema 将它们视为普通字符串。
使用 YAML 1.1 库的 YAML-LD 处理器将无法通过一致性
测试，且不符合要求。
YAML-LD 内容可以很容易地嵌入 HTML [HTML] 中，方法是将其放入
<script> 元素，并将 type 属性设置为
application/ld+yaml，如下例所示。
<script type="application/ld+yaml">
"@context":
dbo: http://dbpedia.org/ontology/
dbp: http://dbpedia.org/property/
dbr: http://dbpedia.org/resource/
xsd: http://www.w3.org/2001/XMLSchema#
dbp:discovered:
"@type": xsd:date
"@id": dbr:Proxima_Centauri_b
"@type": dbo:Planet
dbp:discovered: "2016-08-24"
</script>
YAML 语法基于缩进。因此，在处理每个包含
YAML-LD 内容的 <script> 块时，
YAML-LD 处理器 MUST 为 YAML 解析保留该块的内容
原样，包括空白字符。
如果 YAML-LD <script> 标签包含具有多个YAML 流中的多个YAML 文档，则其中每个文档都必须被视为包含在单独的
<script>
标签中。有关详细信息，请参阅流处理。
本节已提交给互联网工程指导组 （IESG）审查、批准并在 IANA 注册。
本节描述了根据 [RFC6838] 注册上述媒体类型所需的信息
profile一个由空格分隔的非空 URI 列表，用于标识根据 [RFC6906] 应用于YAML-LD
流的特定约束或约定。
在不了解配置文件的情况下处理资源表示时，配置文件不会改变其语义，
因此了解和不了解具有配置文件的资源的客户端都可以安全地使用相同的
表示。客户端可以使用 profile 参数
在内容协商过程中表达其偏好。
如果给出了配置文件参数，服务器应该返回一个
遵循列表中其所识别配置文件的文档，
并且必须忽略列表中其无法
识别的配置文件。
建议配置文件 URI 可以解引用，并在该 URI 处提供
有用的文档。有关更多信息和背景，
请参阅 [RFC6906]。
本规范允许使用
中列出的
profile 参数，并另外定义以下参数：
http://www.w3.org/ns/json-ld#extended
当在 媒体类型
参数 [RFC4288]
中用作 HTTP Accept
标头字段 [RFC9110]时，
如果 profile 参数的值包含
空白等特殊字符，则必须用引号（"）将其
括起来；组合多个配置文件 URI 时需要这样做。
处理“profile”媒体类型参数时，务必 注意其值包含的是一个或多个 URI，而不是 IRI。因此，在某些情况下， 可能需要按照 [RFC3987] 的 第 3 节 IRI 与 URI 之间的关系 中的规定，在 IRI 和 URI 之间进行转换。
+yaml 相同。application/yaml 相同.yaml.yamlldapplication/yaml 相同application/yaml 相同本节为非规范性内容。
理论上，我们可以尝试将 YAML 注释收集到
JSON-LD 文档中。我们会定义一个特定谓词，例如
https://json-ld.org/yaml-ld/comment，并把
每个 # My comment 片段转换为 JSON-LD
文档中的一个 {"yaml-ld:comment": "My comment"} 片段。
但是，这会对实现产生以下影响：
本节为非规范性内容。
Gregg Kellogg 是 JSON-LD 和 YAML-LD 故事中的核心人物。 他十多年如一日地致力于 JSON-LD 和许多其他规范， 直到 2025 年 9 月 6 日去世前仍是如此。Gregg 对以精巧方式解决 难题充满热情，而这份热情也只有他愿意与他人协作、 并鼓励他人一同抵达目标的意愿能够超越。JSON-LD 以及 更广泛的链接数据社区，将永远感激 Gregg 在这些社区最具 形成意义的岁月中所作出的持续、细致且友善的贡献。
编辑们特别感谢以下个人对本规范的编写和编辑作出的重要 贡献：
Referenced in:
Referenced in:
4.1.2 注释
YAML-LD 流中的注释被视为空白。
有关更多详细信息，请参阅 YAML 与 JSON 的互操作性 注意事项。