Skip to content

Commit

Permalink
docs: add diagrams for the import and scanning component (#154)
Browse files Browse the repository at this point in the history 
* docs: add diagrams for the import and scanning component

Signed-off-by: Nam Hoang <[email protected]>

* docs: format the table of render check list component docs

Signed-off-by: Nam Hoang <[email protected]>

* docs: add docs for headers, vc configs and examples

---------

Signed-off-by: Nam Hoang <[email protected]>
  • Loading branch information
@namhoang1604
namhoang1604 authored Nov 26, 2024
1 parent 6be27a2 commit f76c8cf
Show file tree
Hide file tree
Showing 6 changed files with 425 additions and 30 deletions.
21 changes: 21 additions & 0 deletions documentation/docs/mock-apps/common/http-headers.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
sidebar_position: 57
title: HTTP Headers
---

import Disclaimer from '../.././\_disclaimer.mdx';

<Disclaimer />

## Description

The `Http Headers` object contains configuration details for the HTTP headers that is used to make requests. The headers content follow the [HTTP headers specification](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).

## Example

```json
{
"Authorization": "Bearer test",
"Content-Type": "application/json"
}
```
56 changes: 56 additions & 0 deletions documentation/docs/mock-apps/common/payload-type.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
sidebar_position: 58
title: Payload Type
---

import Disclaimer from '../../\_disclaimer.mdx';

<Disclaimer />

## Description

The `type` property of the `props` object in a [component](/docs/mock-apps/configuration/component-config) configuration defines the kind of data that component is responsible for handling.

## Usage

The `type` property of the `props` object is required for component receiving data such as [import-button](/docs/mock-apps/components/import-button), [qr-code-scanner-dialog-button](/docs/mock-apps/components/qr-code-scanner-dialog-button), etc. The component will use the `type` to determine how to handle the data it receives.

## Types

### JSON

When a component has the `JSON` type, it will suppose receive any JSON object as its payload and will not transform it in any way.

### VerifiableCredential

When a component has the `VerifiableCredential` type, it will suppose receive a [Verifiable Credential](/docs/mock-apps/common/verifiable-credentials) as its payload and will verify the credential before using it.

## Examples

```json
{
"name": "ImportButton",
"type": "EntryData",
"props": {
"label": "Import JSON",
"type": "JSON",
"style": {}
}
}
```

In this example, the `ImportButton` component is of type `EntryData` and expects any JSON object as its payload.

```json
{
"name": "ImportButton",
"type": "EntryData",
"props": {
"label": "Import JSON",
"type": "VerifiableCredential",
"style": {}
}
}
```

In this example, the `ImportButton` component is of type `EntryData` and expects a Verifiable Credential as its payload.
164 changes: 151 additions & 13 deletions documentation/docs/mock-apps/components/import-button.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,12 @@ title: Import Button
import Disclaimer from '../../\_disclaimer.mdx';

<Disclaimer />

## Description

The ImportButton component is responsible for rendering a button that allows the user to import data. The component will return the data that is imported by the user.

## Example
## Example app-config

```json
{
Expand All @@ -23,6 +24,30 @@ The ImportButton component is responsible for rendering a button that allows the
}
```

## Diagram

```mermaid
sequenceDiagram
participant U as User
participant MA as Mock App
participant V as VCKit
U->>MA: Import file
alt is verifiable credential
MA->>V: Verify VC
V-->>MA: Return verified result
alt is verified
alt is enveloped verifiable credential
MA->>MA: Decode enveloped VC
else is embedded verifiable credential
MA->>U: Return data
end
end
else is JSON
MA->>U: Return data
end
```

## Definitions

| Property | Required | Description | Type |
Expand All @@ -33,17 +58,130 @@ The ImportButton component is responsible for rendering a button that allows the

### Props

| Property | Required | Description | Type |
| --------- | -------- | ----------------------------------------------------------------------------------------------------- | ------ |
| label | Yes | The label for the import button | String |
| style | No | The style for the component | Object |
| type | No | The type of data (should be 'VerifiableCredential' and 'JSON'), the default is 'VerifiableCredential' | String |
| vcOptions | No | The options for the VC data processing | Object |
| Property | Required | Description | Type |
| --------- | -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| label | Yes | The label for the import button | String |
| style | No | The style for the component | [Style](/docs/mock-apps/common/style) |
| type | No | The type of data (should be 'VerifiableCredential' and 'JSON'), the default is 'VerifiableCredential' | [PayloadType](/docs/mock-apps/common/payload-type) |
| vcOptions | No | The options for the VC data processing | [VC component configuration](/docs/mock-apps/configuration/vc-component-config) |

## Data structure

The file extension should be JSON and the data structure can be any JSON object. The component will return data that will be an array of objects, each object has key as the file name and value as the data that is imported.
In case the data is a verifiable credential (VC) or contains a VC, the component will use the vcOptions to verify and decode the VC. The decoded enveloped VC will be set as the same level as the original VC.

### Example data structure

- When import a file that contains a JSON object:

```json
// imported JSON file
{
"name": "Alice",
"age": 25
}
```

The return data will be:

```json
// return data
[
{
"data.json": {
"name": "Alice",
"age": 25
}
}
]
```

- When import a file that contains a VC and the vcOptions is set as below:

```json
// vcOptions
{
"credentialPath": "/",
"vckitAPIUrl": "https://vckit-api.com",
"headers": { "Authorization": "Bearer test" }
}
```

```json
// imported VC file
{
"@context": ["https://www.w3.org/ns/credentials/v2"],
"type": ["VerifiableCredential"],
"credentialSubject": {
"id": "did:example:123",
"name": "Alice"
}
}
```

The return data will be:

```json
// return data
[
{
"VC1.json": {
"@context": ["https://www.w3.org/ns/credentials/v2"],
"type": ["VerifiableCredential"],
"credentialSubject": {
"id": "did:example:123",
"name": "Alice"
}
}
}
]
```

The imported data will be verified and return the original VC.

- When import a file that contains a enveloped VC and the vcOptions is set as below:

```json
// vcOptions
{
"credentialPath": "/",
"vckitAPIUrl": "https://vckit-api.com",
"headers": { "Authorization": "Bearer test123" }
}
```

```json
// imported VC file
{
"@context": ["https://www.w3.org/ns/credentials/v2"],
"id": "data:application/vc-ld+jwt,jwt",
"type": "EnvelopedVerifiableCredential"
}
```

The return data will be:

#### vcOptions
```json
// return data
[
{
"VC1.json": {
"vc": {
"@context": ["https://www.w3.org/ns/credentials/v2"],
"id": "data:application/vc-ld+jwt,jwt",
"type": "EnvelopedVerifiableCredential"
},
"decodedEnvelopedVC": {
"@context": ["https://www.w3.org/ns/credentials/v2"],
"type": ["VerifiableCredential"],
"credentialSubject": {
"id": "did:example:123",
"name": "Alice"
}
}
}
}
]
```

| Property | Required | Description | Type |
| -------------- | -------- | ---------------------------------------------------------------------------- | ------ |
| credentialPath | Yes | The path for the credential data | String |
| vckitAPIUrl | No | The URL for the vckit API | String |
| headers | No | The headers for the vckit API, example: \{ Authorization: "Bearer test123"\} | Object |
Based on the above example, the imported data will be verified and transformed to an object that contains the original VC and the decoded VC.
Loading

0 comments on commit f76c8cf

Please sign in to comment.