VCALM v1.0

摘要

可验证凭证提供了一种在 Web 上表达凭证的机制，这种方式具有加密安全性、尊重隐私，并且可由机器验证。本规范提供了数据模型和 HTTP 协议，用于签发、验证、出示和管理此类生态系统中使用的数据。

目标	描述
模块化	实现者只需实现其用例所需的 API，从而在签发、验证和出示之间实现模块化。
简单性	API 数量和可选性保持在最低限度，以确保它们易于从安全角度实现和审计。
可组合性	API 被设计为可组合的，使复杂流程能够通过少量简单的 API 原语实现。
可扩展性	API 设计预期并支持对 API 端点的扩展，以便在基础 API 平台之上进行实验并添加增值服务。

VCALM OAuth 2.0 作用域语法
scope = operation ":" path-absolute（定义于 [RFC3986]） operation = "read" / "write"

本节包含在创建一致实现时应遵循的 HTTP API 端点定义和实现指南。

本节按预期可调用端点的组件，概述 VC-API 中的所有端点。如果某个组件下面没有列表，则意味着 VC-API 当前未为该组件指定任何端点。

下面列出了预期由签发者协调器公开的所有端点，以及预期调用该端点的组件。

端点	预期调用方	定义
GET /interactions/{interactionId}	持有所提供 URL 的任何人	3.7.1 交互 URL 格式
POST /callbacks/{localCallbackId}	工作流服务	3.6.7 交换步骤回调

下面列出了预期由签发者服务公开的所有端点，以及预期调用该端点的组件。

端点	预期调用方	定义
POST /credentials/issue	签发者协调器、工作流服务	3.2.1 签发凭证
GET /credentials/{id}	签发者协调器、持有者协调器、工作流服务	3.2.2 获取特定凭证
DELETE /credentials/{id}	签发者协调器、持有者协调器	3.2.3 删除特定凭证

下面列出了预期由验证者协调器公开的所有端点，以及预期调用该端点的组件。

端点	预期调用方	定义
GET /interactions/{interactionId}	持有所提供 URL 的任何人	3.7.1 交互 URL 格式
POST /callbacks/{localCallbackId}	工作流服务	3.6.7 交换步骤回调

下面列出了预期由验证者服务公开的所有端点，以及预期调用该端点的组件。

端点	预期调用方	定义
POST /credentials/verify	验证者协调器、工作流服务	3.3.1 验证凭证
POST /presentations/verify	验证者协调器、工作流服务	3.3.2 验证表达
POST /challenges	验证者协调器、工作流服务	3.3.3 创建质询

下面列出了预期由持有者协调器公开的所有端点，以及预期调用该端点的组件。

端点	预期调用方	定义
GET /interactions/{interactionId}	持有所提供 URL 的任何人	3.7.1 交互 URL 格式
POST /callbacks/{localCallbackId}	工作流服务	3.6.7 交换步骤回调

下面列出了预期由持有者服务公开的所有端点，以及预期调用该端点的组件。

端点	预期调用方	定义
POST /credentials/derive	持有者协调器、工作流服务	3.5.1 派生凭证
GET /credentials/{id}	签发者协调器、持有者协调器、工作流服务	3.2.2 获取特定凭证
DELETE /credentials/{id}	签发者协调器、持有者协调器	3.2.3 删除特定凭证
GET /presentations	持有者协调器、工作流服务	3.5.3 获取表达
POST /presentations	持有者协调器、工作流服务	3.5.2 创建表达
GET /presentations/{id}	持有者协调器、工作流服务	3.5.4 获取特定表达
DELETE /presentations/{id}	持有者协调器	3.5.5 删除特定表达

下面列出了预期由状态服务公开的所有端点，以及预期调用该端点的组件。

端点	预期调用方	定义
POST /status-lists	签发者服务	C.1 创建状态列表
GET /status-lists/{id}	公开	C.2 获取状态列表
POST /credentials/status	签发者服务	C.3 更新状态

下面列出了预期由工作流服务公开的所有端点，以及预期调用该端点的组件。

端点	预期调用方	定义
POST /workflows	管理员	3.6.1 创建工作流
GET /workflows/{localWorkflowId}	管理员	3.6.2 获取工作流配置
POST /workflows/{localWorkflowId}/exchanges	协调器	3.6.3 创建交换
GET /workflows/{localWorkflowId}/exchanges/{localExchangeId}	协调器	3.6.6 获取交换状态
POST /workflows/{localWorkflowId}/exchanges/{localExchangeId}	任何人	3.6.5 参与交换
GET /workflows/{localWorkflowId}/exchanges/{localExchangeId}/protocols	验证者协调器、持有者协调器	3.6.4 获取交换协议
POST /{inviteId}/invite-request/response	POST 到包含 /interactions/{interactionId} 的 URL 的任何人	3.7.4 交互协议响应

以下 API 被定义用于签发 Verifiable Credential：

端点	描述
GET /credentials/{id}	按 ID 获取 credential 或 verifiable credential。若要获取未设置 credential.id 但具有相关 credentialId 值的 credential，请改为传递 credentialId。
DELETE /credentials/{id}	按 ID 删除 credential 或 verifiable credential。若要删除未设置 credential.id 但具有相关 credentialId 值的 credential，请改为传递 credentialId。
POST /credentials/issue	签发 credential，并在响应主体中返回它。
POST /credentials/status	更新已签发 credential 的状态
POST /status-lists	创建新的状态列表
GET /status-lists/{id}	检索状态列表凭证

此端点用于签发可验证凭证。

注：已签发 credential 的媒体类型

若要签发媒体类型不是 application/vc 的 credentials，例如 application/mdoc、application/vc+sd-jwt、 application/vcb;barcode-format=qr_code 或 application/vcb;barcode-format=pdf417，可以在响应中返回一个 EnvelopedVerifiableCredential。

POST /credentials/issue - 签发 credential，并在响应主体中返回它。

/credentials/issue 端点在接收 POST 时使用以下模式：

属性描述

属性	描述
`credential` [object]	拟签发的 W3C Verifiable Credential。它MUST是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项MUST是字符串。 `id` [string] credential 的 ID。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 对象，或 { "type": "array", "items": { "type": "object" } }
`options` [object]	用于指定如何签发 credential 的选项。它MUST是如下形式的对象： `mandatoryPointers` [array] 与选择性披露方案一起使用，用于指定必须披露的语句。`mandatoryPointers` 数组中的每一项MUST是字符串。 `credentialId` [string] 可用于标识 credential 的 URI，可在 API 中用于引用已签发的 verifiable credential。如果 issuer coordinator 未提供 credentialId，issuer service 将从 credential.id 自动填充其值。如果既未提供 credentialId，也未提供 credential.id，则在该 credential 签发后将无法引用它，也无法处理重复错误。如果设置了 credential.id 属性， issuer coordinator SHOULD NOT设置 credentialId，也不应使用 credentialId 替代 credential.id；相反， credentialId 是一种在未设置 id 属性（即 credential.id）时标识 credential 的方式。如果 issuer coordinator 未提供 credentialId，issuer service SHOULD NOT自动生成 credentialId，因为如果客户端从未收到结果，这样做可能会造成分区错误。

credential [object]

拟签发的 W3C Verifiable Credential。它MUST是如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项MUST是字符串。

id [string]

credential 的 ID。

type [array]

credential 的 JSON-LD type。type 数组中的每一项 MUST是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

对象，或

{
  "type": "array",
  "items": {
    "type": "object"
  }
}

options [object]

用于指定如何签发 credential 的选项。它MUST是如下形式的对象：

mandatoryPointers [array]: 与选择性披露方案一起使用，用于指定必须披露的语句。mandatoryPointers 数组中的每一项MUST是字符串。
credentialId [string]: 可用于标识 credential 的 URI，可在 API 中用于引用已签发的 verifiable credential。如果 issuer coordinator 未提供 credentialId，issuer service 将从 credential.id 自动填充其值。如果既未提供 credentialId，也未提供 credential.id，则在该 credential 签发后将无法引用它，也无法处理重复错误。如果设置了 credential.id 属性， issuer coordinator SHOULD NOT设置 credentialId，也不应使用 credentialId 替代 credential.id；相反， credentialId 是一种在未设置 id 属性（即 credential.id）时标识 credential 的方式。如果 issuer coordinator 未提供 credentialId，issuer service SHOULD NOT自动生成 credentialId，因为如果客户端从未收到结果，这样做可能会造成分区错误。

/credentials/issue 端点在接收 POST 时可能产生以下任一响应：

响应主体

201

响应	主体
201	Credential 已成功签发！ content-type: application/json 如下形式的对象： `IssueCredentialResponse` [object] 成功请求 verifiable credential 后返回的格式。它MUST是如下形式的对象： `verifiableCredential` [object] 如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST是字符串。 `id` [string] credential 的 ID。此属性MAY为空。如果未提供 id 属性，issuer SHOULD NOT自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项MUST是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它MUST是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。，或一个用于在 verifiable presentation 中将 enveloped verifiable credential 与 verifiableCredential 属性关联的对象。它MUST是如下形式的对象： `@context` [array] enveloped verifiable credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST是字符串。 `id` [string] 这MUST是一个 "data:" scheme URL [RFC2397]，使用封装安全方案表达受保护的 verifiable credential。 `type` [string] 这MUST是 EnvelopedVerifiableCredential。
400	由于以下原因之一，无法处理请求： - 提供的 'issuer' 值与预期配置不匹配。 - 导致 Bad Request 的其他条件。

Credential 已成功签发！

content-type: application/json

如下形式的对象：

IssueCredentialResponse [object]

成功请求 verifiable credential 后返回的格式。它MUST是如下形式的对象：

verifiableCredential [object]

如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项 MUST是字符串。

id [string]

credential 的 ID。此属性MAY为空。如果未提供 id 属性，issuer SHOULD NOT自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。

type [array]

credential 的 JSON-LD type。type 数组中的每一项MUST是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它MUST是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

，或一个用于在 verifiable presentation 中将 enveloped verifiable credential 与 verifiableCredential 属性关联的对象。它MUST是如下形式的对象：

@context [array]: enveloped verifiable credential 的 JSON-LD context。 @context 数组中的每一项 MUST是字符串。
id [string]: 这MUST是一个 "data:" scheme URL [RFC2397]，使用封装安全方案表达受保护的 verifiable credential。
type [string]: 这MUST是 EnvelopedVerifiableCredential。

400 由于以下原因之一，无法处理请求： - 提供的 'issuer' 值与预期配置不匹配。 - 导致 Bad Request 的其他条件。

如果某个用例要求 issuer instance 将多个 proofs 附加到所提供的 credential，则该 instance MUST在对 /credentials/issue 端点的单次调用响应中附加所有这些 proofs。

如果提供的 credential 已经包含一个或多个 proofs，则其行为由 issuer instance 的配置决定。issuing instance SHOULD 被配置为以下列方式之一处理现有 proofs：

证明集：将新 proofs 追加到调用方提供的现有 proofs 列表中，必要时先将任何现有单一 proof 转换为列表。在这里，新 proofs 不绑定到任何现有 proofs；新 proofs 与调用方先前提供的 proofs 并行存在。
证明链：追加新 proofs 以创建或扩展现有 proof chain。在这里，proofs 按特定顺序链接，可能使用 previousProof 属性建立链关系。
错误处理：如果提供了包含现有 proof 值的 credential 值，而该 instance 被配置为只接受没有现有 proofs 的 credentials，则返回错误。

使用的具体方法取决于 issuer instance 的配置以及 verifiable credential 的预期用例。

GET /credentials/{id} - 按 ID 获取 credential 或 verifiable credential。若要获取未设置 credential.id 但具有相关 credentialId 值的 credential，请改为传递 credentialId。

/credentials/{id} 端点在接收 GET 时可能产生以下任一响应：

响应	主体
200	Credential 已检索 content-type: application/json 成功请求 verifiable credential 后返回的格式。它MUST是如下形式的对象： `verifiableCredential` [object] 如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项MUST是字符串。 `id` [string] credential 的 ID。此属性MAY为空。如果未提供 id 属性，issuer SHOULD NOT自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它MUST是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。，或一个用于在 verifiable presentation 中将 enveloped verifiable credential 与 verifiableCredential 属性关联的对象。它MUST是如下形式的对象： `@context` [array] enveloped verifiable credential 的 JSON-LD context。 `@context` 数组中的每一项MUST是字符串。 `id` [string] 这MUST是一个 "data:" scheme URL [RFC2397]，使用封装安全方案表达受保护的 verifiable credential。 `type` [string] 这MUST是 EnvelopedVerifiableCredential。
400	错误请求
401	未授权
404	未找到 credential
410	已消失！这里没有数据
418	我是茶壶——MUST不得在双方预先安排的场景之外返回

签发者服务或持有者服务可能会长期存储已签发的可验证凭证。这样做时，删除此类可验证凭证可能很有用；例如，签发者可能由于监管要求而需要这样做，例如被遗忘权。有关从系统中移除可验证凭证的更多考量，见第 B.3 删除节。

DELETE /credentials/{id} - 按 ID 删除 credential 或 verifiable credential。若要删除未设置 credential.id 但具有相关 credentialId 值的 credential，请改为传递 credentialId。

/credentials/{id} 端点在接收 DELETE 时可能产生以下任一响应：

响应	主体
202	Credential 已删除——默认使用 202，因为假定会进行软删除并需要处理时间
400	错误请求
401	未授权
404	未找到 credential
410	已消失！这里没有数据

以下 API 被定义用于验证 Verifiable Credential：

端点	描述
POST /credentials/verify	验证 verifiableCredential，并在响应主体中返回 verificationResult。
POST /presentations/verify	验证 Presentation 及其包含的所有 Verifiable Credentials，并返回详细的验证结果。
POST /challenges	向此端点传递空主体会创建并在响应主体中返回一个 challenge 字符串。

此端点用于验证可验证凭证。

注：验证 credential 的媒体类型

若要验证媒体类型不是 application/vc 的 credentials，例如 application/mdoc、application/vc+sd-jwt、 application/vcb;barcode-format=qr_code 或 application/vcb;barcode-format=pdf417，可以在请求中提供一个 EnvelopedVerifiableCredential。

POST /credentials/verify - 验证 verifiableCredential，并在响应主体中返回 verificationResult。

/credentials/verify 端点在接收 POST 时使用以下模式之一：

属性描述

属性	描述
`verifiableCredential` [object]	如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果未提供 id 属性， issuer SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。
`options` [object]	用于指定如何验证 credential 的选项。它 MUST 是如下形式的对象： `returnResults` [boolean] 在响应中包含所执行的每个验证步骤的结果，例如验证各个 proofs、statuses 和 schemas。 `returnProblemDetails` [boolean] 在响应中包含 ProblemDetails 错误和警告。 `returnCredential` [boolean] 是否应在响应中返回已验证的 credential？如果为 true，则已验证的 credential 应以其被验证时的形式返回。如果为 false 或未提供，则不应返回已验证的 credential。

verifiableCredential [object]

如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

credential 的 ID。此属性 MAY 为空。如果未提供 id 属性， issuer SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。

type [array]

credential 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

options [object]

用于指定如何验证 credential 的选项。它 MUST 是如下形式的对象：

returnResults [boolean]: 在响应中包含所执行的每个验证步骤的结果，例如验证各个 proofs、statuses 和 schemas。
returnProblemDetails [boolean]: 在响应中包含 ProblemDetails 错误和警告。
returnCredential [boolean]: 是否应在响应中返回已验证的 credential？如果为 true，则已验证的 credential 应以其被验证时的形式返回。如果为 false 或未提供，则不应返回已验证的 credential。

或者，/credentials/verify 端点也可以使用以下模式：

属性描述

属性	描述
`verifiableCredential` [object]	用于在 verifiable presentation 中将 enveloped verifiable credential 与 verifiableCredential 属性关联的对象。它 MUST 是如下形式的对象： `@context` [array] enveloped verifiable credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] 这 MUST 是一个 "data:" scheme URL [RFC2397]，用于使用封装安全方案表达受保护的 verifiable credential。 `type` [string] 这 MUST 是 EnvelopedVerifiableCredential。
`options` [object]	用于指定如何验证 credential 的选项。它 MUST 是如下形式的对象： `returnResults` [boolean] 在响应中包含所执行的每个验证步骤的结果，例如验证各个 proofs、statuses 和 schemas。 `returnProblemDetails` [boolean] 在响应中包含 ProblemDetails 错误和警告。 `returnCredential` [boolean] 是否应在响应中返回已验证的 credential？如果为 true，则已验证的 credential 应以其被验证时的形式返回。如果为 false 或未提供，则不应返回已验证的 credential。

verifiableCredential [object]

用于在 verifiable presentation 中将 enveloped verifiable credential 与 verifiableCredential 属性关联的对象。它 MUST 是如下形式的对象：

@context [array]: enveloped verifiable credential 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。
id [string]: 这 MUST 是一个 "data:" scheme URL [RFC2397]，用于使用封装安全方案表达受保护的 verifiable credential。
type [string]: 这 MUST 是 EnvelopedVerifiableCredential。

options [object]

用于指定如何验证 credential 的选项。它 MUST 是如下形式的对象：

returnResults [boolean]: 在响应中包含所执行的每个验证步骤的结果，例如验证各个 proofs、statuses 和 schemas。
returnProblemDetails [boolean]: 在响应中包含 ProblemDetails 错误和警告。
returnCredential [boolean]: 是否应在响应中返回已验证的 credential？如果为 true，则已验证的 credential 应以其被验证时的形式返回。如果为 false 或未提供，则不应返回已验证的 credential。

