Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add diagrams for the import and scanning component #154

Open
wants to merge 3 commits into
base: next
Choose a base branch
from
Open

docs: add diagrams for the import and scanning component #154

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0c32c9b
docs: add diagrams for the import and scanning component
namhoang1604 Nov 5, 2024
1fc228a
docs: format the table of render check list component docs
namhoang1604 Nov 7, 2024
e10d9b6
docs: add docs for headers, vc configs and examples
namhoang1604 Nov 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions documentation/docs/mock-apps/common/http-headers.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@namhoang1604, what are the permitted data structures of the file being imported? What are the allowed file extensions? What are the permitted credential types?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @ashleythedeveloper, the data structure is defined here, they can be VC or JSON. There is a component render-check-list added examples for cases can happen.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ashleythedeveloper, I updated it for more details.

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
Loading