Skip to content

Commit

Permalink
Merge pull request eclipse-dataspace-dcp#100 from arnoweiss/main
Browse files Browse the repository at this point in the history 
Restructure VPP section
  • Loading branch information
@jimmarino
jimmarino authored Nov 15, 2024
2 parents 18f9cb5 + 78443dd commit 826f468
Show file tree
Hide file tree
Showing 3 changed files with 66 additions and 81 deletions.
4 changes: 3 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
.idea/
/*.png
/*.png
/*.yaml
resources
3 changes: 2 additions & 1 deletion index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<script class='remove'>
var respecConfig = {
specStatus: "unofficial",
latestVersion: null,
latestVersion: "https://github.com/eclipse-dataspace-dcp/decentralized-claims-protocol/releases/tag/0.8.1",
postProcess: [window.respecMermaid.createFigures],
editors: [{
name: "Jim Marino",
Expand All @@ -22,6 +22,7 @@
xref: "web-platform",
lint: { "no-unused-dfns": false },
format: "markdown",
maxTocLevel: 3,
localBiblio: {
"dsp-base": {
title: "Dataspace Protocol 2024-1",
Expand Down
140 changes: 61 additions & 79 deletions specifications/verifiable.presentation.protocol.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ resolve credential-related resources. The protocol also provides a mechanism for
The following sequence diagram depicts a non-normative flow where a client interacts with a [=Verifier=] to present a
[=Verifiable Credential=]:

![alt text 2](specifications/auth.flow.png "Presentation Flow")
![alt text 2](auth.flow.png "Presentation Flow")

1. The client sends a request to its [=Secure Token Service=] for a [=Self-Issued ID Token=]. The API used to make this
request is implementation specific. The client may include a set of scopes that define the Verifiable Credentials the
Expand All @@ -46,7 +46,8 @@ The client [=DID Service=] MUST make the [=Credential Service=] available as a `
The `serviceEndpoint` property MUST be interpreted by the Verifier as the base URL of the [=Credential Service=]. The
following is a non-normative example of a `Credential Service` entry:

```json
<aside class="example" title="Credential Service Entry in DID document">
<pre class="json">
{
"@context": [
"https://www.w3.org/ns/did/v1",
Expand All @@ -60,7 +61,8 @@ following is a non-normative example of a `Credential Service` entry:
}
]
}
```
</pre>
</aside>

## Credential Service Security

Expand All @@ -80,42 +82,39 @@ be submitted in the HTTP `Authorization` header prefixed with `Bearer` of the re
## Resolution API

The Resolution API defines the [=Credential Service=] endpoint for querying credentials and returning a set
of [=Verifiable
Presentations=].
of [=Verifiable Presentations=].

If a client is not authorized for an endpoint request, the [=Credential Service=] SHOULD return `4xx Client Error`. The
exact error code is implementation-specific.

### Query For Presentations

[=Verifiable Presentations=] can be queried by POSTing a `PresentationQueryMessage` message to the query endpoint:
`POST /presentations/query`.
| | |
|-----------------|------------------------------------------------------------------------------------------|
| **Sent by** | [=Verifier=] |
| **HTTP Method** | `POST` |
| **URL Path** | `/presentations/query` |
| **Request** | [`PresentationQueryMessage`](#presentation-query-message) |
| **Response** | [`PresentationResponseMessage`](#presentation-response-message) `HTTP 2xx` OR `HTTP 4xx` |

The POST body is a `PresentationQueryMessage` JSON object with the following properties:
### Presentation Query Message

- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1).
- `@type`: REQUIRED. A string specifying the `PresentationQueryMessage` type.
- `presentationDefinition`: OPTIONAL. A valid `Presentation Definition` according to
the [Presentation Exchange Specification](https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-definition).
- `scope`: OPTIONAL. An array of scopes corresponding to Section [[[#scopes]]].
| | |
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Schema** | [JSON Schema](./resources/v0.8/presentation/presentation-query-message-schema.json) |
| **Required** | </br>- `@context`: Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1).</br>- `@type`: A string specifying the `PresentationQueryMessage` type. |
| **Optional** | </br>- `presentationDefinition`: A valid `Presentation Definition` according to the [Presentation Exchange Specification](https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-definition).</br>- `scope`: An array of scopes corresponding to Section [[[#scopes]]]. |

A `PresentationQueryMessage` MUST contain either a `presentationDefinition` or a `scope` parameter. It is an error to
contain both.

The following are non-normative examples of the JSON body:

```json
{
"@context": [
"https://w3id.org/dspace-dcp/v0.8",
"https://identity.foundation/presentation-exchange/submission/v1"
],
"@type": "PresentationQueryMessage",
"scope": []
}
```
<aside class="example" title="PresentationQueryMessage with scope">
<pre class="json" data-include="./resources/v0.8/presentation/example/presentation-query-message.json">
</pre>
</aside>

```json
<aside class="example" title="PresentationQueryMessage with presentationDefinition">
<pre class="json">
{
"@context": [
"https://w3id.org/dspace-dcp/v0.8",
Expand All @@ -124,7 +123,8 @@ The following are non-normative examples of the JSON body:
"@type": "PresentationQueryMessage",
"presentationDefinition": "..."
}
```
</pre>
</aside>

#### Presentation Definitions

Expand Down Expand Up @@ -166,28 +166,19 @@ credential by id. For example:
denotes read-only access to the VC identified by `8247b87d-8d72-47e1-8128-9ce47e3d829d` and may be used to request a
Verifiable Credential.

#### Query For Presentations Response

The response type of a presentation query is a `PresentationResponseMessage` with the following parameters:
### Presentation Response Message

- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1).
- `@type`: REQUIRED. A string specifying the `PresentationResponseMessage` type.
- `presentation`: REQUIRED. An array of [=Verifiable Presentations=]. The [=Verifiable Presentations=] may be strings,
JSON objects, or a combination of both depending on the format.
| | |
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Schema** | [JSON Schema](./resources/v0.8/presentation/presentation-response-message-schema.json) |
| **Required** | - `@context`: Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1).</br>- `@type`: A string specifying the `PresentationResponseMessage` type.</br>- `presentation`: An array of [=Verifiable Presentations=]. The [=Verifiable Presentations=] may be strings, JSON objects, or a combination of both depending on the format.</br> |

The following are non-normative examples of the JSON response body:

```json
{
"@context": [
"https://w3id.org/dspace-dcp/v0.8"
],
"@type": "PresentationResponseMessage",
"presentation": [
"dsJdh...UMetV"
]
}
```
<aside class="example" title="Presentation Response Message">
<pre class="json" data-include="./resources/v0.8/presentation/example/presentation-response-message.json">
</pre>
</aside>

## Storage API

Expand All @@ -197,44 +188,35 @@ an [=Issuer Service=].
If a client is not authorized for an endpoint request, the [=Credential Service=] SHOULD return `4xx Client Error`. The
exact error code is implementation-specific.

### Write Credentials
| | |
|-----------------|-------------------------------------------|
| **Sent by** | [=Issuer Service=] |
| **HTTP Method** | `POST` |
| **URL Path** | `/credentials` |
| **Request** | [Credential Message](#credential-message) |
| **Response** | `HTTP 2xx` OR `HTTP 4xx Client Error` |

[=Verifiable Credentials=] can be written to the [=Credential Service=] by POSTing a `CredentialMessage` to the
`credentials` endpoint: `POST /credentials`.
### Credential Message

If the POST is successful, credentials will be created and an HTTP `2XX` is returned.
| | |
|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Schema** | [JSON Schema](./resources/v0.8/presentation/credential-message-schema.json) |
| **Required** | - `@context`: Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1).</br>- `@type`: A string specifying the `CredentialMessage` type.</br>- `requestId`: A string corresponding to the issuance request id.</br>- `credentials`: An array of `CredentialContainer` Json objects as defined in the following. |

The POST body is a `CredentialMessage` JSON object with the following properties:
The following is a non-normative example of the Credential Message JSON body:

- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1).
- `@type`: REQUIRED. A string specifying the `CredentialMessage` type.
- `requestId`: REQUIRED. A string corresponding to the issuance request id.
- `credentials`: REQUIRED. An array of `CredentialContainer` Json objects corresponding to the schema
specified in section [[[#the-credentialcontainer-object]]].

The following is a non-normative example of the JSON body:

```json
{
"@context": [
"https://w3id.org/dspace-dcp/v0.8"
],
"@type": "CredentialMessage",
"requestId": "...",
"credentials": [
{
"@type": "CredentialContainer",
"payload": ""
}
]
}
```
<aside class="example" title="Credential Message">
<pre class="json" data-include="./resources/v0.8/presentation/example/credential-message.json">
</pre>
</aside>

#### The `CredentialContainer` Object
### Credential Container

The `credentials` property contains an array of `CredentialContainer` objects. The `CredentialContainer` object contains
the following properties:
The [Credential Message](#credential-message)'s `credentials` property contains an array of `CredentialContainer`
objects.
The `CredentialContainer` object contains the following properties:

- `@type`: REQUIRED. A string specifying the `CredentialContainer` type.
- `payload`: REQUIRED. A [Json Literal]([[json-ld11]], sect. 4.2.2) containing a [=Verifiable Credential=] defined
by ([[vc-data-model]]).
| | |
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Schema** | [JSON Schema](./resources/v0.8/presentation/credential-message-schema.json) |
| **Required** | - `@type`: A string specifying the `CredentialContainer` type.</br>- `payload`: A Json Literal ([[json-ld11]], sect. 4.2.2) containing a [=Verifiable Credential=] defined by ([[vc-data-model]]). |

0 comments on commit 826f468

Please sign in to comment.