/credentials/verify 端点在接收 POST 时可能产生以下任一响应：

响应主体

200

响应	主体
200	Verifiable Credential 已成功验证！ content-type: application/json 用于报告 VerifiableCredential 验证过程结果的对象。它 MUST 是如下形式的对象： `verified` [boolean] VerifiableCredential 的整体验证断言。如果在验证过程中未检测到错误，则设为 `true`；否则为 `false`。有关错误、警告和验证步骤的更多指导，见错误处理章节。 `credential` [object] 一个对象 `problemDetails` [array] 由 ProblemDetails 对象组成的数组。`problemDetails` 数组中的每一项 MUST 是如下形式的对象： `type` [string] 标识问题类型的 URL。 `title` [string] 针对问题的简短但具体的人类可读字符串。 `detail` [string] 针对问题的较长人类可读字符串。 `results` [object] 作为更详细输出包含的验证结果。键映射到 Verifiable Credential Data Model 中的属性。它 MUST 是如下形式的对象： `validFrom` [object] 验证 validFrom 属性的结果（若该属性存在于 VerifiableCredential 中）。它 MUST 是如下形式的对象： `verified` [boolean] 验证结果。 `input` [string] validFrom 值。 `validUntil` [object] 验证 validUntil 属性的结果（若该属性存在于 VerifiableCredential 中）。它 MUST 是如下形式的对象： `verified` [boolean] 验证结果。 `input` [string] validUntil 值。 `credentialSchema` [array] 验证 credentialSchema 对象的结果（若有）。 `credentialSchema` 数组中的每一项 MUST 是验证 credentialSchema 对象的结果。它 MUST 是如下形式的对象： `verified` [boolean] 验证 credentialSchema 对象的结果。 `input` [object] 一个对象 `credentialStatus` [array] 验证 credentialStatus 对象的结果（若有）。 `credentialStatus` 数组中的每一项 MUST 是验证 credentialStatus 对象的结果。它 MUST 是如下形式的对象： `value` [integer] 与状态条目关联的具体状态值。 `verified` [boolean] 验证 credentialStatus 对象的结果。 `input` [object] 一个对象 `proof` [array] 验证 proof 对象的结果（若有）。`proof` 数组中的每一项 MUST 是验证 proof 对象的结果。它 MUST 是如下形式的对象： `verified` [boolean] 验证 proof 对象的结果。 `input` [object] 一个对象
400	输入无效！

Verifiable Credential 已成功验证！

content-type: application/json

用于报告 VerifiableCredential 验证过程结果的对象。它 MUST 是如下形式的对象：

verified [boolean]

VerifiableCredential 的整体验证断言。如果在验证过程中未检测到错误，则设为 true；否则为 false。有关错误、警告和验证步骤的更多指导，见错误处理章节。

credential [object]

一个对象

problemDetails [array]

由 ProblemDetails 对象组成的数组。problemDetails 数组中的每一项 MUST 是如下形式的对象：

type [string]: 标识问题类型的 URL。
title [string]: 针对问题的简短但具体的人类可读字符串。
detail [string]: 针对问题的较长人类可读字符串。

results [object]

作为更详细输出包含的验证结果。键映射到 Verifiable Credential Data Model 中的属性。它 MUST 是如下形式的对象：

validFrom [object]

验证 validFrom 属性的结果（若该属性存在于 VerifiableCredential 中）。它 MUST 是如下形式的对象：

verified [boolean]: 验证结果。
input [string]: validFrom 值。

validUntil [object]

验证 validUntil 属性的结果（若该属性存在于 VerifiableCredential 中）。它 MUST 是如下形式的对象：

verified [boolean]: 验证结果。
input [string]: validUntil 值。

credentialSchema [array]

验证 credentialSchema 对象的结果（若有）。 credentialSchema 数组中的每一项 MUST 是验证 credentialSchema 对象的结果。它 MUST 是如下形式的对象：

verified [boolean]: 验证 credentialSchema 对象的结果。
input [object]: 一个对象

credentialStatus [array]

验证 credentialStatus 对象的结果（若有）。 credentialStatus 数组中的每一项 MUST 是验证 credentialStatus 对象的结果。它 MUST 是如下形式的对象：

value [integer]: 与状态条目关联的具体状态值。
verified [boolean]: 验证 credentialStatus 对象的结果。
input [object]: 一个对象

proof [array]

验证 proof 对象的结果（若有）。proof 数组中的每一项 MUST 是验证 proof 对象的结果。它 MUST 是如下形式的对象：

verified [boolean]: 验证 proof 对象的结果。
input [object]: 一个对象

400 输入无效！

此端点用于验证可验证表达，并且默认验证其中包含的所有可验证凭证。

验证过程包括：

验证表达自身的 proof（包括 domain 和 challenge 验证）
验证每个所含可验证凭证的 proof、status 和有效期限
检查表达中的 holder 是否与表达 proof 中使用的 verification method 匹配

业务规则验证（例如验证 credential subjects 是否与 presentation holder 匹配，或关于谁可以出示哪些 credentials 的授权策略）不在此验证端点范围内，应由调用应用程序执行。

POST /presentations/verify - 验证 Presentation 及其包含的所有 Verifiable Credentials，并返回详细验证结果。

/presentations/verify 端点在接收 POST 时使用以下模式之一：

属性描述

属性	描述
`verifiablePresentation` [object]	如下形式的对象： `@context` [array] presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] presentation 的 ID。 `type` [array] presentation 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] Verifiable Credentials。`verifiableCredential` 数组中的每一项 MUST 是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。 `proof` [object] 包含 challenge 和 domain 的 Data Integrity Proof，如 W3C VC Data Integrity 规范所定义。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `challenge` [string] verifier 选择的值，用于缓解认证 proof 重放攻击。 `domain` [string] proof 的 domain，用于将其使用限制到特定目标。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。
`options` [object]	用于指定如何验证 presentation 的选项。实现 MAY 用附加属性扩展此对象，以控制验证行为。常见扩展可以包括用于禁用对所含 credentials 的验证的选项（例如用于调试，或仅需要 presentation 级验证时）；对 credential 各方面验证的细粒度控制，例如 status checks、validity period validation、proof verification 和 schema validation；以及针对 presentation 中特定 credentials 的选择性验证控制。当 credential verification 被禁用或受限时，此 API 是可组合的；可以使用 /credentials/verify 端点单独验证 individual credentials。它 MUST 是如下形式的对象： `challenge` [string] 由 proof 请求方提供的 challenge；例如 `6e62f66e-67de-11eb-b490-ef3eeefa55f2`。 `domain` [string] proof 的预期有效 domain；例如 `website.example`。 `returnPresentation` [boolean] 是否返回已验证的 presentation。如果为 true，则已验证的 presentation MUST 被返回。如果为 false 或未提供，则已验证的 presentation MUST NOT 被返回。

verifiablePresentation [object]

如下形式的对象：

@context [array]

presentation 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

presentation 的 ID。

type [array]

presentation 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

holder [object]

一个对象

verifiableCredential [array]

Verifiable Credentials。verifiableCredential 数组中的每一项 MUST 是如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。

type [array]

credential 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

proof [object]

包含 challenge 和 domain 的 Data Integrity Proof，如 W3C VC Data Integrity 规范所定义。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
challenge [string]: verifier 选择的值，用于缓解认证 proof 重放攻击。
domain [string]: proof 的 domain，用于将其使用限制到特定目标。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

options [object]

用于指定如何验证 presentation 的选项。实现 MAY 用附加属性扩展此对象，以控制验证行为。常见扩展可以包括用于禁用对所含 credentials 的验证的选项（例如用于调试，或仅需要 presentation 级验证时）；对 credential 各方面验证的细粒度控制，例如 status checks、validity period validation、proof verification 和 schema validation；以及针对 presentation 中特定 credentials 的选择性验证控制。当 credential verification 被禁用或受限时，此 API 是可组合的；可以使用 /credentials/verify 端点单独验证 individual credentials。它 MUST 是如下形式的对象：

challenge [string]: 由 proof 请求方提供的 challenge；例如 6e62f66e-67de-11eb-b490-ef3eeefa55f2。
domain [string]: proof 的预期有效 domain；例如 website.example。
returnPresentation [boolean]: 是否返回已验证的 presentation。如果为 true，则已验证的 presentation MUST 被返回。如果为 false 或未提供，则已验证的 presentation MUST NOT 被返回。

或者，/presentations/verify 端点也可以使用以下模式：

属性描述

属性	描述
`presentation` [object]	不带 proof 的 JSON-LD Verifiable Presentation。它 MUST 是如下形式的对象： `@context` [array] presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] presentation 的 ID。 `type` [array] presentation 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] Verifiable Credentials。`verifiableCredential` 数组中的每一项 MUST 是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。

presentation [object]

不带 proof 的 JSON-LD Verifiable Presentation。它 MUST 是如下形式的对象：

@context [array]

presentation 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

presentation 的 ID。

type [array]

presentation 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

holder [object]

一个对象

verifiableCredential [array]

Verifiable Credentials。verifiableCredential 数组中的每一项 MUST 是如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

type [array]

credential 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

属性描述

属性	描述
`verifiablePresentation` [object]	用于表达 enveloped verifiable presentation 的对象。它 MUST 是如下形式的对象： `@context` [array] enveloped verifiable presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] 这 MUST 是一个 "data:" scheme URL [RFC2397]，用于使用封装安全方案表达受保护的 verifiable presentation。 `type` [string] 这 MUST 是 EnvelopedVerifiablePresentation。
`options` [object]	用于指定如何验证 presentation 的选项。实现 MAY 用附加属性扩展此对象，以控制验证行为。常见扩展可以包括用于禁用对所含 credentials 的验证的选项（例如用于调试，或仅需要 presentation 级验证时）；对 credential 各方面验证的细粒度控制，例如 status checks、validity period validation、proof verification 和 schema validation；以及针对 presentation 中特定 credentials 的选择性验证控制。当 credential verification 被禁用或受限时，此 API 是可组合的；可以使用 /credentials/verify 端点单独验证 individual credentials。它 MUST 是如下形式的对象： `challenge` [string] 由 proof 请求方提供的 challenge；例如 `6e62f66e-67de-11eb-b490-ef3eeefa55f2`。 `domain` [string] proof 的预期有效 domain；例如 `website.example`。 `returnPresentation` [boolean] 是否返回已验证的 presentation。如果为 true，则已验证的 presentation MUST 被返回。如果为 false 或未提供，则已验证的 presentation MUST NOT 被返回。

verifiablePresentation [object]

用于表达 enveloped verifiable presentation 的对象。它 MUST 是如下形式的对象：

@context [array]: enveloped verifiable presentation 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。
id [string]: 这 MUST 是一个 "data:" scheme URL [RFC2397]，用于使用封装安全方案表达受保护的 verifiable presentation。
type [string]: 这 MUST 是 EnvelopedVerifiablePresentation。

options [object]

challenge [string]: 由 proof 请求方提供的 challenge；例如 6e62f66e-67de-11eb-b490-ef3eeefa55f2。
domain [string]: proof 的预期有效 domain；例如 website.example。
returnPresentation [boolean]: 是否返回已验证的 presentation。如果为 true，则已验证的 presentation MUST 被返回。如果为 false 或未提供，则已验证的 presentation MUST NOT 被返回。

/presentations/verify 端点在接收 POST 时可能产生以下任一响应：

响应	主体
200	验证过程已成功完成。响应主体包含详细结果，指示 presentation 及其包含的 credentials 是通过还是未通过验证。 <code>200</code> 状态表示验证过程本身成功，无论 presentation 和/或 credentials 被判定为有效还是无效。 content-type: application/json 用于报告 VerifiablePresentation 验证过程结果的对象。它 MUST 是如下形式的对象： `verified` [boolean] VerifiablePresentation 的整体验证断言。如果 VerifiablePresentation 和所有已检查的 VerifiableCredentials 均通过验证，则设为 `true`；否则为 `false`。有关错误和警告，以及验证和校验步骤的更多指导，见错误处理章节。 `verifiablePresentation` [object] 一个对象 `problemDetails` [array] 由 presentation 级整体问题的 ProblemDetails 对象组成的数组。 `problemDetails` 数组中的每一项 MUST 是如下形式的对象： `type` [string] 标识问题类型的 URL。 `title` [string] 针对问题的简短但具体的人类可读字符串。 `detail` [string] 针对问题的较长人类可读字符串。 `results` [object] 默认情况下，包含 VerifiablePresentation 和其中所有 VerifiableCredentials 的详细验证结果。键映射到 Verifiable Credential Data Model 中受验证约束的属性。它 MUST 是如下形式的对象： `presentation` [object] 特定于 VerifiablePresentation 本身（不包括其所含 VerifiableCredentials）的验证结果。它 MUST 是如下形式的对象： `challenge` [object] 如果在验证选项中提供，则为验证所有所提供 proofs 的 security challenge 的结果。它 MUST 是如下形式的对象： `verified` [boolean] 验证所有所提供 proofs 的 security challenge 的结果。 `input` [string] challenge 输入字符串。 `domain` [object] 如果在验证选项中提供，则为验证所有所提供 proofs 的 security domain 的结果。它 MUST 是如下形式的对象： `verified` [boolean] 验证所有所提供 proofs 的 security domain 的结果。 `input` [string] security domain 输入字符串。 `holder` [object] 验证 holder 的结果（若有）。它 MUST 是如下形式的对象： `verified` [boolean] 验证 holder 的结果。 `input` [string] holder 输入字符串。 `proof` [array] 验证 proof 对象的结果（若有）。 `proof` 数组中的每一项 MUST 是验证 proof 对象的结果。它 MUST 是如下形式的对象： `verified` [boolean] 验证 proof 对象的结果。 `input` [object] 一个对象 `problemDetails` [array] 特定于此 proof 的问题。`problemDetails` 数组中的每一项 MUST 是如下形式的对象： `type` [string] 标识问题类型的 URL。 `title` [string] 针对问题的简短但具体的人类可读字符串。 `detail` [string] 针对问题的较长人类可读字符串。 `credentials` [array] VerifiablePresentation 中每个 VerifiableCredential 的详细验证结果。`credentials` 数组中的每一项 MUST 是用于报告 VerifiableCredential 验证过程结果的对象。它 MUST 是如下形式的对象： `verified` [boolean] VerifiableCredential 的整体验证断言。如果在验证过程中未检测到错误，则设为 `true`；否则为 `false`。有关错误、警告和验证步骤的更多指导，见错误处理章节。 `credential` [object] 一个对象 `problemDetails` [array] 由 ProblemDetails 对象组成的数组。 `problemDetails` 数组中的每一项 MUST 是如下形式的对象： `type` [string] 标识问题类型的 URL。 `title` [string] 针对问题的简短但具体的人类可读字符串。 `detail` [string] 针对问题的较长人类可读字符串。 `results` [object] 作为更详细输出包含的验证结果。键映射到 Verifiable Credential Data Model 中的属性。它 MUST 是如下形式的对象： `validFrom` [object] 验证 validFrom 属性的结果，若存在于 VerifiableCredential 中。它 MUST 是如下形式的对象： `verified` [boolean] 验证结果。 `input` [string] validFrom 值。 `validUntil` [object] 验证 validUntil 属性的结果，若存在于 VerifiableCredential 中。它 MUST 是如下形式的对象： `verified` [boolean] 验证结果。 `input` [string] validUntil 值。 `credentialSchema` [array] 验证 credentialSchema 对象的结果（若有）。`credentialSchema` 数组中的每一项 MUST 是验证 credentialSchema 对象的结果。它 MUST 是如下形式的对象： `verified` [boolean] 验证 credentialSchema 对象的结果。 `input` [object] 一个对象 `credentialStatus` [array] 验证 credentialStatus 对象的结果（若有）。`credentialStatus` 数组中的每一项 MUST 是验证 credentialStatus 对象的结果。它 MUST 是如下形式的对象： `value` [integer] 与状态条目关联的具体状态值。 `verified` [boolean] 验证 credentialStatus 对象的结果。 `input` [object] 一个对象 `proof` [array] 验证 proof 对象的结果（若有）。`proof` 数组中的每一项 MUST 是验证 proof 对象的结果。它 MUST 是如下形式的对象： `verified` [boolean] 验证 proof 对象的结果。 `input` [object] 一个对象
400	无效或格式错误的输入阻止了验证过程执行。这表示请求格式、结构或参数存在问题，而不是验证失败。
413	载荷过大
429	已超过请求速率限制。

POST /challenges - 向此端点传递空主体会创建并在响应主体中返回一个 challenge 字符串。

/challenges 端点在接收 POST 时可能产生以下任一响应：

响应	主体
200	Challenge 已创建 content-type: application/json 包含 challenge 的对象。它 MUST 是如下形式的对象： `challenge` [string] challenge 值
400	无效或格式错误的输入

instance 应创建用于验证期间的 challenge，并跟踪该 challenge 作为 options.challenge 被传递给验证端点的次数。

在使用可验证凭证和基于去中心化标识符的认证时，一方通常需要向另一方请求数据。本节描述这些请求的一般格式，并提供一种具体的可验证表达请求格式。

可验证表达请求是验证者向持有者发出的对表达的请求。若要请求一个或多个封装在可验证表达中的 credentials，验证者会构造一个 JSON 请求，描述其希望从持有者接收的一个或多个 credentials。请求的一般格式如下所示：

示例 1：可验证表达请求的一般形式

