【6】表示形式

6. 表示形式

在本规范中，DID文档的具体序列化形式称为表示形式。表示形式是通过称为生成的过程将数据模型序列化后创建的。表示形式通过称为解析的过程转化为数据模型。生成和解析过程使得信息可以从一种表示形式转换为另一种表示形式。本规范定义了JSON和JSON-LD的表示形式，开发者也可以使用其他能够表达数据模型的表示形式，如XML或YAML。以下部分定义了生成和解析的一般规则，以及JSON和JSON-LD的表示形式。

6.1 生成与解析

除了本规范中定义的表示形式外，实施者可以使用其他表示形式，前提是每种表示形式都被正确指定（包括对未列入DID规范注册表 [DID-SPEC-REGISTRIES]的属性进行互操作处理的规则）。更多信息见4.1 可扩展性。

所有表示形式的要求如下：

表示形式必须为 4. 数据模型中指定的所有数据类型定义确定性的生成和解析规则。
表示形式必须唯一地与IANA注册的媒体类型相关联。
表示形式必须为其媒体类型定义片段处理规则，并符合片段中定义的片段处理规则。
表示形式应使用数据模型数据类型的词法表示形式。例如，JSON和JSON-LD使用XML Schema的dateTime词法序列化来表示日期时间。表示形式可以选择使用不同的词法序列化来序列化数据模型的数据类型，只要解析过程回到数据模型时是无损的。例如，一些基于CBOR的表示形式使用整数来表示自Unix纪元以来的秒数来表达日期时间值。
表示形式可以定义特定于表示形式的条目，这些条目存储在表示形式特定的条目映射中，以便在生成和解析过程中使用。这些条目用于在解析或生成时，帮助确保无损转换。
为了最大限度地实现互操作性，表示形式规范的作者应在DID规范注册表 [DID-SPEC-REGISTRIES]中注册他们的表示形式。

所有符合规范的生成器的要求如下：

符合规范的生成器必须在生成过程中以DID文档数据模型和表示形式特定的条目映射作为输入。符合规范的生成器可以接受其他选项作为生成过程的输入。
符合规范的生成器必须序列化DID文档数据模型中的所有条目，以及表示形式特定的条目映射中没有明确处理规则的条目，并在生成过程完成后返回序列化结果。
符合规范的生成器必须在生成过程完成后返回与表示形式相关联的媒体类型字符串。
符合规范的生成器不得生成不符合规范的DID或DID文档。

所有符合规范的解析器的要求如下：

符合规范的解析器必须在解析过程中以表示形式和媒体类型字符串作为输入。符合规范的解析器可以接受其他选项作为解析过程的输入。
符合规范的解析器必须使用媒体类型输入字符串来确定DID文档的表示形式。
符合规范的解析器必须检测所有已知表示形式中的任何表示形式特定条目，并将该条目放入表示形式特定的条目映射中，在解析过程完成后返回。所有已知的表示形式特定条目的列表可在DID规范注册表 [DID-SPEC-REGISTRIES]中查阅。
符合规范的解析器必须将所有没有明确处理规则的非表示形式特定条目添加到DID文档数据模型中，并使用仅表示形式的数据类型处理规则，并在解析过程完成后返回DID文档数据模型。
符合规范的解析器在解析不符合规范的DID或DID文档时必须产生错误。

在这里插入图片描述

图 4 表示的生成与解析。参见：叙述描述。

注：表示之间的转换实现应通过在源表示上使用解析规则生成数据模型，然后使用生产规则将数据模型序列化为目标表示，或使用任何其他能生成相同目标表示的机制，在表示之间进行转换。

6.2 JSON

本节定义了 JSON 表示的生成与解析规则。

6.2.1 生成

生产 DID 文档、DID 文档数据结构和特定表示的条目映射必须根据以下生产规则序列化为 JSON 表示：