{
  // 一个或多个对可验证凭证的请求
  "query": [{
    "type": "QueryByExample",
    // QueryByExample 专用的查询详细信息...
  }],
  // 要包含在可验证表达中的目标安全域，
  // 例如网站域名
  "domain": "domain.example",

  // 要包含在可验证表达中的随机 challenge 字符串
  "challenge": "f63cb0d2-760e-11f0-a2b1-67febb854a5f"
}

query 属性作为 presentation 中数据请求的主要扩展点机制。虽然本文档定义了一种通用查询机制（见第 3.4.2 按示例查询节），但所有 query 对象均为如下形式：

query: 一个 REQUIRED 属性，指定验证者所请求的信息。该值 MUST 是一个或多个映射，其中每个映射 MUST 定义一个 type 属性，其关联值为字符串。
domain: 一个 OPTIONAL 的字符串，由验证者在 presentation request 期间提供给持有者。持有者会检查以确保该数据与其正在交互的 domain（例如网站域名）关联；如果是，则将该数据包含在可验证表达中。domain 用于确保持有者将其可验证表达限定到特定验证者，从而保护验证者免受重放攻击。
challenge: 一个 OPTIONAL、唯一的字符串，由验证者在特定 presentation request 期间提供给持有者。持有者将此数据包含在发送给验证者的可验证表达中，从而保护验证者免受重放攻击。

“query by example” credential 查询格式旨在使开发者能够轻松地从一个或多个可验证凭证中请求其需要的声明，以支持特定业务流程。该查询还可以指定其他信息，例如一个或多个受到验证者信任的签发者。

QueryByExample 查询中的 credentialQuery 属性是单个对象。用于组合多个查询的逻辑 "AND" 和 "OR" 操作通过查询级别的 group 属性处理，如第 3.4.5 查询中的逻辑操作节所述。具有相同 group 值的多个查询作为 "AND" 操作处理，而具有不同或缺失 group 值的查询作为 "OR" 操作处理。

示例 2：Query By Example 查询

{
  "query": [{
    "type": "QueryByExample",
    "credentialQuery": {
      // （可选）请求此 credential 的原因，
      // 可由用户的软件显示给用户
      "reason": "We need to know if you are an alumni of this school.",
      // （可选）所请求 credential 的示例
      "example": {
        "@context": [
          "https://www.w3.org/ns/credentials/v2",
          "https://www.w3.org/ns/credentials/examples/v2"
        ],
        "type": "ExampleAlumniCredential",
        // （可选）根据 credential subject type 选择 credential
        "credentialSubject": {
          "type": "Alumni"
        }
      },
      // （可选）指定来自特定 acceptedIssuers 或
      // 权威委托方的 credentials
      "acceptedIssuers": [{
        "issuer": "did:web:authority.example"
      }]
    }
  }],
  "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
  "domain": "reunion.example"
}

credentialQuery 对象支持以下属性：

属性	描述
reason	一个 OPTIONAL 的字符串，提供人类可读的说明，解释为什么请求该 credential。该说明 MAY 由其软件显示给持有者。
example	一个 OPTIONAL 对象，提供所请求 credential 的示例，包括其 `@context`、`type`，以及可选的 `credentialSubject` 字段，用于指示需要哪些 claims。
acceptedIssuers	一个 OPTIONAL 数组，包含条目或包含条目的列表，用于标识验证者认可并接受作为可验证凭证签发者的实体。每一项 MUST 是以下之一： 1）标识收到的可验证凭证的 `issuer` 属性中某个签发者的 [URL]；或 2）包含 `id` 属性的对象，该属性值是 [URL]，用于标识收到的可验证凭证的 `issuer` 属性中的签发者；或 3）包含 `recognizedIn` 属性的对象，该属性与一个对象关联，该对象具有设置为 `RecognizedEntityCredential` 的 `type` 属性，以及带有 [URL] 值的 `id` 属性，该值指向 Recognized Entities v1.0 规范中定义的此类 credential；该列表包含验证者可接受的已认可签发者。有效示例值包括： `did:web:red-issuer.example` `https://blue-issuer.example/` `{"id": "did:web:green-issuer.example"}` `{"recognizedIn": {"id": "https://url.example/list.vc", "type": "RecognizedEntityCredential"}}`
acceptedCryptosuites	一个 OPTIONAL 数组，指定验证者将接受哪些 cryptographic proof suites。每个元素 SHOULD 是一个对象，带有 `cryptosuite` 属性，引用 Data Integrity cryptosuite 名称，或为旧版使用 `Ed25519Signature2020` （为向后兼容，字符串值也 MAY 被使用，并解释为 cryptosuite 名称）。这使持有者能够选择适当的 proof 格式。此属性 MAY 独立于 `acceptedEnvelopes` 使用，后者仅适用于 enveloped credentials。有效示例值包括： `[{"cryptosuite": "eddsa-rdfc-2022"}, {"cryptosuite": "ecdsa-rdfc-2019"}]` `[{"cryptosuite": "bbs-2023"}, {"cryptosuite": "ecdsa-sd-2023"}]`
acceptedEnvelopes	一个 OPTIONAL 数组，指定验证者将接受哪些 envelope formats。每个元素 SHOULD 是一个带有 `mediaType` 属性的对象，该属性引用 envelope 的媒体类型（为向后兼容，字符串值也 MAY 被使用，并解释为媒体类型）。这使持有者能够以默认 Data Integrity 格式之外的格式提供 credentials。此属性 MAY 独立于 `acceptedCryptosuites` 使用，后者仅适用于使用可接受 cryptosuite 签名的 JSON-LD credentials。有效示例值包括： `[{"mediaType": "application/jwt"}]` `[{"mediaType": "application/vc+sd-jwt"}]`

QueryByExample 的 JSON Schema 在单独文件中提供，用于集成到软件系统中。

以下示例演示一个指定可接受 cryptosuites 和 envelope formats 的 QueryByExample，使持有者能够选择适当的 proof 机制：

示例 3：带有可接受 cryptosuites 和 envelopes 的 Query By Example

{
  "query": [{
    "type": "QueryByExample",
    "credentialQuery": {
      "reason": "Please present your PermanentResidentCard to complete the verification process.",
      "example": {
        "@context": [
          "https://www.w3.org/ns/credentials/v2",
          "https://w3id.org/citizenship/v3"
        ],
        "type": ["PermanentResidentCard"],
        "credentialSubject": {
          "birthCountry": ""
        }
      },
      "acceptedCryptosuites": [
        {"cryptosuite": "eddsa-rdfc-2022"},
        {"cryptosuite": "ecdsa-rdfc-2019"},
        {"cryptosuite": "bbs-2023"},
        {"cryptosuite": "ecdsa-sd-2023"}
      ],
      "acceptedEnvelopes": [
        {"mediaType": "application/jwt"},
        {"mediaType": "application/vc+sd-jwt"}
      ]
    }
  }],
  "challenge": "9876fedc-ba98-7654-3210-fedcba987654",
  "domain": "immigration.example"
}

在上述示例中，验证者表明其将接受由所列任一 cryptosuite 保护的 credentials。通过包含 bbs-2023 和 ecdsa-sd-2023，验证者表示选择性披露 proofs 是可接受的，从而允许持有者只披露 birthCountry 字段，而不是整个 credential。acceptedEnvelopes 属性表示基于 JWT 的 envelope formats 也是可接受的。

注：使用 Query By Example 进行选择性披露

Query By Example 中包含的任何字段都是必填字段。这意味着在使用 Query By Example 启用选择性披露时，请求者需要注意不要在其查询中包含用例不需要的字段。Query By Example 没有办法指示“可选” 字段；因此，响应查询的钱包有责任确保其响应不会披露超出请求范围的信息。注意：某些用于可验证凭证的保护机制不允许选择性披露；在这些情况下，可能必须发送未请求的信息，才能发送所请求的信息。数字钱包预期会告知用户将共享哪些信息。若要请求一个字段而不声明预期值，请求者可以在请求中包含该字段并将其值留为空字符串。例如，如果请求者需要名字，可以包含可选的 "credentialSubject" 对象，并带有一个字段 "firstName": ""。这将允许钱包仅以所请求 credential 的 firstName 进行响应，而不期待包含任何其他字段。_这并不阻止钱包通过在其查询响应中包含额外字段而过度共享。_ 若要表示选择性披露 cryptosuites 是可接受的，验证者 SHOULD 在 acceptedCryptosuites 数组中包含诸如 bbs-2023 或 ecdsa-sd-2023 的 cryptosuites。

本节定义验证者如何请求持有者执行基于去中心化标识符的认证 [DID-CORE]。最简单的形式中，认证协议由验证者发出的 challenge 和持有者给出的响应组成：

示例 4：DID Authentication 请求

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "example"}]
  }],
  "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
  "domain": "example.com"
}

上述 DID Authentication 请求指定验证者希望持有者通过对所提供 challenge 生成数字签名来证明其对 DID 的控制。持有者可以通过提供以下响应来回应：

示例 5：DID Authentication 响应

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": "VerifiablePresentation",
  "holder": "did:example:12345",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "verificationMethod": "did:example:12345#key-1",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "example.com",
    "created": "2024-02-25T14:58:42Z",
    "proofPurpose": "authentication",
    "proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
  }
}

DID Authentication 查询格式使验证者能够请求持有者以特定方式进行认证。DID Authentication 查询 MUST 采用以下形式：

属性	描述
type	一个 REQUIRED 字符串值，MUST 设置为 `DIDAuthentication`。
acceptedMethods	一个可选的对象数组，表示验证者将接受所列的任意 DID Method。数组中的每个对象 MUST 包含一个名为 `method` 的属性，其值是 DID Method 名称，并且 MAY 包含其他 DID Method 专用属性。有效示例值包括： `[{"method": "key"}]` `[{"method": "key"}, {"method": "web"}]`
acceptedCryptosuites	一个可选的对象数组，传达持有者在生成要提交给此验证者的 cryptographic proof 时 MUST 选择的 cryptography suites。数组中的每个对象 MUST 包含一个名为 `cryptosuite` 的属性，其值是 Data Integrity cryptosuite 名称（或旧版的 `Ed25519Signature2020`），并且 MAY 包含其他 cryptosuite 专用属性。有效示例值包括： `[{"cryptosuite": "eddsa-rdfc-2022"}]` `[{"cryptosuite": "ecdsa-rdfc-2019"}, {"cryptosuite": "bbs-2023"}]`

以下示例演示验证者希望持有者使用 DID Web method 和 data integrity ECDSA cryptography suite，在已建立的通信通道（例如 Credential Handler API（CHAPI））上进行认证：

示例 6：使用 did:web 和 ecdsa-rdfc-2019 的 DID Authentication 请求

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "key"}],
    "acceptedCryptosuites": [{"cryptosuite": "ecdsa-rdfc-2019"}]
  }],
  "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
  "domain": "example.com"
}

在下一个示例中，验证者希望持有者使用 DID Key 或 DID Web method，并使用标准 EdDSA data integrity cryptography suite；可选地包含一个 cryptographic proof，证明其能够执行 data integrity BBS proof；并在不同通信通道上进行认证，在此情况下使用 Verifiable Credential API HTTP 端点。

示例 7：复杂 DID Authentication 请求

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "key"}, {"method": "web"}],
    "acceptedCryptosuites": [{"cryptosuite": "ecdsa-rdfc-2019"}]
  }, {
    "type": "DIDAuthentication",
    "required": false,
    "acceptedMethods": [{"method": "key"}, {"method": "web"}],
    "acceptedCryptosuites": [{"cryptosuite": "bbs-2023"}]
  }],
  "challenge": "zLEwtBYgQVNR4tyeo",
  "domain": "didauth.example"
}

DID Authentication 响应格式使持有者能够提供验证者请求的信息。DID Authentication 响应 MUST 是如下形式的可验证表达：

属性	描述
type	一个 REQUIRED 字符串值，MUST 设置为 `VerifiablePresentation`。
holder	一个 REQUIRED 字符串值，MUST 设置为 DID Authentication 查询中所请求类型的特定 DID。
proof	一个 REQUIRED 值，MUST 是 DID Authentication 查询中所请求的一个或多个特定 digital proof types。每个 proof 对象 MUST 包含 DID Authentication 查询中提供的 `domain` 和 `challenge` 值。 Holder 实现 MUST 确保验证者指定的 `domain` 与当前通信通道使用的 domain 匹配。

持有者实现检查 verifier 提供的 domain 是否与当前通信通道所使用的 domain 匹配，这一点至关重要。如果持有者未能这样做，不诚实的验证者就可能将消息重放到并非其自己的 domain。例如，一个从 evil.example domain 运行的不诚实验证者可以从你的银行获取 challenge，指定 yourbank.example 的 domain 值，然后将你的响应重放给你的银行以访问你的金融账户。只要实现确保在生成可验证表达时使用适当的 domain，这种攻击就能被缓解。

以下示例演示一个简单的 DID Authentication 响应。

示例 8：使用 did:key 的 DID Authentication 响应

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": "VerifiablePresentation",
  "holder": "did:example:12345",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "verificationMethod": "did:example:12345#key-1",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "example.com",
    "created": "2024-02-25T14:58:42Z",
    "proofPurpose": "authentication",
    "proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
  }
}

议题 2

Authorization Capability 查询和响应此时可能不会被标准化。此示例用于演示可验证凭证和 mDLs/mdocs 并不是唯一可被查询的 credential 类型。

这种查询类型会包含在请求中，用于请求 Verifiable Presentation 中的 Authorization Capabilities 或 "zcaps"。

示例 9：Authorization Capability Request 查询

{
  "query": [{
    "type": "AuthorizationCapabilityQuery",
    "capabilityQuery": [{
      "referenceId": "a-memorable-name",
      "allowedAction": ["read", "write"],
      "controller": "did:example:1234",
      "invocationTarget": {
        "type": "urn:edv:documents"
      }
    }, {
      "referenceId": "another-memorable-name",
      "allowedAction": "sign",
      "controller": "did:example:1234",
      "invocationTarget": {
        "type": "Multikey",
        "proofPurpose": "assertionMethod"
      }
    }],
    challenge: "111112b24-63d9-11ea-b99f-4f66f3e4f81a"
  }]
}

在 Verifiable Presentation Requests 中，信息的结构化和检索依赖逻辑操作的使用。"AND" 和 "OR" 操作在定义到达期望数据的路径方面发挥关键作用。

在请求结构的最顶层，如果每个查询的 group 属性设置为相同值，则不同类型的查询预期作为 "AND" 操作处理。

在此示例中，有两个查询的 group 标志设置为 certification。这会产生一个 "AND" 操作，表示为了满足请求，这两个条件都需要被满足。

示例 10：使用顶层查询一次请求多个 credentials

{
  "query": [{
    "type": "QueryByExample",
    "group": "certification",
    // 查询详细信息 ...
  },
  // "AND"
  {
    "type": "DigitalCredentialQueryLanguage",
    "group": "certification",
    // 查询详细信息 ...
  }]
}

在特定查询类型内，可以通过不指定 group，或提供彼此不同的 group 值，应用 "OR" 操作。

示例 11：针对备选 credentials 的查询，其中任一匹配都会成功

{
  "query": [{
    "type": "QueryByExample",
    "group": "college-degree",
    // 查询详细信息 ...
  },
  // "OR"
  {
    "type": "DigitalCredentialQueryLanguage",
    "group": "job-experience",
    // 查询详细信息 ...
  }]
}

以下 API 被定义用于出示 Verifiable Credential：

端点	描述
POST /credentials/derive	派生 credential，并在响应主体中返回它。
GET /presentations	获取 presentations 或 verifiable presentations 的列表
POST /presentations	创建 presentation，并在响应主体中返回它。
GET /presentations	获取 presentations 或 verifiable presentations 的列表
POST /presentations	创建 presentation，并在响应主体中返回它。
GET /presentations/{id}	按 ID 获取 presentation 或 verifiable presentation
DELETE /presentations/{id}	按 ID 删除 presentation 或 verifiable presentation
POST /exchanges/	错误：API 端点未定义 - /exchanges/
POST /exchanges/{exchangeId}	错误：API 端点未定义 - /exchanges/{exchangeId}

URL 路径值 exchange-id 对服务器有意义，但对客户端是不透明的。虽然某些服务器实现可能使用恰好为人类可读的值，但强烈建议客户端不要为任何人类可读值赋予语义。

POST /credentials/derive - 派生 credential，并在响应主体中返回它。

/credentials/derive 端点在接收 POST 时使用以下模式：

属性描述

属性	描述
`verifiableCredential` [object]	如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果未提供 id 属性， issuer SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。
`options` [object]	用于指定如何创建 derived credential 的选项。它 MUST 是如下形式的对象： `selectivePointers` [array] 指定选择性披露信息的 JSON pointers 数组。 `selectivePointers` 数组中的每一项 MUST 是字符串。

verifiableCredential [object]

如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

credential 的 ID。此属性 MAY 为空。如果未提供 id 属性， issuer SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。

type [array]

credential 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

options [object]

用于指定如何创建 derived credential 的选项。它 MUST 是如下形式的对象：

selectivePointers [array]: 指定选择性披露信息的 JSON pointers 数组。 selectivePointers 数组中的每一项 MUST 是字符串。

/credentials/derive 端点在接收 POST 时可能产生以下任一响应：

响应主体

201

响应	主体
201	Credential 已成功派生。 content-type: application/json 如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。
400	无效请求

Credential 已成功派生。

content-type: application/json

如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

type [array]

credential 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

400 无效请求

注： Presentation 媒体类型

可以在响应中返回 EnvelopedVerifiablePresentation，以便创建媒体类型不是 application/vp 的 presentations，例如 application/vp+jwt。

POST /presentations - 创建 presentation，并在响应主体中返回它。

/presentations 端点在接收 POST 时使用以下模式：

属性描述

属性	描述
`presentation` [object]	不带 proof 的 JSON-LD Verifiable Presentation。它 MUST 是如下形式的对象： `@context` [array] presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] presentation 的 ID。 `type` [array] presentation 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] Verifiable Credentials。`verifiableCredential` 数组中的每一项 MUST 是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。
`options` [object]	用于指定如何创建 DataIntegrityProof 的选项。它 MUST 是如下形式的对象： `type` [string] proof 的类型。默认值为 'DataIntegrityProof'。 `cryptosuite` [string] proof 的 cryptosuite。 `verificationMethod` [string] 用于 proof 的 verificationMethod 的 URI。如果省略，将使用默认的 verification method。 `proofPurpose` [string] proof 的用途。默认值为 'assertionMethod'。 `created` [string] proof 的日期和时间（最高精确到秒）。默认值为当前系统时间。 `challenge` [string] 由 proof 请求方提供的 challenge。例如 6e62f66e-67de-11eb-b490-ef3eeefa55f2 `domain` [string] proof 的预期有效 domain。例如 website.example

presentation [object]

不带 proof 的 JSON-LD Verifiable Presentation。它 MUST 是如下形式的对象：

@context [array]

presentation 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

presentation 的 ID。

type [array]

presentation 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

holder [object]

一个对象

verifiableCredential [array]

Verifiable Credentials。verifiableCredential 数组中的每一项 MUST 是如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

type [array]

credential 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

options [object]

用于指定如何创建 DataIntegrityProof 的选项。它 MUST 是如下形式的对象：

type [string]: proof 的类型。默认值为 'DataIntegrityProof'。
cryptosuite [string]: proof 的 cryptosuite。
verificationMethod [string]: 用于 proof 的 verificationMethod 的 URI。如果省略，将使用默认的 verification method。
proofPurpose [string]: proof 的用途。默认值为 'assertionMethod'。
created [string]: proof 的日期和时间（最高精确到秒）。默认值为当前系统时间。
challenge [string]: 由 proof 请求方提供的 challenge。例如 6e62f66e-67de-11eb-b490-ef3eeefa55f2
domain [string]: proof 的预期有效 domain。例如 website.example

/presentations 端点在接收 POST 时可能产生以下任一响应：

响应主体

201

响应	主体
201	Presentation 已成功创建！ content-type: application/json 如下形式的对象： `verifiablePresentation` [object] 如下形式的对象： `@context` [array] presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] presentation 的 ID。 `type` [array] presentation 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] Verifiable Credentials。`verifiableCredential` 数组中的每一项 MUST 是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。 `proof` [object] 包含 challenge 和 domain 的 Data Integrity Proof，如 W3C VC Data Integrity 规范所定义。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `challenge` [string] verifier 选择的值，用于缓解认证 proof 重放攻击。 `domain` [string] proof 的 domain，用于将其使用限制到特定目标。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。，或一个用于表达 enveloped verifiable presentation 的对象。它 MUST 是如下形式的对象： `@context` [array] enveloped verifiable presentation 的 JSON-LD context。`@context` 数组中的每一项 MUST 是字符串。 `id` [string] 这 MUST 是一个 "data:" scheme URL [RFC2397]，用于使用封装安全方案表达受保护的 verifiable presentation。 `type` [string] 这 MUST 是 EnvelopedVerifiablePresentation。
400	输入无效！

Presentation 已成功创建！

content-type: application/json

如下形式的对象：

verifiablePresentation [object]

如下形式的对象：

@context [array]

presentation 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

presentation 的 ID。

type [array]

presentation 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

holder [object]

一个对象

verifiableCredential [array]

Verifiable Credentials。verifiableCredential 数组中的每一项 MUST 是如下形式的对象：

@context [array]

credential 的 JSON-LD context。 @context 数组中的每一项 MUST 是字符串。

id [string]

type [array]

credential 的 JSON-LD type。type 数组中的每一项 MUST 是字符串。

issuer [object]

字符串，或如下形式的对象：

id [string]: issuer id。

validFrom [string]

validFrom 日期

validUntil [string]

validUntil 日期

credentialSubject [object]

一个对象

proof [object]

由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

proof [object]

包含 challenge 和 domain 的 Data Integrity Proof，如 W3C VC Data Integrity 规范所定义。它 MUST 是如下形式的对象：

type [string]: Data Integrity Proof 类型。
cryptosuite [string]: 密码套件的名称。
created [string]: proof 创建日期。
challenge [string]: verifier 选择的值，用于缓解认证 proof 重放攻击。
domain [string]: proof 的 domain，用于将其使用限制到特定目标。
nonce [string]: proof 创建者选择的值，用于出于隐私目的随机化 proof 值。
verificationMethod [string]: 用于验证 proof 的 Verification Method。
proofPurpose [string]: proof 的用途，与 verificationMethod 一起使用。
proofValue [string]: Linked Data proof 的值。

，或一个用于表达 enveloped verifiable presentation 的对象。它 MUST 是如下形式的对象：

@context [array]: enveloped verifiable presentation 的 JSON-LD context。@context 数组中的每一项 MUST 是字符串。
id [string]: 这 MUST 是一个 "data:" scheme URL [RFC2397]，用于使用封装安全方案表达受保护的 verifiable presentation。
type [string]: 这 MUST 是 EnvelopedVerifiablePresentation。

400 输入无效！

GET /presentations - 获取 presentations 或 verifiable presentations 的列表

/presentations 端点在接收 GET 时可能产生以下任一响应：

响应	主体
200	Presentations 已检索 content-type: application/json 数组中的每一项 MUST 是不带 proof 的 JSON-LD Verifiable Presentation。它 MUST 是如下形式的对象： `@context` [array] presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] presentation 的 ID。 `type` [array] presentation 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] Verifiable Credentials。`verifiableCredential` 数组中的每一项 MUST 是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。，或如下形式的对象： `@context` [array] presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] presentation 的 ID。 `type` [array] presentation 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] Verifiable Credentials。`verifiableCredential` 数组中的每一项 MUST 是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。 `proof` [object] 包含 challenge 和 domain 的 Data Integrity Proof，如 W3C VC Data Integrity 规范所定义。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `challenge` [string] verifier 选择的值，用于缓解认证 proof 重放攻击。 `domain` [string] proof 的 domain，用于将其使用限制到特定目标。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。
400	错误请求
401	未授权
410	已消失！这里没有数据

GET /presentations/{id} - 按 ID 获取 presentation 或 verifiable presentation

/presentations/{id} 端点在接收 GET 时可能产生以下任一响应：

响应	主体
200	Credential 已检索 content-type: application/json 不带 proof 的 JSON-LD Verifiable Presentation。它 MUST 是如下形式的对象： `@context` [array] presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] presentation 的 ID。 `type` [array] presentation 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] Verifiable Credentials。`verifiableCredential` 数组中的每一项 MUST 是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。，或如下形式的对象： `@context` [array] presentation 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] presentation 的 ID。 `type` [array] presentation 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] Verifiable Credentials。`verifiableCredential` 数组中的每一项 MUST 是如下形式的对象： `@context` [array] credential 的 JSON-LD context。 `@context` 数组中的每一项 MUST 是字符串。 `id` [string] credential 的 ID。此属性 MAY 为空。如果 issuer 未提供 id 属性，则 SHOULD NOT 自动生成该属性，因为 Verifiable Credential 不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [array] credential 的 JSON-LD type。`type` 数组中的每一项 MUST 是字符串。 `issuer` [object] 字符串，或如下形式的对象： `id` [string] issuer id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的 Data Integrity Proof。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。 `proof` [object] 包含 challenge 和 domain 的 Data Integrity Proof，如 W3C VC Data Integrity 规范所定义。它 MUST 是如下形式的对象： `type` [string] Data Integrity Proof 类型。 `cryptosuite` [string] 密码套件的名称。 `created` [string] proof 创建日期。 `challenge` [string] verifier 选择的值，用于缓解认证 proof 重放攻击。 `domain` [string] proof 的 domain，用于将其使用限制到特定目标。 `nonce` [string] proof 创建者选择的值，用于出于隐私目的随机化 proof 值。 `verificationMethod` [string] 用于验证 proof 的 Verification Method。 `proofPurpose` [string] proof 的用途，与 verificationMethod 一起使用。 `proofValue` [string] Linked Data proof 的值。
400	错误请求
401	未授权
404	未找到 presentation
410	已消失！这里没有数据

DELETE /presentations/{id} - 按 ID 删除 presentation 或 verifiable presentation

/presentations/{id} 端点在接收 DELETE 时可能产生以下任一响应：

响应	主体
202	Presentation 已删除——默认使用 202，因为假定会进行软删除并需要处理时间
400	错误请求
401	未授权
404	未找到 presentation
410	已消失！这里没有数据

工作流定义了用于在跨越信任边界的两方之间交换可验证凭证的一组特定步骤。每一步都可能涉及可验证凭证的签发、验证、传输和/或出示。工作流旨在支持线性的步骤序列，以及包含分支逻辑和重复步骤的更复杂模式，从而支持相关各方之间的复杂交互。VC API 工作流的示例包括但不限于以下内容：

向已登录到协调器网站的员工签发员工成员凭证。
在收到驾驶执照凭证的出示后签发车辆所有权凭证。
验证永久居民凭证的出示。
接收一个或多个新签发的一次性年龄证明凭证。

工作流实例预计由管理员创建，用于例如协调器网站。工作流实例通过向工作流服务的 /workflows 端点执行 HTTP POST 来创建。HTTP 请求主体包含工作流实例的配置。这包括但不限于定义工作流的步骤信息，以及将用于签发可验证凭证的任何凭证模板。定义工作流的步骤也可以是模板，从而提供额外的灵活性。如果工作流涉及可验证凭证的签发，或出示或凭证的验证，则工作流实例配置可以包含用于使用一个或多个签发者和/或验证服务的授权能力。

一旦工作流实例存在，就可以向协调器授予创建和查询特定工作流交互的授权，这些交互称为交换。

交换表示基于给定工作流的特定交互。该交互将在交换客户端和工作流服务之间进行。交换预计是短暂的，仅在交互完成所需的时间内存在。工作流服务会存储每个交换的状态信息，例如该交换是待处理、活动还是已完成，以及工作流中的当前步骤、任何工作流特定的变量和数据，以及在交换执行期间收到的任何可验证出示和凭证。除第 3.6.3 创建交换中定义的保留变量之外，实现者还可以自由使用其实现所需的任何变量。虽然技术上对工作流中的步骤数量没有限制，但实现者可能希望强制执行默认的最大步骤数以防止 bug。

签发者、验证者或持有者协调器负责创建交换。协调器通过向工作流服务上所选工作流的 /exchanges 子路径执行 HTTP POST 来创建交换。 HTTP 请求主体包含交换的过期日期和时间，以及用于填充该特定交换的工作流模板的任何变量。请求主体还可以包含配置选项，以允许使用本 API 之外的其他协议执行该交换。创建交换后，会向协调器返回一个用于标识该交换并允许与之交互的交换 URL。

交换 URL 会提供给交换客户端，以便其发起该交换。请注意，虽然交换 URL 会提供给协调器，再由协调器将其提供给交换客户端，但实际的交换是在交换客户端和工作流服务之间执行；协调器在向交换客户端提供交换 URL 后不再参与。为清楚起见：对于任何需要协调器自身执行交换的用例，协调器仍然可以使用自己的交换客户端。

发起交换不需要交换 URL 之外的任何授权。根据工作流服务实现，交换 URL 也可以是能力 URL （即，该 URL 是不可猜测的秘密，因此只有被给予该 URL 的人才能发起交换）。如果该交换所基于的工作流需要持有交换 URL 之外的任何其他授权，则应在交换期间获得，而不是在发起时获得。

协调器也可以使用交换 URL 查询交换进展中的当前状态，并获取工作流服务已存储的与该交换相关的信息。以这种方式查询交换需要额外授权，协调器预计拥有该授权，而交换客户端没有。

交换 URL 如何从协调器传输到交换客户端不在本规范范围内。与客户端共享交换 URL 的已知机制包括 Credential Handler API （又称 CHAPI）、二维码或通用链接。

交换被设计为除了本 API 交换协议之外，还可使用其他协议执行；例如，交换可能可以使用 OID4VCI、OID4VP、DIDComm 以及 exchange 协议中的任何一种来执行。支持的协议取决于交换所基于的工作流的复杂性，以及协调器在创建交换时提供的选项。

交换客户端预计会使用与其接收交换 URL 的方式相兼容的协议来发起交换。例如，交换 URL 可能通过 CHAPI 提供，并带有一个协议标识符，指示应使用本 API 协议。或者，交换 URL 可以作为 OID4VCI 凭证要约中的 "credential_issuer"，或作为 OID4VP 授权请求中的 "client_id"，分别指示应使用 OID4VCI 或 OID4VP。本节重点说明交换客户端如何使用本 API 与交换交互；参见待定附录，以了解如何将交换与 OID4VCI、OID4VP 和 DIDComm 等其他协议结合使用。

使用本 API 协议执行的交换涉及通过 HTTP 以请求和响应主体形式发送的消息。每条消息都由一个简单的 JSON 对象组成，其中包含零个或多个以下属性和值：

redirectUrl：一个 URL，可用于在另一个位置继续交互。其一个用例是在交换完成后，将交换客户端的用户发送回协调器网站。
verifiablePresentation：一个可验证出示。交换中的任一方使用它向另一方提供信息，原因可以是后者请求了该信息，也可以是前者只是主动提供该信息。
verifiablePresentationRequest：一个可验证出示请求。交换中的任一方使用它向另一方请求信息。

也可以包含自定义属性和值，但在不识别它们的实现中预计会触发错误。

要使用本 API 协议发起交换，交换客户端会执行 HTTP POST，将一个 JSON 对象作为请求主体发送。在最简单的情况下，当客户端对交换没有自己的约束——也就是说，它没有要向另一方请求的内容—— JSON 对象为空（{}）。工作流服务会在响应主体中以其自己的 JSON 对象进行响应。

如果该响应对象为空，则交换完成，并且没有向交换客户端请求或提供任何内容。如果该对象包含 verifiablePresentationRequest，则交换尚未完成，并且会根据关联的可验证出示请求的内容请求一些额外信息。如果该对象包含 verifiablePresentation，则会提供一些信息，例如签发给操作交换客户端的持有者的可验证凭证，或基于交换客户端请求提供的、关于交换服务器运营者的信息的可验证凭证。如果该对象包含 redirectUrl，则交换完成，并且工作流服务建议客户端前往另一个位置，以另一种形式继续交互。

许多可验证凭证用例都可以使用这些基本原语实现。交换的任一方都能够请求可验证出示，并提供一个或多个可能有助于建立信任和/或获得授权能力的可验证凭证；任一方也都能够出示他们持有或签发的凭证。可以配置特定工作流以期望特定的出示和凭证，并拒绝偏离预期信息流的情况。当工作流服务确定某条特定消息不可接受时，它会通过返回 4xx HTTP 状态消息和一个表达错误信息的 JSON 对象来引发错误。

交换设计方法是分层的：它旨在提供一个最小的通信消息层和一组原语，使大多数用例能够通过上一层中的特定可验证出示请求和可验证凭证来实现。有关使用特定可验证出示请求和可验证凭证的工作流与交换示例，请参见后续附录。

注：工作流步骤和凭证示例

步骤模板和凭证模板的最小可行示例，以及几个更复杂的工作流模板，可以在附录工作流步骤和模板示例中找到。

与交换的一次给定交互预计是短暂的，但也可以使用其他机制来支持更长或多阶段的交互。其他交互机制的示例包括短信、电子邮件、Web 通知或电话。这种方法简化了数字钱包实现，并允许复用现有机制，而无需在本 API 中重新发明。 Web 或原生平台预计会通过应用程序（例如 Web 浏览器）或其他平台功能支持额外交互。例如，在异步签发中，持有者请求凭证但需要等待处理。在这种情况下，系统组件（例如签发者协调器）会使用本 API 之外的机制，在持有者的凭证可供领取时通知持有者。

为需要跨越信任边界的凭证用例使用工作流和交换，定义了以下 API：

端点	描述
POST /workflows	创建新的工作流，并在响应标头中返回工作流元数据的位置。
GET /workflows/{localWorkflowId}	获取现有工作流的配置，并在响应主体中返回。
POST /workflows/{localWorkflowId}/exchanges	创建新的交换，并在响应标头中返回交换元数据的位置。
GET /workflows/{localWorkflowId}/exchanges/{localExchangeId}	获取现有交换的状态，并在响应主体中返回。
POST /workflows/{localWorkflowId}/exchanges/{localExchangeId}	参与交换。提交空主体将启动交换，或返回该交换为完成下一步所期望的内容。提交可验证出示请求将导致 4xx 错误，或以下之一——符合客户端请求的可验证出示或可验证出示请求。如果发送了可验证出示，也可以发送额外的可验证出示请求以继续交换。

在工作流和交换 API 中，“local” ID 指的是相对于服务实例本地的 ID。换句话说，exchangeId 或 workflowId 指的是完全限定的 URL，而 localExchangeId 或 localWorkflowId 指的是 URL 路径中的特定元素。

POST /workflows - 创建新的工作流，并在响应标头中返回工作流元数据的位置。