数据类型	JSON表示类型
map	JSON 对象，其中每个条目作为 JSON 对象的成员序列化，条目的键作为 JSON 字符串成员名，值根据其类型按本表定义进行序列化。
list	JSON 数组，其中列表的每个元素按顺序作为数组的值进行序列化，类型根据本表定义。
set	JSON 数组，其中集合的每个元素按顺序添加为数组的值，类型根据本表定义。
datetime	JSON 字符串，序列化为标准化为 UTC 00:00:00 的 XML 日期时间格式，且不包含秒以下的小数精度。例如：2020-12-20T19:17:47Z`.
string	JSON 字符串。
integer	不带小数或分数部分的 JSON 数字。
double	带有小数和分数部分的 JSON 数字。
boolean	JSON 布尔值。
null	JSON 空值字面量。

所有生成 JSON 表示的符合标准的生产者，建议确保其算法与 [INFRA] 规范中的 JSON 序列化规则保持一致，并遵循 JSON [RFC8259] 规范中关于数字精度的建议。

DID 文档的所有条目必须包含在根 JSON 对象中。条目可以包含符合上述值表示规则的额外数据子结构。在序列化 DID 文档时，符合标准的生产者必须为下游应用程序（如 7.1.2 DID 解析元数据中描述的）指定媒体类型为 application/did+json。

Example 21: Example DID document in JSON representation
{
    
    
  "id": "did:example:123456789abcdefghi",
  "authentication": [{
    
    
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }]
}

6.2.2 解析

DID 文档和 DID 文档数据结构的 JSON 表示必须根据以下解析规则进行反序列化到数据模型中：

JSON 表示类型	数据类型
JSON 对象	一个映射，JSON 对象的每个成员作为映射中的一个条目添加。每个条目的键设置为 JSON 对象成员名称。每个条目的值通过根据本表中定义的 JSON 表示类型转换 JSON 对象成员值来设置。由于 JSON 对象未指定顺序，因此不保证插入顺序。
JSON 数组，其中数据模型条目值为列表或未知	一个列表，JSON 数组的每个值按顺序添加到列表中，根据数组值的 JSON 表示类型进行转换，如本表所定义。
JSON 数组，其中数据模型条目值为集合	一个集合，JSON 数组的每个值按顺序添加到集合中，根据数组值的 JSON 表示类型进行转换，如本表所定义。
JSON 字符串，其中数据模型条目值为日期时间	一个日期时间。
JSON 字符串，其中数据模型条目值类型为字符串或未知	一个字符串。
JSON 数字，无小数或分数部分	一个整数。
JSON 数字，具有小数和分数部分，或者当条目值为双精度浮点数时，无论是否包含分数部分	一个双精度浮点数。
JSON 布尔值	一个布尔值。
JSON null 字面量	一个 null 值。

所有创建符合规范的解析器并生成 JSON 表示的实现者建议确保其算法与 [INFRA] 规范中的 JSON 转换规则以及 JSON [RFC8259] 规范中关于数字的精度建议保持一致。

如果符合规范的解析器可获得媒体类型信息，并且媒体类型值为 application/did+json，则正在解析的数据结构是 DID 文档，根元素必须是一个 JSON 对象，其中对象的所有成员都是 DID 文档的条目。对于根元素不是 JSON 对象的 DID 文档，符合规范的解析器必须报告错误。

6.3 JSON-LD

JSON-LD [JSON-LD11] 是一种基于 JSON 的格式，用于序列化链接数据。本节定义了 JSON-LD 表示的生成和解析规则。

JSON-LD 表示定义了以下表示特定条目：

@context

JSON-LD 上下文可以是一个字符串或一个列表，包含任意组合的字符串和/或有序映射。

6.3.1 生成

DID 文档、DID 文档数据结构以及表示特定条目映射必须根据 JSON 表示的生成规则序列化为 JSON-LD 表示，具体定义见 6.2 JSON。

除了使用 JSON 表示的生成规则外，JSON-LD 生成必须包含表示特定的 @context 条目。@context 的序列化值必须是 JSON 字符串 https://www.w3.org/ns/did/v1，或者是一个 JSON 数组，其中第一个项目为 JSON 字符串 https://www.w3.org/ns/did/v1，后续项目根据 JSON 表示的生成规则序列化。

示例 22：有效的简单 @context 条目序列化

{
    
    
  "@context": "https://www.w3.org/ns/did/v1",
  ...
}

示例 23：有效的分层 @context 条目序列化

{
    
    
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://did-method-extension.example/v1"
  ],
  ...
}

所有创建符合规范的生产者并生成 JSON-LD 表示的实现者建议确保其算法生成有效的 JSON-LD [JSON-LD11] 文档。无效的 JSON-LD 文档将导致 JSON-LD 处理器停止并报告错误。

为了实现不同表示之间的互操作性，所有 JSON-LD 上下文及其术语应在 DID 规范注册表中注册 [DID-SPEC-REGISTRIES]。

生成 JSON-LD 表示的符合规范的生产者不应生成包含未通过 @context 定义的术语的 DID 文档，因为符合规范的解析器被期望移除未知术语。在序列化 DID 文档的 JSON-LD 表示时，符合规范的生产者必须为下游应用指定媒体类型 application/did+ld+json。

6.3.2 解析

DID 文档及任何通过 JSON-LD 表示表达的 DID 文档数据结构必须根据 JSON 表示的解析规则反序列化为数据模型，具体定义见 6.2 JSON。

所有创建符合规范的解析器并解析 JSON-LD 表示的实现者建议确保其算法仅接受有效的 JSON-LD [JSON-LD11] 文档。无效的 JSON-LD 文档将导致 JSON-LD 处理器停止并报告错误。

处理 JSON-LD 表示的符合规范的解析器应删除所有未通过 @context 定义的 DID 文档中的术语。