/workflows 端点在接收 POST 时使用以下模式：

属性	描述
`id` [string]	将用于已创建工作流的 ID。传递 ID 是可选的。
`initialStep` [string]	交换开始时使用的上述步骤集合中的步骤。传递 initialStep 是必需的。
`controller` [string]	一个可选属性，用于指定实例的根控制器，该属性可供支持授权能力（ZCAPs）等依赖对象能力的授权机制的系统使用。该值可以与 `authorization` 属性结合使用，以同时允许其他授权机制。
`authorization` [object]	一个可选属性，用于指定端点的授权方案信息，例如 OAuth2 配置。它必须是以下形式的对象： `oauth2` [object] OAuth2 配置。它必须是以下形式的对象： `issuerConfigUrl` [string] OAuth2 签发者配置 URL。
`credentialTemplates` [array]	一个数组，其中每一项都必须是以下形式的对象： `id` [string] 模板的 ID。 `type` [string] 模板的类型。 `template` [string] 模板本身。
`steps` [object]	完成该工作流上的交换所需的一个或多个步骤。传递 steps 对象是必需的。键是一个或多个步骤名称，其中每个 STEP_NAME 会替换为某个步骤的名称（例如 `request-employee-id`），值是步骤配置。它必须是以下形式的对象： `STEP_NAME` [object] 如果未使用模板，则包含步骤数据。它必须是以下形式的对象： `createChallenge` [boolean] 一个可选的步骤指令，告诉交换通过其拥有 zcap 的 VCALM 验证者服务来处理质询管理。 `verifiablePresentationRequest` [object] 一个可验证出示请求。它必须是以下形式的对象： `query` [array] 请求者发送的一个或多个查询集合。每个 `query` 数组中的项都必须是以下形式的对象： `type` [array] 查询的类型。`type` 数组中的每一项都必须是字符串。 `credentialQuery` [object] 对于 QueryByExample 查询，指定凭证请求详情。它必须是以下形式的对象： `reason` [string] 说明为什么请求该凭证的人类可读解释。 `example` [object] 一个对象 `acceptedIssuers` [array] 所请求凭证的可接受签发者。 `acceptedIssuers` 数组中的每一项都必须是以下形式的对象： `issuer` [string] `acceptedCryptosuites` [array] 验证者将接受的密码学证明套件。每个元素应该是一个带有 `cryptosuite` 属性的对象，该属性引用 Data Integrity cryptosuite 名称，或用于旧版的 `Ed25519Signature2020` （为向后兼容，也可以使用字符串值，并将其解释为 cryptosuite 名称）。这使持有者能够选择合适的证明格式。此属性可以独立于 `acceptedEnvelopes` 使用，后者仅适用于封装凭证。 `acceptedCryptosuites` 数组中的每一项都必须是 undefined： `acceptedEnvelopes` [array] 验证者将接受的封装格式。每个元素应该是一个带有 `mediaType` 属性的对象，该属性引用封装的媒体类型（为向后兼容，也可以使用字符串值并将其解释为媒体类型）。这使持有者能够以默认 Data Integrity 格式之外的格式提供凭证。此属性可以独立于 `acceptedCryptosuites` 使用，后者仅适用于使用可接受 cryptosuite 签名的 JSON-LD 凭证。 `acceptedEnvelopes` 数组中的每一项都必须是 undefined： `challenge` [string] 由请求者提供的质询，旨在防止重放攻击，通常预计会包含在可验证出示响应中。 `domain` [string] 由请求者提供的域，旨在防止重放攻击，通常预计会包含在可验证出示响应中。 `interact` [array] 服务器支持的交互机制列表。 `interact` 数组中的每一项都必须是以下形式的对象： `service` [object] 服务器支持的一项服务，能够接收对可验证出示请求的响应。它必须是以下形式的对象： `type` [array] 服务的类型。`type` 数组中的每一项都必须是字符串。 `serviceEndpoint` [string] 可用于与服务交互以响应可验证出示请求的 URL。 `verifiablePresentation` [object] 以下形式的对象： `@context` [array] 出示的 JSON-LD 上下文。`@context` 数组中的每一项都必须是字符串。 `id` [string] 出示的 ID。 `type` [array] 出示的 JSON-LD 类型。`type` 数组中的每一项都必须是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] 可验证凭证。`verifiableCredential` 数组中的每一项都必须是以下形式的对象： `@context` [array] 凭证的 JSON-LD 上下文。 `@context` 数组中的每一项都必须是字符串。 `id` [string] 凭证的 ID。此属性可以为空。如果未提供，签发者不应该自动生成 id 属性，因为可验证凭证并不要求 id 属性有效，并且存在无法设置 id 属性的用例。 `type` [array] 凭证的 JSON-LD 类型。`type` 数组中的每一项都必须是字符串。 `issuer` [object] 一个字符串，或以下形式的对象： `id` [string] 签发者 id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的数据完整性证明。它必须是以下形式的对象： `type` [string] 数据完整性证明类型。 `cryptosuite` [string] 密码学套件的名称。 `created` [string] 证明创建日期。 `nonce` [string] 证明创建者选择的一个值，用于出于隐私目的随机化证明值。 `verificationMethod` [string] 用于验证证明的验证方法。 `proofPurpose` [string] 与 verificationMethod 一起使用的证明目的。 `proofValue` [string] Linked Data 证明的值。 `proof` [object] 包含质询和域的数据完整性证明，如 W3C VC Data Integrity 规范所定义。它必须是以下形式的对象： `type` [string] 数据完整性证明类型。 `cryptosuite` [string] 密码学套件的名称。 `created` [string] 证明创建日期。 `challenge` [string] 验证者选择的一个值，用于缓解认证证明重放攻击。 `domain` [string] 证明的域，用于将其使用限制到特定目标。 `nonce` [string] 证明创建者选择的一个值，用于出于隐私目的随机化证明值。 `verificationMethod` [string] 用于验证证明的验证方法。 `proofPurpose` [string] 与 verificationMethod 一起使用的证明目的。 `proofValue` [string] Linked Data 证明的值。 `redirectUrl` [string] 发送给客户端的 URL，可用于在另一个位置继续交互。传递 redirectUrl 是可选的。 `callback` [object] 一个回调，将在此步骤执行后被调用。它必须是以下形式的对象： `url` [string] 将接收回调数据的 URL。 `issueRequests` [array] `issueRequests` 数组中的每一项都必须是 { "required": [ "credentialTemplateId" ] } 或 { "required": [ "credentialTemplateIndex" ] } `presentationSchema` 用于描述要对出示执行的验证的 JSON Schema。它必须是以下形式的对象： `type` [string] 该值必须是 `JsonSchema`。 `jsonSchema` [object] 一个对象，或是在当前步骤中验证出示时使用的另一种出示模式格式。对于特定出示模式类型，预计会有其他属性，但这些属性超出本规范范围。它必须是以下形式的对象： `type` [string] 验证出示时使用的出示模式机制类型。 `verifyPresentationResponseSchema` 用于描述要对验证出示的结果执行的验证的 JSON Schema。它必须是以下形式的对象： `type` [string] 该值必须是 `JsonSchema`。 `jsonSchema` [object] 一个对象，或是在当前步骤中对验证出示的结果使用的另一种出示模式格式。对于特定出示模式类型，预计会有其他属性，但这些属性超出本规范范围。它必须是以下形式的对象： `type` [string] 验证出示的结果时使用的出示模式机制类型。 `nextStep` [string] 序列中下一步的名称。传递 nextStep 是可选的。此字段不得出现在最终步骤配置中。 `openId` [object] 以下之一 { "required": [ "createAuthorizationRequest" ], "not": { "required": [ "authorizationRequest" ] } } 或 { "required": [ "authorizationRequest" ], "not": { "required": [ "createAuthorizationRequest" ] } } 或以下形式的对象： `clientProfiles` [object] 一个对象或以下形式的对象： `stepTemplate` [object] 工作流步骤的模板。必须存在此项或其他步骤数据，但不能同时存在两组数据。它必须是以下形式的对象： `type` [string] 模板的类型。 `template` [string] 步骤模板。

/workflows 端点在接收 POST 时可能产生以下任一响应：

响应	主体
201	工作流已成功创建（带数据）
204	工作流已成功创建（不带数据）
400	无效输入
401	未授权
500	内部错误

工作流可以包含有关步骤、凭证模板和授权的信息。在某些情况下，工作流还会在其配置的不同位置（通常在凭证模板中）引用保留的 results 变量。此变量保存工作流服务在交换过程中从客户端接收的数据。下面是一个基本的工作流配置，其中包含一个 DID Authentication 步骤和一个凭证交付步骤：

一个步骤可以包含一个 issueRequests 数组，其中包含一个或多个签发请求对象。每个签发请求对象都会标识要使用的凭证模板，可以通过其标识符（credentialTemplateId）或通过其在工作流 credentialTemplates 数组中的索引（credentialTemplateIndex）来标识。签发请求对象可以还包含一个 variables 属性，用于提供在评估凭证模板时使用的值。默认情况下，每个签发请求的结果都会包含在同一步骤中发送给交换客户端的可验证出示中。签发请求对象可以包含一个可选的 result 属性，其值必须是交换的 variables 对象中的顶层变量名称，或指向交换 variables 对象中任意变量的 JSON 指针，用于标识签发请求结果的存储位置。这支持更强的组合性，因为后续步骤可以引用已存储的结果，或者交换可以结束，而拥有交换状态访问权限的一方可以获取该结果，用于另一个交换或通过其他机制使用。

示例 12：一个基本工作流

{
  "id": "9fd3bc6d-4a04-4b3d-a983-3482d0586626",
  "initialStep": "didAuthRequest",
  "steps": {
    "didAuthRequest": {
      "createChallenge": true,
      "verifiablePresentationRequest": {
        "query": {
          "type": "DIDAuthentication",
          "acceptedMethods": [
            {
              "method": "key"
            },
            {
              "method": "web"
            }
          ],
          "acceptedCryptosuites": [
            {
              "cryptosuite": "eddsa-rdfc-2022"
            },
            {
              "cryptosuite": "ed25519-2020"
            }
          ]
        },
        "domain": "https://issuer.example.com"
      },
      "nextStep": "credentialDelivery"
    },
    "credentialDelivery": {
      "issueRequests": [
        {
          "credentialTemplateId": "caffb919-053a-4bfa-beba-80567904f842",
          "variables": "sampleAchievementCredential"
        }
      ]
    }
  },
  "credentialTemplates": [
    {
      "id": "caffb919-053a-4bfa-beba-80567904f842",
      "type": "jsonata",
      "template": "{
        \"credential\": {
          \"@context\": [
            \"https://www.w3.org/ns/credentials/v2\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/extensions.json\"
          ],
          \"id\": sampleAchievementCredential.id,
          \"type\": [\"VerifiableCredential\", \"AchievementCredential\"],
          \"issuer\": {
            \"type\": [\"Profile\"],
            \"name\": \"Example Issuer\",
            \"image\": {
              \"type\": \"Image\",
              \"id\": \"https://issuer.example.com/logo.png\"
            }
          },
          \"awardedDate\": sampleAchievementCredential.awardedDate,
          \"validFrom\": sampleAchievementCredential.validFrom,
          \"name\": \"Sample Achievement\",
          \"credentialSubject\": {
            \"id\": results.didAuthRequest.verifiablePresentation.holder,
            \"type\": \"AchievementSubject\",
            \"name\": sampleAchievementCredential.credentialSubject.name,
            \"achievement\": {
              \"id\": sampleAchievementCredential.credentialSubject.achievement.id,
              \"type\": [\"Achievement\"],
              \"achievementType\": sampleAchievementCredential.credentialSubject.achievement.achievementType,
              \"name\": sampleAchievementCredential.credentialSubject.achievement.name,
              \"description\": sampleAchievementCredential.credentialSubject.achievement.description,
              \"alignment\": sampleAchievementCredential.credentialSubject.achievement.alignment
            }
          }
        }
      }"
    }
  ],
  "controller": "did:web:issuer.example.com"
}

一个步骤可以包含一个 verifiablePresentation，以明确表达要在该步骤中使用的可验证出示。该出示可以通过交换中的其他变量组合而成，并且可以附加在该步骤期间可能签发的任何额外可验证凭证（依据 issueRequests）。这支持以下用例：需要特定可验证出示版本、需要特定子类型的可验证出示，或需要特定可验证出示内容，包括要在工作流步骤中交付的、先前通过带外方式签发的可验证凭证。

一个步骤可以包含 redirectUrl，用于指定发送给客户端的 URL，该 URL 可用于在另一个位置继续交互。其一个用例是在交换完成后将交换客户端的用户送回协调器网站。另一个用例是返回一个交互 URL，使服务器能够在持续交互期间实现自定义业务规则，而无需客户端导航到 Web 浏览器。例如，第一个交换可以向用户请求信息，然后通过 redirectUrl 返回一个交互 URL。客户端（例如数字钱包）可以确定它是一个交互 URL（例如， URL 使用 ?iuv=1）并获取它，从而使交互服务器运行自定义业务逻辑，然后返回一个协议对象，其中包含另一个用于继续交互的交换。

某些工作流需要在其一个或多个步骤中引用自定义变量。在这种情况下，协调器在创建交换时需要为这些变量提供适当的值。下面是一个带模板化 DID Authentication 步骤的工作流配置示例（请注意 didAuthRequest 步骤中引用的 verifiablePresentationRequest 和 callbackUrl 变量）：

示例 13：一个模板化工作流

{
  "id": "9fd3bc6d-4a04-4b3d-a983-3482d0586626",
  "initialStep": "didAuthRequest",
  "steps": {
    "didAuthRequest": {
      "stepTemplate": {
        "type": "jsonata",
        "template": "{
          "createChallenge": true,
          "verifiablePresentationRequest": verifiablePresentationRequest,
          "callback": {
            "url": callbackUrl
          },
          "nextStep": "credentialDelivery"
        }"
      }
    },
    "credentialDelivery": {
      "issueRequests": [
        {
          "credentialTemplateId": "caffb919-053a-4bfa-beba-80567904f842",
          "variables": "sampleAchievementCredential"
        }
      ]
    }
  },
  "credentialTemplates": [
    {
      "id": "caffb919-053a-4bfa-beba-80567904f842",
      "type": "jsonata",
      "template": "{
        \"credential\": {
          \"@context\": [
            \"https://www.w3.org/ns/credentials/v2\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/extensions.json\"
          ],
          \"id\": sampleAchievementCredential.id,
          \"type\": [\"VerifiableCredential\", \"AchievementCredential\"],
          \"issuer\": {
            \"type\": [\"Profile\"],
            \"name\": \"Example Issuer\",
            \"image\": {
              \"type\": \"Image\",
              \"id\": \"https://issuer.example.com/logo.png\"
            }
          },
          \"awardedDate\": sampleAchievementCredential.awardedDate,
          \"validFrom\": sampleAchievementCredential.validFrom,
          \"name\": \"Sample Achievement\",
          \"credentialSubject\": {
            \"id\": results.didAuthRequest.verifiablePresentation.holder,
            \"type\": \"AchievementSubject\",
            \"name\": sampleAchievementCredential.credentialSubject.name,
            \"achievement\": {
              \"id\": sampleAchievementCredential.credentialSubject.achievement.id,
              \"type\": [\"Achievement\"],
              \"achievementType\": sampleAchievementCredential.credentialSubject.achievement.achievementType,
              \"name\": sampleAchievementCredential.credentialSubject.achievement.name,
              \"description\": sampleAchievementCredential.credentialSubject.achievement.description,
              \"alignment\": sampleAchievementCredential.credentialSubject.achievement.alignment
            }
          }
        }
      }"
    }
  ],
  "controller": "did:web:issuer.example.com"
}

对于 openId 选项，特别是 createAuthorizationRequest 和 authorizationRequest 值，下面提供的示例用于帮助开发者理解 OID4VP 授权请求的形式：

示例 14：一个 OID4VP 授权请求

{
  "response_type": "vp_token",
  "presentation_definition": {
    "id": "f1bd224a-0fed-469a-b64a-dad7cf63fd98",
    "input_descriptors": [
      {
        "id": "77d50c71-95ef-442c-a372-f32e17634fab",
        "constraints": {
          "fields": [
            {
              "path": [
                "$['@context']"
              ],
              "filter": {
                "type": "array",
                "contains": {
                  "type": "string",
                  "const": "https://www.w3.org/ns/credentials/v2"
                }
              }
            },
            {
              "path": [
                "$['type']"
              ],
              "filter": {
                "type": "array",
                "contains": {
                  "type": "string",
                  "const": "VerifiableCredential"
                }
              }
            },
            {
              "path": [
                "$['credentialSubject']['name']"
              ],
              "filter": {
                "type": "string"
              }
            }
          ]
        },
        "purpose": "We require a name credential to display your name when you post messages."
      }
    ]
  },
  "response_mode": "direct_post",
  "client_metadata": {
    "vp_formats_supported": {
      "ldp_vc": {
        "proof_type_values": [
          "DataIntegrityProof",
          "Ed25519Signature2020"
        ],
        "cryptosuite_values": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022"
        ]
      }
    },
    "vp_formats": {
      "jwt_vp": {
        "alg": [
          "EdDSA",
          "Ed25519",
          "ES256",
          "ES384"
        ]
      },
      "jwt_vp_json": {
        "alg": [
          "EdDSA",
          "Ed25519",
          "ES256",
          "ES384"
        ]
      },
      "di_vp": {
        "proof_type": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022",
          "Ed25519Signature2020"
        ]
      },
      "ldp_vp": {
        "proof_type": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022",
          "Ed25519Signature2020"
        ]
      }
    }
  },
  "client_id": "https://some.example/workflows/z1A7ojitBF3pGpVzW17MgU7zm/exchanges/z1ACKwiBiXmuGjpKAdKMpBZXB/openid/client/authorization/response",
  "client_id_scheme": "redirect_uri",
  "response_uri": "https://some.example/workflows/z1A7ojitBF3pGpVzW17MgU7zm/exchanges/z1ACKwiBiXmuGjpKAdKMpBZXB/openid/client/authorization/response",
  "nonce": "z1ACKwiBiXmuGjpKAdKMpBZXB"
}

GET /workflows/{localWorkflowId} - 获取现有工作流的配置，并在响应主体中返回。

/workflows/{localWorkflowId} 端点在接收 GET 时可能产生以下任一响应：

响应	主体
200	已检索工作流配置！ content-type: application/json 包含工作流相关信息的对象。它必须是以下形式的对象： `id` [string] 将用于已创建工作流的 ID。传递 ID 是可选的。 `initialStep` [string] 交换开始时使用的上述步骤集合中的步骤。传递 intialStep 是必需的。 `controller` [string] 实例的控制器。传递 controller 是可选的。 `authorization` [object] 授权方案信息（例如 OAuth2 配置）。传递 authorization 是可选的。它必须是以下形式的对象： `oauth2` [object] OAuth2 配置。它必须是以下形式的对象： `issuerConfigUrl` [string] OAuth2 签发者配置 URL。 `credentialTemplates` [array] 用于凭证签发的一个或多个模板。 `template` 字符串应渲染为一个对象，该对象包含 `credential` 字段，用于保存凭证模板，并且（可选）包含 `options` 字段，用于保存重要的凭证签发参数（这是发送到 `POST /credentials/issue` 的请求主体格式）。传递 `credentialTemplates` 是可选的。 `credentialTemplates` 数组中的每一项都必须是以下形式的对象： `type` [string] 模板的类型。 `template` [string] 模板本身。 `steps` [object] 完成该工作流上的交换所需的一个或多个步骤。键是一个或多个步骤名称，其中每个 STEP_NAME 会替换为某个步骤的名称（例如 `request-employee-id`），值是步骤配置。它必须是以下形式的对象： `STEP_NAME` [object] 如果未使用模板，则包含步骤数据。它必须是以下形式的对象： `createChallenge` [boolean] 一个可选的步骤指令，告诉交换通过其拥有 zcap 的 VCALM 验证者服务来处理质询管理。 `verifiablePresentationRequest` [object] 一个可验证出示请求。它必须是以下形式的对象： `query` [array] 请求者发送的一个或多个查询集合。 `query` 数组中的每一项都必须是以下形式的对象： `type` [array] 查询的类型。 `type` 数组中的每一项都必须是字符串。 `credentialQuery` [object] 对于 QueryByExample 查询，指定凭证请求详情。它必须是以下形式的对象： `reason` [string] 说明为什么请求该凭证的人类可读解释。 `example` [object] 一个对象 `acceptedIssuers` [array] 所请求凭证的可接受签发者。 `acceptedIssuers` 数组中的每一项都必须是以下形式的对象： `issuer` [string] `acceptedCryptosuites` [array] 验证者将接受的密码学证明套件。每个元素应该是一个带有 `cryptosuite` 属性的对象，该属性引用 Data Integrity cryptosuite 名称，或用于旧版的 `Ed25519Signature2020` （为向后兼容，也可以使用字符串值，并将其解释为 cryptosuite 名称）。这使持有者能够选择合适的证明格式。此属性可以独立于 `acceptedEnvelopes` 使用，后者仅适用于封装凭证。 `acceptedCryptosuites` 数组中的每一项都必须是 undefined： `acceptedEnvelopes` [array] 验证者将接受的封装格式。每个元素应该是一个带有 `mediaType` 属性的对象，该属性引用封装的媒体类型（为向后兼容，也可以使用字符串值，并将其解释为媒体类型）。这使持有者能够以默认 Data Integrity 格式之外的格式提供凭证。此属性可以独立于 `acceptedCryptosuites` 使用，后者仅适用于使用可接受 cryptosuite 签名的 JSON-LD 凭证。 `acceptedEnvelopes` 数组中的每一项都必须是 undefined： `challenge` [string] 由请求者提供的质询，旨在防止重放攻击，通常预计会包含在可验证出示响应中。 `domain` [string] 由请求者提供的域，旨在防止重放攻击，通常预计会包含在可验证出示响应中。 `interact` [array] 服务器支持的交互机制列表。 `interact` 数组中的每一项都必须是以下形式的对象： `service` [object] 服务器支持的一项服务，能够接收对可验证出示请求的响应。它必须是以下形式的对象： `type` [array] 服务的类型。 `type` 数组中的每一项都必须是字符串。 `serviceEndpoint` [string] 可用于与服务交互以响应可验证出示请求的 URL。 `verifiablePresentation` [object] 以下形式的对象： `@context` [array] 出示的 JSON-LD 上下文。 `@context` 数组中的每一项都必须是字符串。 `id` [string] 出示的 ID。 `type` [array] 出示的 JSON-LD 类型。 `type` 数组中的每一项都必须是字符串。 `holder` [object] 一个对象 `verifiableCredential` [array] 可验证凭证。`verifiableCredential` 数组中的每一项都必须是以下形式的对象： `@context` [array] 凭证的 JSON-LD 上下文。 `@context` 数组中的每一项都必须是字符串。 `id` [string] 凭证的 ID。此属性可以为空。如果未提供，签发者不应该自动生成 id 属性，因为可验证凭证并不要求 id 属性有效，并且存在无法设置 id 属性的用例。 `type` [array] 凭证的 JSON-LD 类型。 `type` 数组中的每一项都必须是字符串。 `issuer` [object] 一个字符串，或以下形式的对象： `id` [string] 签发者 id。 `validFrom` [string] validFrom 日期 `validUntil` [string] validUntil 日期 `credentialSubject` [object] 一个对象 `proof` [object] 由 W3C VC Data Integrity 规范定义的数据完整性证明。它必须是以下形式的对象： `type` [string] 数据完整性证明类型。 `cryptosuite` [string] 密码学套件的名称。 `created` [string] 证明创建日期。 `nonce` [string] 证明创建者选择的一个值，用于出于隐私目的随机化证明值。 `verificationMethod` [string] 用于验证证明的验证方法。 `proofPurpose` [string] 与 verificationMethod 一起使用的证明目的。 `proofValue` [string] Linked Data 证明的值。 `proof` [object] 包含质询和域的数据完整性证明，如 W3C VC Data Integrity 规范所定义。它必须是以下形式的对象： `type` [string] 数据完整性证明类型。 `cryptosuite` [string] 密码学套件的名称。 `created` [string] 证明创建日期。 `challenge` [string] 验证者选择的一个值，用于缓解认证证明重放攻击。 `domain` [string] 证明的域，用于将其使用限制到特定目标。 `nonce` [string] 证明创建者选择的一个值，用于出于隐私目的随机化证明值。 `verificationMethod` [string] 用于验证证明的验证方法。 `proofPurpose` [string] 与 verificationMethod 一起使用的证明目的。 `proofValue` [string] Linked Data 证明的值。 `redirectUrl` [string] 发送给客户端的 URL，可用于在另一个位置继续交互。传递 redirectUrl 是可选的。 `callback` [object] 一个回调，将在此步骤执行后被调用。它必须是以下形式的对象： `url` [string] 将接收回调数据的 URL。 `issueRequests` [array] `issueRequests` 数组中的每一项都必须是 { "required": [ "credentialTemplateId" ] } 或 { "required": [ "credentialTemplateIndex" ] } `presentationSchema` 用于描述要对出示执行的验证的 JSON Schema。它必须是以下形式的对象： `type` [string] 该值必须是 `JsonSchema`。 `jsonSchema` [object] 一个对象，或是在当前步骤中验证出示时使用的另一种出示模式格式。对于特定出示模式类型，预计会有其他属性，但这些属性超出本规范范围。它必须是以下形式的对象： `type` [string] 验证出示时使用的出示模式机制类型。 `verifyPresentationResponseSchema` 用于描述要对验证出示的结果执行的验证的 JSON Schema。它必须是以下形式的对象： `type` [string] 该值必须是 `JsonSchema`。 `jsonSchema` [object] 一个对象，或是在当前步骤中对验证出示的结果使用的另一种出示模式格式。对于特定出示模式类型，预计会有其他属性，但这些属性超出本规范范围。它必须是以下形式的对象： `type` [string] 验证出示的结果时使用的出示模式机制类型。 `nextStep` [string] 序列中下一步的名称。传递 nextStep 是可选的。此字段不得出现在最终步骤配置中。 `openId` [object] 以下之一 { "required": [ "createAuthorizationRequest" ], "not": { "required": [ "authorizationRequest" ] } } 或 { "required": [ "authorizationRequest" ], "not": { "required": [ "createAuthorizationRequest" ] } } 或以下形式的对象： `clientProfiles` [object] 一个对象或以下形式的对象： `stepTemplate` [object] 工作流步骤的模板。必须存在此项或其他步骤数据，但不能同时存在两组数据。它必须是以下形式的对象： `type` [string] 模板的类型。 `template` [string] 步骤模板。
400	无效输入
401	未授权
500	内部错误

有一个与交换关联的 expires 属性，用于表示交换的过期日期和时间。它使用 /workflows/{localWorkflowId}/exchanges 端点创建。这会影响与此类交换关联的质询的生命周期：如果质询绑定到交换，则该质询会在交换的 expires 属性所引用的日期失效。

POST /workflows/{localWorkflowId}/exchanges - 创建新的交换，并在响应标头中返回交换元数据的位置。

/workflows/{localWorkflowId}/exchanges 端点在接收 POST 时使用以下模式：

属性描述

expires [string] 交换过期的日期和时间（表示为 XML Schema dateTimeStamp）。

variables [object] 一个对象

属性	描述
`expires` [string]	交换过期的日期和时间（表示为 XML Schema dateTimeStamp）。
`variables` [object]	一个对象
`openId` [object]	{ "required": [ "createAuthorizationRequest" ], "not": { "required": [ "authorizationRequest" ] } } 或 { "required": [ "authorizationRequest" ], "not": { "required": [ "createAuthorizationRequest" ] } } 或以下形式的对象： `clientProfiles` [object] 一个对象

openId [object]

{
  "required": [
    "createAuthorizationRequest"
  ],
  "not": {
    "required": [
      "authorizationRequest"
    ]
  }
}

或

{
  "required": [
    "authorizationRequest"
  ],
  "not": {
    "required": [
      "createAuthorizationRequest"
    ]
  }
}

或以下形式的对象：

clientProfiles [object]: 一个对象

/workflows/{localWorkflowId}/exchanges 端点在接收 POST 时可能产生以下任一响应：

响应	主体
201	交换已成功创建（带数据）
204	交换已成功创建（不带数据）
400	无效输入
401	未授权
500	内部错误

此端点为客户端提供一种机制，用于查询某个交换支持的所有协议。单个交换可以支持许多协议，这些协议能够实现该交换的目标，例如将可验证凭证签发到数字钱包中。

GET /workflows/{localWorkflowId}/exchanges/{localExchangeId}/protocols - 获取用于与特定交换交互的受支持协议。

/workflows/{localWorkflowId}/exchanges/{localExchangeId}/protocols 端点在接收 GET 时可能产生以下任一响应：

响应	主体
200	交换所理解的协议。 content-type: application/json 包含可用于执行特定交换的协议相关信息的对象。它必须是以下形式的对象： `protocols` [object] 包含一个或多个可用于执行特定交换的协议的对象。它必须是以下形式的对象： `interact` [string] 可在人参与的交换流程中使用的 URL。更多详情请参见关于 interact URL 格式的章节。 `vcapi` [string] 发起 VCALM 交换时使用的 URL。 `OID4VP` [string] 发起 OID4VP 出示时使用的 URL。 `OID4VCI` [string] 发起 OID4VCI 签发时使用的 URL。
400	无效输入
401	未授权
500	内部错误

此端点还使网站运营者能够通过 HTTPS 域将信任委托给第三方（例如服务提供商），从而将执行交换的权限委托给该第三方。例如，网站 brand.example 可以通过在协议列表中使用 saas.example 域，将交换的操作委托给合作伙伴 saas.example。

这使客户端能够依赖其对 brand.example 的信任，将交换的操作委托给第三方，其方式类似于网站链接到来自其他域的资源以渲染网页。

服务器 MAY 包含一个 referenceId 属性在交换消息中。若客户端收到一个 referenceId，则它 SHOULD 包含相同的 referenceId 。这有助于调试，并确保可能延迟或乱序的消息被链接到正确的请求。 referenceId SHOULD 是一个 urn:uuid: 值。

POST /workflows/{localWorkflowId}/exchanges/{localExchangeId} - 参与交换。提交空主体将启动交换，或返回该交换为完成下一步所期望的内容。提交可验证表达请求将产生 4xx 错误，或以下结果之一：符合客户端请求的可验证表达或可验证表达请求。若发送了可验证表达，也可以发送额外的可验证表达请求以继续该交换。

/workflows/{localWorkflowId}/exchanges/{localExchangeId} 端点在接收 POST 时使用以下模式之一：

属性	描述

或者，/workflows/{localWorkflowId}/exchanges/{localExchangeId} 端点也可以使用以下模式：

属性描述

属性	描述
`verifiablePresentationRequest` [对象]	一个可验证表达请求。它 MUST 是如下形式的对象： `query` [数组] 请求者发送的一组一个或多个查询。其中的每一项 `query` 数组 MUST 是如下形式的对象： `type` [数组] 查询的类型。其中的每一项 `type` 数组 MUST 是字符串。 `credentialQuery` [对象] 对于 QueryByExample 查询，指定凭证请求的详细信息。它 MUST 是如下形式的对象： `reason` [字符串] 说明为何请求该凭证的人类可读解释。 `example` [对象] 一个对象 `acceptedIssuers` [数组] 所请求凭证的可接受签发者。其中的每一项 `acceptedIssuers` 数组 MUST 是如下形式的对象： `issuer` [字符串] `acceptedCryptosuites` [数组] 验证者将接受的加密证明套件。每个元素 SHOULD 是带有 `cryptosuite` 属性的对象，该属性引用数据完整性密码套件名称，或引用 `Ed25519Signature2020` 以用于旧版兼容（为向后兼容，也 MAY 使用字符串值，并将其解释为密码套件名称）。这使持有者能够选择适当的证明格式。此属性 MAY 独立于 `acceptedEnvelopes`，后者仅适用于带封套凭证。其中的每一项 `acceptedCryptosuites` 数组 MUST 是 undefined： `acceptedEnvelopes` [数组] 验证者将接受的封套格式。每个元素 SHOULD 是带有 `mediaType` 属性的对象，该属性引用封套的媒体类型（为向后兼容，也 MAY 使用字符串值，并将其解释为媒体类型）。这使持有者能够以默认数据完整性格式以外的格式提供凭证。此属性 MAY 独立于 `acceptedCryptosuites`，后者仅适用于使用可接受密码套件签名的 JSON-LD 凭证。其中的每一项 `acceptedEnvelopes` 数组 MUST 是 undefined： `challenge` [字符串] 一个质询，由请求者提供，旨在防止重放攻击，通常预期会包含在可验证表达响应中。 `domain` [字符串] 一个域，由请求者提供，旨在防止重放攻击，通常预期会包含在可验证表达响应中。 `interact` [数组] 服务器支持的交互机制列表。其中的每一项 `interact` 数组 MUST 是如下形式的对象： `service` [对象] 服务器支持且能够接收对可验证表达请求的响应的服务。它 MUST 是如下形式的对象： `type` [数组] 服务的类型。其中的每一项 `type` 数组 MUST 是字符串。 `serviceEndpoint` [字符串] 可用于与服务交互的 URL，其用途是响应可验证表达请求。
`referenceId` [字符串]	当服务器先前发送了 referenceId 时，客户端 SHOULD 在此处包含它，以帮助调试和消息关联。该值 SHOULD 是 urn:uuid 值。

verifiablePresentationRequest [对象]

一个可验证表达请求。它 MUST 是如下形式的对象：

query [数组]

请求者发送的一组一个或多个查询。其中的每一项 query 数组 MUST 是如下形式的对象：

type [数组]

查询的类型。其中的每一项 type 数组 MUST 是字符串。

credentialQuery [对象]

对于 QueryByExample 查询，指定凭证请求的详细信息。它 MUST 是如下形式的对象：

reason [字符串]

说明为何请求该凭证的人类可读解释。

example [对象]

一个对象

acceptedIssuers [数组]

所请求凭证的可接受签发者。其中的每一项 acceptedIssuers 数组 MUST 是如下形式的对象：

issuer [字符串]

acceptedCryptosuites [数组]

验证者将接受的加密证明套件。每个元素 SHOULD 是带有 cryptosuite 属性的对象，该属性引用数据完整性密码套件名称，或引用 Ed25519Signature2020 以用于旧版兼容（为向后兼容，也 MAY 使用字符串值，并将其解释为密码套件名称）。这使持有者能够选择适当的证明格式。此属性 MAY 独立于 acceptedEnvelopes，后者仅适用于带封套凭证。其中的每一项 acceptedCryptosuites 数组 MUST 是 undefined：

acceptedEnvelopes [数组]

验证者将接受的封套格式。每个元素 SHOULD 是带有 mediaType 属性的对象，该属性引用封套的媒体类型（为向后兼容，也 MAY 使用字符串值，并将其解释为媒体类型）。这使持有者能够以默认数据完整性格式以外的格式提供凭证。此属性 MAY 独立于 acceptedCryptosuites，后者仅适用于使用可接受密码套件签名的 JSON-LD 凭证。其中的每一项 acceptedEnvelopes 数组 MUST 是 undefined：

challenge [字符串]

一个质询，由请求者提供，旨在防止重放攻击，通常预期会包含在可验证表达响应中。

domain [字符串]

一个域，由请求者提供，旨在防止重放攻击，通常预期会包含在可验证表达响应中。

interact [数组]

服务器支持的交互机制列表。其中的每一项 interact 数组 MUST 是如下形式的对象：

service [对象]

服务器支持且能够接收对可验证表达请求的响应的服务。它 MUST 是如下形式的对象：

type [数组]: 服务的类型。其中的每一项 type 数组 MUST 是字符串。
serviceEndpoint [字符串]: 可用于与服务交互的 URL，其用途是响应可验证表达请求。

referenceId [字符串] 当服务器先前发送了 referenceId 时，客户端 SHOULD 在此处包含它，以帮助调试和消息关联。该值 SHOULD 是 urn:uuid 值。

属性描述

属性	描述
`verifiablePresentation` [对象]	如下形式的对象： `@context` [数组] 表达的 JSON-LD 上下文。其中的每一项 `@context` 数组 MUST 是字符串。 `id` [字符串] 表达的 ID。 `type` [数组] 表达的 JSON-LD 类型。其中的每一项 `type` 数组 MUST 是字符串。 `holder` [对象] 一个对象 `verifiableCredential` [数组] 可验证凭证。其中的每一项 `verifiableCredential` 数组 MUST 是如下形式的对象： `@context` [数组] 凭证的 JSON-LD 上下文。其中的每一项 `@context` 数组 MUST 是字符串。 `id` [字符串] 凭证的 ID。此属性 MAY 为空。如果未提供，签发者 SHOULD NOT 自动生成 id 属性，因为可验证凭证不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [数组] 凭证的 JSON-LD 类型。其中的每一项 `type` 数组 MUST 是字符串。 `issuer` [对象] 字符串或如下形式的对象： `id` [字符串] 签发者 ID。 `validFrom` [字符串] validFrom 日期 `validUntil` [字符串] validUntil 日期 `credentialSubject` [对象] 一个对象 `proof` [对象] W3C VC 数据完整性规范所定义的数据完整性证明。它 MUST 是如下形式的对象： `type` [字符串] 数据完整性证明类型。 `cryptosuite` [字符串] 密码套件的名称。 `created` [字符串] 证明创建的日期。 `nonce` [字符串] 证明创建者选择的值，用于出于隐私目的对证明值进行随机化。 `verificationMethod` [字符串] 用于验证证明的验证方法。 `proofPurpose` [字符串] 与 verificationMethod 一起使用的证明目的。 `proofValue` [字符串] 链接数据证明的值。 `proof` [对象] 包含质询和域的数据完整性证明，如 W3C VC 数据完整性规范所定义。它 MUST 是如下形式的对象： `type` [字符串] 数据完整性证明类型。 `cryptosuite` [字符串] 密码套件的名称。 `created` [字符串] 证明创建的日期。 `challenge` [字符串] 验证者选择的值，用于缓解认证证明重放攻击。 `domain` [字符串] 证明的域，用于将其使用限制到特定目标。 `nonce` [字符串] 证明创建者选择的值，用于出于隐私目的对证明值进行随机化。 `verificationMethod` [字符串] 用于验证证明的验证方法。 `proofPurpose` [字符串] 与 verificationMethod 一起使用的证明目的。 `proofValue` [字符串] 链接数据证明的值。
`referenceId` [字符串]	当服务器先前发送了 referenceId 时，客户端 SHOULD 在此处包含它，以帮助调试和消息关联。该值 SHOULD 是 urn:uuid 值。

verifiablePresentation [对象]

如下形式的对象：

@context [数组]

表达的 JSON-LD 上下文。其中的每一项 @context 数组 MUST 是字符串。

id [字符串]

表达的 ID。

type [数组]

表达的 JSON-LD 类型。其中的每一项 type 数组 MUST 是字符串。

holder [对象]

一个对象

verifiableCredential [数组]

可验证凭证。其中的每一项 verifiableCredential 数组 MUST 是如下形式的对象：

@context [数组]

凭证的 JSON-LD 上下文。其中的每一项 @context 数组 MUST 是字符串。

id [字符串]

凭证的 ID。此属性 MAY 为空。如果未提供，签发者 SHOULD NOT 自动生成 id 属性，因为可验证凭证不要求 id 属性才有效，并且存在无法设置 id 属性的用例。

type [数组]

凭证的 JSON-LD 类型。其中的每一项 type 数组 MUST 是字符串。

issuer [对象]

字符串或如下形式的对象：

id [字符串]: 签发者 ID。

validFrom [字符串]

validFrom 日期

validUntil [字符串]

validUntil 日期

credentialSubject [对象]

一个对象

proof [对象]

W3C VC 数据完整性规范所定义的数据完整性证明。它 MUST 是如下形式的对象：

type [字符串]: 数据完整性证明类型。
cryptosuite [字符串]: 密码套件的名称。
created [字符串]: 证明创建的日期。
nonce [字符串]: 证明创建者选择的值，用于出于隐私目的对证明值进行随机化。
verificationMethod [字符串]: 用于验证证明的验证方法。
proofPurpose [字符串]: 与 verificationMethod 一起使用的证明目的。
proofValue [字符串]: 链接数据证明的值。

proof [对象]

包含质询和域的数据完整性证明，如 W3C VC 数据完整性规范所定义。它 MUST 是如下形式的对象：

type [字符串]: 数据完整性证明类型。
cryptosuite [字符串]: 密码套件的名称。
created [字符串]: 证明创建的日期。
challenge [字符串]: 验证者选择的值，用于缓解认证证明重放攻击。
domain [字符串]: 证明的域，用于将其使用限制到特定目标。
nonce [字符串]: 证明创建者选择的值，用于出于隐私目的对证明值进行随机化。
verificationMethod [字符串]: 用于验证证明的验证方法。
proofPurpose [字符串]: 与 verificationMethod 一起使用的证明目的。
proofValue [字符串]: 链接数据证明的值。

referenceId [字符串] 当服务器先前发送了 referenceId 时，客户端 SHOULD 在此处包含它，以帮助调试和消息关联。该值 SHOULD 是 urn:uuid 值。

属性	描述
`redirectUrl` [字符串]	客户端 MAY 将交互 URL 作为 redirectUrl 发送给服务器，邀请服务器成为另一个相关交换的客户端，并从该交互 URL 开始。服务器 MAY 与此 redirectUrl 交互。
`referenceId` [字符串]	当服务器先前发送了 referenceId 时，客户端 SHOULD 在此处包含它，以帮助调试和消息关联。该值 SHOULD 是 urn:uuid 值。

/workflows/{localWorkflowId}/exchanges/{localExchangeId} 端点在接收 POST 时可能产生以下任一响应：

响应	主体
200	交换已推进。 content-type: application/json 如下形式的对象： `verifiablePresentationRequest` [对象] 一个可验证表达请求。它 MUST 是如下形式的对象： `query` [数组] 请求者发送的一组一个或多个查询。其中的每一项 `query` 数组 MUST 是如下形式的对象： `type` [数组] 查询的类型。其中的每一项 `type` 数组 MUST 是字符串。 `credentialQuery` [对象] 对于 QueryByExample 查询，指定凭证请求的详细信息。它 MUST 是如下形式的对象： `reason` [字符串] 说明为何请求该凭证的人类可读解释。 `example` [对象] 一个对象 `acceptedIssuers` [数组] 所请求凭证的可接受签发者。其中的每一项 `acceptedIssuers` 数组 MUST 是如下形式的对象： `issuer` [字符串] `acceptedCryptosuites` [数组] 验证者将接受的加密证明套件。每个元素 SHOULD 是带有 `cryptosuite` 属性的对象，该属性引用数据完整性密码套件名称，或引用 `Ed25519Signature2020` 以用于旧版兼容（为向后兼容，也 MAY 使用字符串值，并将其解释为密码套件名称）。这使持有者能够选择适当的证明格式。此属性 MAY 独立于 `acceptedEnvelopes`，后者仅适用于带封套凭证。其中的每一项 `acceptedCryptosuites` 数组 MUST 是 undefined： `acceptedEnvelopes` [数组] 验证者将接受的封套格式。每个元素 SHOULD 是带有 `mediaType` 属性的对象，该属性引用封套的媒体类型（为向后兼容，也 MAY 使用字符串值，并将其解释为媒体类型）。这使持有者能够以默认数据完整性格式以外的格式提供凭证。此属性 MAY 独立于 `acceptedCryptosuites`，后者仅适用于使用可接受密码套件签名的 JSON-LD 凭证。其中的每一项 `acceptedEnvelopes` 数组 MUST 是 undefined： `challenge` [字符串] 一个质询，由请求者提供，旨在防止重放攻击，通常预期会包含在可验证表达响应中。 `domain` [字符串] 一个域，由请求者提供，旨在防止重放攻击，通常预期会包含在可验证表达响应中。 `interact` [数组] 服务器支持的交互机制列表。其中的每一项 `interact` 数组 MUST 是如下形式的对象： `service` [对象] 服务器支持且能够接收对可验证表达请求的响应的服务。它 MUST 是如下形式的对象： `type` [数组] 服务的类型。其中的每一项 `type` 数组 MUST 是字符串。 `serviceEndpoint` [字符串] 可用于与服务交互的 URL，其用途是响应可验证表达请求。 `referenceId` [字符串] 用于关联交换消息的可选标识符。服务器 MAY 包含此值；若存在，客户端 SHOULD 在其下一条消息中包含它。该值 SHOULD 是 urn:uuid 值。或如下形式的对象： `verifiablePresentation` [对象] 如下形式的对象： `@context` [数组] 表达的 JSON-LD 上下文。其中的每一项 `@context` 数组 MUST 是字符串。 `id` [字符串] 表达的 ID。 `type` [数组] 表达的 JSON-LD 类型。其中的每一项 `type` 数组 MUST 是字符串。 `holder` [对象] 一个对象 `verifiableCredential` [数组] 可验证凭证。其中的每一项 `verifiableCredential` 数组 MUST 是如下形式的对象： `@context` [数组] 凭证的 JSON-LD 上下文。其中的每一项 `@context` 数组 MUST 是字符串。 `id` [字符串] 凭证的 ID。此属性 MAY 为空。如果未提供，签发者 SHOULD NOT 自动生成 id 属性，因为可验证凭证不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [数组] 凭证的 JSON-LD 类型。其中的每一项 `type` 数组 MUST 是字符串。 `issuer` [对象] 字符串或如下形式的对象： `id` [字符串] 签发者 ID。 `validFrom` [字符串] validFrom 日期 `validUntil` [字符串] validUntil 日期 `credentialSubject` [对象] 一个对象 `proof` [对象] W3C VC 数据完整性规范所定义的数据完整性证明。它 MUST 是如下形式的对象： `type` [字符串] 数据完整性证明类型。 `cryptosuite` [字符串] 密码套件的名称。 `created` [字符串] 证明创建的日期。 `nonce` [字符串] 证明创建者选择的值，用于出于隐私目的对证明值进行随机化。 `verificationMethod` [字符串] 用于验证证明的验证方法。 `proofPurpose` [字符串] 与 verificationMethod 一起使用的证明目的。 `proofValue` [字符串] 链接数据证明的值。 `proof` [对象] 包含质询和域的数据完整性证明，如 W3C VC 数据完整性规范所定义。它 MUST 是如下形式的对象： `type` [字符串] 数据完整性证明类型。 `cryptosuite` [字符串] 密码套件的名称。 `created` [字符串] 证明创建的日期。 `challenge` [字符串] 验证者选择的值，用于缓解认证证明重放攻击。 `domain` [字符串] 证明的域，用于将其使用限制到特定目标。 `nonce` [字符串] 证明创建者选择的值，用于出于隐私目的对证明值进行随机化。 `verificationMethod` [字符串] 用于验证证明的验证方法。 `proofPurpose` [字符串] 与 verificationMethod 一起使用的证明目的。 `proofValue` [字符串] 链接数据证明的值。 `referenceId` [字符串] 用于关联交换消息的可选标识符。服务器 MAY 包含此值；若存在，客户端 SHOULD 在其下一条消息中包含它。该值 SHOULD 是 urn:uuid 值。如下形式的对象： `redirectUrl` [字符串] 交换希望将客户端重定向到的 URL。 `referenceId` [字符串] 用于关联交换消息的可选标识符。服务器 MAY 包含此值；若存在，客户端 SHOULD 在其下一条消息中包含它。该值 SHOULD 是 urn:uuid 值。一个不含交换继续属性的对象，表示服务器希望终止该交换。它 MUST 是如下形式的对象： `referenceId` [字符串] 用于关联交换消息的可选标识符。服务器 MAY 包含此值；若存在且有下一条消息要发送，则客户端 SHOULD 在其下一条消息中包含它。该值 SHOULD 是 urn:uuid 值。
400	无效输入
401	未授权
500	内部错误

GET /workflows/{localWorkflowId}/exchanges/{localExchangeId} - 获取现有交换的状态，并在响应主体中返回它。

/workflows/{localWorkflowId}/exchanges/{localExchangeId} 端点在接收 GET 时可能产生以下任一响应：

响应	主体
200	已检索交换配置！ content-type: application/json 包含活动交换相关信息的对象。当给定交换没有要发送的 VP 且没有 redirectUrl 时，它可以是空对象。它 MUST 是如下形式的对象： `id` [字符串] 用于标识该交换的本地交换 ID。 `sequence` [整数] 交换的序列号。创建时设置为 0。 `expires` [字符串] 交换过期的日期和时间（表示为 XML Schema dateTimeStamp）。 `step` [字符串] 交换中的当前步骤。 `state` [字符串] 交换的状态（"pending" \| "active" \| "complete" \| "invalid"），创建时设置为 "pending"。 `lastError` [对象] 如下形式的对象： `type` [字符串] 标识问题类型的 URL。 `title` [字符串] 用于描述该问题的简短但具体的人类可读字符串。 `detail` [字符串] 用于描述该问题的更长的人类可读字符串。 `variables` [对象] 交换所需的变量。它 MUST 是如下形式的对象： `results` [对象] 来自交换各步骤的结果。它 MUST 是如下形式的对象： `STEP_NAME` [对象] 来自交换某个步骤的结果。它 MUST 是如下形式的对象： `verifiablePresentation` [对象] 如下形式的对象： `@context` [数组] 表达的 JSON-LD 上下文。其中的每一项 `@context` 数组 MUST 是字符串。 `id` [字符串] 表达的 ID。 `type` [数组] 表达的 JSON-LD 类型。其中的每一项 `type` 数组 MUST 是字符串。 `holder` [对象] 一个对象 `verifiableCredential` [数组] 可验证凭证。其中的每一项 `verifiableCredential` 数组 MUST 是如下形式的对象： `@context` [数组] 凭证的 JSON-LD 上下文。其中的每一项 `@context` 数组 MUST 是字符串。 `id` [字符串] 凭证的 ID。此属性 MAY 为空。如果未提供，签发者 SHOULD NOT 自动生成 id 属性，因为可验证凭证不要求 id 属性才有效，并且存在无法设置 id 属性的用例。 `type` [数组] 凭证的 JSON-LD 类型。其中的每一项 `type` 数组 MUST 是字符串。 `issuer` [对象] 字符串或如下形式的对象： `id` [字符串] 签发者 ID。 `validFrom` [字符串] validFrom 日期 `validUntil` [字符串] validUntil 日期 `credentialSubject` [对象] 一个对象 `proof` [对象] W3C VC 数据完整性规范所定义的数据完整性证明。它 MUST 是如下形式的对象： `type` [字符串] 数据完整性证明类型。 `cryptosuite` [字符串] 密码套件的名称。 `created` [字符串] 证明创建的日期。 `nonce` [字符串] 证明创建者选择的值，用于出于隐私目的对证明值进行随机化。 `verificationMethod` [字符串] 用于验证证明的验证方法。 `proofPurpose` [字符串] 与 verificationMethod 一起使用的证明目的。 `proofValue` [字符串] 链接数据证明的值。 `proof` [对象] 包含质询和域的数据完整性证明，如 W3C VC 数据完整性规范所定义。它 MUST 是如下形式的对象： `type` [字符串] 数据完整性证明类型。 `cryptosuite` [字符串] 密码套件的名称。 `created` [字符串] 证明创建的日期。 `challenge` [字符串] 验证者选择的值，用于缓解认证证明重放攻击。 `domain` [字符串] 证明的域，用于将其使用限制到特定目标。 `nonce` [字符串] 证明创建者选择的值，用于出于隐私目的对证明值进行随机化。 `verificationMethod` [字符串] 用于验证证明的验证方法。 `proofPurpose` [字符串] 与 verificationMethod 一起使用的证明目的。 `proofValue` [字符串] 链接数据证明的值。 `openId` [对象] 来自 OID4VCI/OID4VP 持有者交互的结果。它 MUST 是如下形式的对象： `clientProfileId` [对象] 一个对象 `authorizationResponse` [对象] 一个对象 `presentationSubmission` [对象] 一个对象 `inviteRequest` [对象] 来自邀请请求的结果。它 MUST 是如下形式的对象： `inviteResponse` [对象] 对邀请请求的响应，指示将持有者重定向到何处。它 MUST 是如下形式的对象： `url` [字符串] 交换应继续进行的 URL。 `purpose` [字符串] 交互描述。 `referenceId` [字符串] 邀请请求的唯一 ID。
400	无效输入
401	未授权
500	内部错误

POST /callbacks/{localCallbackId} - 一种回调，可以是任何能力 URL（即难以猜测的 URL），当执行交换步骤时可以收到通知。该 URL SHOULD 是能力 URL，以确保它只能由被共享该 URL 的各方使用，而无需授权令牌、周期性令牌刷新或客户端注册。若使用带有 "localCallbackId" 的建议 URL 格式，则 "localCallbackId" 值必须表达至少 128 位随机信息，以确保完整回调 URL 可被视为能力 URL。还建议为每个交换创建新的能力 URL，并且仅由该交换使用。

/callbacks/{localCallbackId} 端点在接收 POST 时使用以下模式：

属性	描述
`event` [对象]	与回调关联的事件信息。它 MUST 是如下形式的对象： `data` [对象] 与回调关联的事件数据。它 MUST 是如下形式的对象： `exchangeId` [字符串] 指向交换状态的 URL，可用于检索该交换的当前状态。

/callbacks/{localCallbackId} 端点在接收 POST 时可能产生以下任一响应：

响应	主体
200	已接收回调数据。
400	未接收回调数据。

本规范中的 API 使得可以执行无中介（自动化、机器到机器）或有中介（人在环路中）的交换。这些交换由持有者协调器发起，并由实现交换的任何协调器响应。流程由以下步骤组成：

该持有者协调器联系接收方协调器，以请求启动特定交换。
接收方协调器以某种表达请求进行响应，以认证和/或授权持有者协调器并以 URL 形式提供交换中的下一跳。
该持有者协调器以包含满足表达请求的信息的可验证表达响应接收方协调器。
接收方协调器使用带有新签发可验证凭证的可验证表达，或如上文步骤 2 所述的进一步表达请求进行响应。

该持有者协调器 MAY 调用协调器的交换发现端点，以确定持有者协调器是否支持协调器在特定端点上的协议要求，然后再实际启动交换。

上述步骤的图示如下：

注

上述通用交换可以以完全自动化、由人中介，或以混合方式执行；在混合方式中，部分流程是自动化的，但在某些阶段需要人的交互。上述第二步用于提供指引，说明下一步是自动化的，还是需要个人介入。

下图展示了一种交换，其中持有者协调器以可验证表达请求发起，要求接收方协调器提供凭证后才继续：

下图展示了一种交换，其中持有者协调器在收到服务器的初始请求后发送反向请求：

图 6 一种交换中途的反向请求，其中持有者向签发者/验证者在收到服务器的初始请求后请求凭证。

以下示例演示交换客户端使用 verifiablePresentationRequest 发起交换，该请求指定其将接受哪些加密证明格式和封套类型。若 credentialQuery 属性不存在，则交换客户端将接受来自工作流服务、匹配指定格式的任何凭证。

示例 15：带有可接受格式的客户端发起交换

{
  "verifiablePresentationRequest": {
    "query": [{
      "type": "QueryByExample",
      "credentialQuery": {
        "acceptedCryptosuites": [
          {"cryptosuite": "eddsa-rdfc-2022"},
          {"cryptosuite": "ecdsa-rdfc-2019"},
          {"cryptosuite": "bbs-2023"}
        ],
        "acceptedEnvelopes": [
          {"mediaType": "application/jwt"}
        ]
      }
    }]
  }
}

以下示例演示交换客户端在满足任何后续请求之前，先向工作流服务请求凭证。在此场景中，交换客户端在共享个人信息之前，需要证明服务器运营者是注册企业。

示例 16：客户端在继续之前请求服务器凭证

{
  "verifiablePresentationRequest": {
    "query": [{
      "type": "QueryByExample",
      "credentialQuery": {
        "reason": "Please present your BusinessRegistrationCredential to complete the verification process.",
        "example": {
          "@context": [
            "https://www.w3.org/ns/credentials/v2"
          ],
          "type": ["BusinessRegistrationCredential"]
        },
        "acceptedCryptosuites": [
          {"cryptosuite": "eddsa-rdfc-2022"}
        ]
      }
    }]
  }
}

对于一个实现来说，向另一个实现传达如何开始与其交互是有用的。这个引导过程称为 启动一次交互，它会传达每个实现支持哪些协议，以及如何与该实现开始一次特定的交互。

注：交互与应用、用例和协议无关

虽然本文档中包含若干交互规范，但其通用方法并不依赖于用例、应用或协议。此方法可用于配对两个或更多希望引导进入特定协议的应用，而不受任何传输媒介限制——例如 Web 浏览器、QR 码（光学媒介）或 NFC（无线媒介）——并且该协议不需要涉及此 API。

下面的序列图概述了一个签发者生成交互 URL、使用 QR 码与持有者共享它，并继续使用 vcapi 协议的过程：

下面的序列图概述了一个验证者生成交互 URL、使用 QR 码与持有者共享它，并继续使用 vcapi 协议的过程：

下面的序列图概述了一个持有者生成交互 URL，使用 QR 码与验证者共享它，并继续使用 inviteRequest 协议的过程：

交互 URL 的格式必须符合 URL 标准的语法，并包含一个 iuv 查询参数，用于编码交互 URL 版本号；在使用此版本的本 API 时，该版本号必须为 1。交互 URL 应该是一个 HTTPS URL，并包含一个特定于交互的标识符。该 URL 应该是不透明的，并且在接收系统获取它之前，不需要进行 URL 语法处理。此类 URL 的示例如下：

示例 17：一个交互 URL

https://app.example/interactions/z8n38Dp7a?iuv=1

将较长的协议特定信息编码到 URL 中的协议，会受到软件库对 URL 最大允许长度所施加的限制。在撰写本文时，建议的 URL 长度限制约为 2,000 个字符。实现者不应该把可以在对交互 URL 的 GET 请求响应中表达的信息（该响应在第 3.7.4 交互协议响应中定义）放入交互 URL 的查询参数中。

注：交互 URL 位于协调器上，而不是工作流服务上

协调器可以自由地将交互 URL 放在其 Web 源上的任意位置，因为消费软件预计会将其视为不透明的（iuv 查询参数除外）。但是，重要的是交互 URL 应托管在协调器上，而不是托管在工作流服务上。这使协调器的 Web 源（DNS 域名）能够被消费者用作一致的信任信号，并用于应用可能调节操作的业务规则。

交互 QR 码必须是一个交互 URL，并按照 ISO18004:2024：QR Code Bar Code Symbology Specification 表示为 QR 码。为确保广泛的互操作性，交互 URL 的长度应该尽可能短，不应该超过 400 个字母数字字符，并且不得超过 4,296 个字母数字字符。下面给出了一个交互 QR 码的示例：

一个由黑白点填充的正方形图像，其中编码了
一个交互 URL — 图 10 `https://app.example/interactions/z8n38Dp7a?iuv=1` 的交互 QR 码

调用一个能够处理交互 URL 的应用可能很有用。本节为此目的定义了一个 interaction: 协议方案格式。协议方案的格式必须符合以下语法：

交互协议方案
scheme = "interaction:" interaction-url interaction-url = URL

interaction-url 是任何符合 URL 标准的 URL，并且检索该 URL 处的资源会得到一个交互协议响应。

示例 18：一个交互方案 URL 的示例

interaction:https://app.example/interactions/z8n38Dp7a?iuv=1

对交互 URL执行检索，会得到关于如何开始与远程系统交互的说明。

当使用值为 application/json 的 Accept 标头获取交互 URL 时，必须返回一个包含 protocols 映射的单个 JSON 对象，其中每个键都是协议标识符，并且每个值都是可用于发起该交互的 URL。例如，对 https://app.example/interactions/z8n38Dp7a?iuv=1 交互 URL执行 HTTP GET，可能会得到以下任一响应：

示例 19：给定交互所支持的协议列表，其中 inviteRequest 由正在使用的工作流服务生成。

{
  "protocols": {
    "inviteRequest": "https://saas.example/workflows/123/exchanges/987/invite-request/response",
    "vcapi": "https://saas.example/workflows/123/exchanges/987",
    "OID4VP": "openid4vp://?client_id=https%3A%2F%2Fapp.example%2Fworkflows%2F123%2Fexchanges%2F987%2Fopenid%2Fclient%2Fauthorization%2Fresponse&request_uri=https%3A%2F%2Fapp.example%2Fworkflows%2F123%2Fexchanges%2F987%2Fopenid%2Fclient%2Fauthorization%2Frequest'"
  }
}

示例 20：协议列表仅包含 inviteRequest 选项的退化情形。

{
  "protocols": {
    "inviteRequest": "https://saas.example/interactions/123/invite-request/response"
  }
}

协议响应使协议执行能够通过 HTTPS 域信任模型委托给第三方服务提供商，这类似于获取交换协议一节中描述的委托机制。例如，网站 app.example 可以通过在协议列表中包含 saas.example 域，将交换的操作委托给合作伙伴 saas.example。

当使用任何无法识别的 Accept 标头获取交互 URL 时，必须返回一个 text/html 文档，其中包含指示人类使用特定软件的说明，该软件知道如何处理交互 URL。

注：映射到交换 URL

一些协调器实现会将 protocols 端点实现为到某个交换实例的 protocols 端点的透传。例如，对 https://app.example/interactions/z8n38Dp7a?iuv=1 执行 GET，会导致对 https://app.example/workflows/123/exchanges/987/protocols 的透传 GET，后者将返回上面的响应。以这种方式实现交互 URL 可以提供更容易的实现路径。

inviteRequest 交互协议由本地系统使用，用于通过特定 URL 向远程系统表示它希望获得前往远程系统的邀请，例如前往一个个人可以参与用例特定交互的网站。如果选择了 inviteRequest 交互协议，本地系统会使用 HTTP POST 发送数据，以指示远程系统应该将该个人发送到哪里。下面展示了几个 POST 数据示例。这些示例旨在强调，本规范并未规定 "url" 字段应如何格式化，但确实建议此交互机制的实现者使用唯一 ID：

示例 21：对邀请请求的响应，用于在商店结账

{
  "url": "https://website.example/checkout/8372974",
  "purpose": "Checkout at ShopCo",
  "referenceId": "417bcaf2-14d9-11f0-99d7-9f094678517b"
}

示例 22：对邀请请求的响应，用于填写在线表单

{
  "url": "https://website.example/forms/7864165",
  "purpose": "Fill out online form",
  "referenceId": "d4a6e5b8-1715-4654-8e47-e68b311756d1"
}

vcapi 交互协议用于发起一个特定交换，如第 3.6.5 参与交换所述。

示例 23：一个 VC-API 交互协议请求

{
  "verifiablePresentationRequest": {
    "query": [{
      "type": "QueryByExample",
      "credentialQuery": {
        "reason": "Please provide your student ID.",
        "example": {
          "@context": [
            "https://www.w3.org/ns/credentials/v2",
            "https://www.w3.org/ns/credentials/examples/v2",
          ],
          "type": "StudentIdCredential",
          "credentialSubject": {
            "studentId": ""
          },
        },
        "trustedIssuer": [{
          "issuer": "did:web:university.example"
        }]
      }
    }],
    "challenge": "5e34826e-14da-11f0-98a5-8b1c0a196728",
    "domain": "university.example"
  }
}

当一个实现在处理文档时检测到异常时，可以使用 ProblemDetails 对象向其他软件系统报告该问题。这些对象的接口遵循 [RFC9457] 来编码数据。一个 ProblemDetails 映射由以下属性组成：

type: type 键必须存在，并且其值必须是一个用于标识问题类型的 URL。
title: title 键应该为该问题提供一个简短但具体的人类可读字符串。
detail: detail 键应该为该问题提供一个更长的人类可读字符串。

鼓励利用键（例如 detail 和 instance）来提供有关错误的更多上下文反馈，同时注意安全问题，因此不要披露敏感信息。

本规范定义了以下问题描述类型：

https://www.w3.org/TR/vcalm#UNKNOWN_OPTION_PROVIDED: 向 API 调用提供了一个实现未知的选项。

实现可能报告的其他 ProblemDetails 列表可在以下规范中找到：

示例 24：一个 ProblemDetails 对象示例

{
  "type": "https://www.w3.org/TR/vc-data-model#CRYPTOGRAPHIC_SECURITY_ERROR",
  "status": 400,
  "title": "CRYPTOGRAPHIC_SECURITY_ERROR",
  "detail": "The cryptographic security mechanism couldn't be verified. This is likely due to a malformed proof or an invalid verificationMethod."
}

议题 3

上述示例 type URL 将在 VCDM v2.0 成为全球标准之后生效。为确保错误链接到适当的位置，你可以暂时将 https://www.w3.org/TR/vc-data-model 的基 URL 替换为 www.w3.org/TR/vc-data-model-2.0。

强烈建议实现者在生产环境中清理所有服务器错误，因为不这样做可能导致信息披露。

建议在执行验证时避免抛出错误，而是收集 ProblemDetails 对象并将其包含在验证结果中。

本规范定义了验证错误和验证警告之间的区别。错误是与密码学、数据模型以及格式不正确的上下文相关的 ProblemDetails，并且不可恢复。警告是与状态和有效期相关的 ProblemDetails，并且可能是可恢复的，或将后续操作留给应用自行决定。

如果包含错误，则 VerificationResponse 对象的 verified 属性必须设置为 false；如果不包含错误，则该属性必须设置为 true。

示例 25：包含警告和错误的验证响应示例。

{
  "verified": false,
  "document": verifiableCredential,
  "mediaType": "application/vc",
  "controller": issuer,
  "controllerDocument": didDocument,
  "warnings": [ProblemDetails],
  "errors": [ProblemDetails]
}

属性	描述
`credentialId` [string]	标识凭证（该标识符不必出现在 VC 本身中）。
`credentialStatus` [object]	标识要更新的特定状态列表条目。它必须是以下形式的对象： `id` [string] `type` [string] `statusPurpose` [string] `statusListIndex` [string] `statusListCredential` [string]
`status` [boolean]	指定新的状态。
`indexAllocator` [string]	供服务使用，用于确定哪些索引正被使用/分配给 VC。

属性	描述
`statusPurpose` [string]	状态列表的用途（例如 "revocation"、"suspension"）。这决定了列表将跟踪哪种类型的状态信息。
`id` [string]	状态列表的可选标识符。如果未提供，服务将生成一个。
`options` [object]	一个对象

响应	主体
200	凭证状态已成功更新
400	错误请求
404	未找到凭证

VCALM v1.0

用于生命周期管理的可验证凭证 API

摘要

本文档状态

1. 引言

1.1 设计目标和原理

HTTP API 设计指南

1.2 架构概述

1.3 一致性

1.4 术语

2. 架构

2.1 协调器

2.2 服务

2.3 实例

2.4 配置

基准 URL

授权

被禁止的授权

OAuth 2.0

选项

内容序列化

载荷大小

3. HTTP API

3.1 组件概述

签发者协调器

签发者服务

验证者协调器

验证者服务

持有者协调器

持有者服务

状态服务

工作流服务

3.2 签发

3.2.1 签发凭证

3.2.2 获取特定凭证

3.2.3 删除特定 凭证

3.3 验证

3.3.1 验证凭证

3.3.2 验证表达

3.3.3 创建质询

3.4 请求表达

3.4.1 可验证 表达请求

3.4.2 按示例查询

3.4.3 DID 认证

3.4.3.1 DID Authentication 查询格式

3.4.3.2 DID Authentication 响应格式

3.4.4 授权 能力请求

3.4.5 查询中的逻辑操作

3.4.5.1 顶层 查询（"AND" 操作）

3.4.5.2 嵌套查询 （"OR" 操作）

3.5 出示

3.5.1 派生凭证

3.5.2 创建表达

3.5.3 获取表达

3.5.4 获取特定 表达

3.5.5 删除特定 表达

3.6 工作流和交换

3.6.1 创建工作流

3.6.2 获取工作流配置

3.6.3 创建交换

3.6.4 获取交换协议

3.6.5 参与交换

3.6.6 获取交换状态

3.6.7 交换步骤回调

3.6.8 交换示例

3.7 启动交互

3.7.1 交互 URL 格式

3.7.2 交互 QR 码格式

3.7.3 交互方案格式

3.7.4 交互协议 响应

3.7.5 inviteRequest 交互协议

3.7.6 vcapi 交互协议

3.8 错误处理

3.8.1 验证错误 与警告

A. 隐私注意事项

A.1 委托

A.2 “回拨归属方”被认为 有害

B. 安全注意事项

B.1 未知证明类型

B.2 对交互 URL 使用 HTTPS

3.2.3 删除特定凭证

3.4.1 可验证表达请求

3.4.4 授权能力请求

3.4.5.1 顶层查询（"AND" 操作）

3.4.5.2 嵌套查询（"OR" 操作）

3.5.4 获取特定表达

3.5.5 删除特定表达

3.7.4 交互协议响应

3.7.5 `inviteRequest` 交互协议

3.7.6 `vcapi` 交互协议

3.8.1 验证错误与警告

A.2 “回拨归属方”被认为有害

D. 工作流步骤和模板示例

D.1 最小可行步骤和凭证模板

E. 与其他规范的关系