Issue a complex JSON-LD Credential

Introduction

This guide will demonstrate how to create a verifiable credential using VII Core that is more complex in its data structures. This includes adding images and nested data, that can be displayed in the MATTR mobile app in a more human-friendly way.

Prerequisites

You will need access to the MATTR VII APIs. If you’re experiencing any difficulties, contact us.

In order to create a credential, you will need the following information:

  • Issuer DID

  • Subject DID

  • Credential type

  • JSON-LD claim names as defined by schema.org or hosted on allowed domain w3.org or w3id.org

  • Claim values

If you want to use our experimental ZKP feature alongside complex credential, see the tutorial on issuing a ZKP-enabled credential.

Create a Credential

Create a credential by making an API request.

To construct the claims body appropriately, you will need to understand the varying data types.

Common data types are listed below:

  • Images can be embedded into a credential but need to be Base64 encoded and referenced with data:image/png; these will then be displayed as part of the credential. There is a size limitation of 2MB per total request on the MATTR VII platform, images should be reduced in size to accommodate.

External references to images are not supported in the MATTR mobile wallet due to risk of external tracking and privacy concerns.

  • Dates can be used following the recognised ISO 8601 format.

  • Telephone and Email addresses are added as strings, on the MATTR mobile app, These will be rendered in a way that they can be tapped to open the default handlers.

  • Locations can be physical places used with the address fields defined in https://schema.org/address. These will be displayed on the MATTR mobile app as a location item and can be opened in the device's default maps app.

  • Alternatively, a location may be virtual, and a URL used to open other apps on the device.

Any time an external link is accessed on the MATTR mobile app, a privacy warning is displayed to the user.

Request

http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/credentials
json
Copy to clipboard.
1{
2    "issuer": {
3        "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
4        "name": "tenant"
5    },
6    "@context": [
7        "https://www.w3.org/2018/credentials/v1",
8        "https://schema.org"
9    ],
10    "subjectId": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
11    "type": [
12        "VerifiableCredential",
13        "CourseCredential"
14    ],
15    "claims": {
16        "givenName": "Chris",
17        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOYAAADmCAMAAAD2tAmJAAAACXBIWXMAAAsSAAALEgHS3X78AAADAF..."
18        "birthDate": "1975-03-05T06:30:00-05:00"
19        "telephone" : "077 0123728",
20        "email": "me@mail.com",
21        "location": {
22          "@type": "Place",
23          "address": {
24            "@type": "PostalAddress",
25            "addressLocality": "Denver",
26            "addressRegion": "CO",
27            "postalCode": "80209",
28            "streetAddress": "7 S. Broadway"
29              },
30          "name": "The Place"
31          },
32        "location": {
33          "@type": "VirtualLocation",
34          "url": "https://zoom.us/j/12737465"
35          }
36    },
37    "persist": false,
38    "revocable": false
39}

Response

json
Copy to clipboard.
1{
2  "id": "03bb9930-eb18-11ea-a057-530317397ea3",
3  "credential": {
4    "@context": [
5      "https://www.w3.org/2018/credentials/v1",
6      "https://schema.org"
7    ],
8    "type": [
9      "VerifiableCredential",
10      "CourseCredential"
11    ],
12    "issuer": {
13      "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
14      "name": "tenant"
15    },
16    "issuanceDate": "2020-08-30T23:24:54.876Z",
17    "credentialSubject": {
18        "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
19        "givenName": "Chris",
20        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOYAAADmCAMAAAD2tAmJAAAACXBIWXMAAAsSAAALEgHS3X78AAADAF..."
21        "birthDate": "1975-03-05T06:30:00-05:00"
22        "telephone" : "077 0123728",
23        "email": "me@mail.com",
24        "location": {
25          "@type": "Place",
26          "address": {
27            "@type": "PostalAddress",
28            "addressLocality": "Denver",
29            "addressRegion": "CO",
30            "postalCode": "80209",
31            "streetAddress": "7 S. Broadway"
32              },
33          "name": "The Place"
34          },
35        "location": {
36          "@type": "VirtualLocation",
37          "url": "https://zoom.us/j/12737465"
38          }
39    },
40    "proof": {
41      "type": "Ed25519Signature2018",
42      "created": "2020-08-30T23:24:55Z",
43      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..BSHdalZrYml0slwgAXFVF5uAcg2DbPMfwatturKs8TnuxBxylQDnS3JkORORVmO73Ruh7h8KJvVvHO4pE5NsCQ",
44      "proofPurpose": "assertionMethod",
45      "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
46    }
47  },
48  "issuanceDate": "2020-08-30T23:24:54.876Z"
49}

The returned credential attribute contains a VerifiableCredential object.

View in the MATTR mobile app

Currently, in order to view a complex credential in the MATTR mobile app, you will need to replicate this configuration on the OIDC Bridge Credential Issuer and associated OpenID Provider to set the claim values in the ID Token.

This is possible by mapping nested data in the JWT format ID token and configure the claim mappings.

e.g.

An ID Token may be created using a mixture of default OIDC claims (e.g. given_name, picture, birthdate) and custom claims (e.g. location)

json
Copy to clipboard.
1"sub": "00u9vme99nxudvxZA0h7",
2"updated_at": 1490198843,
3"given_name": "Chris",
4"picture": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOYAAADmCAMAAAD2tAmJAAAACXBIWXMAAAsSAAALEgHS3X78AAADAF..."
5"birthdate": "1975-03-05T06:30:00-05:00"
6"telephone" : "077 0123728",
7"email": "me@mail.com",
8"https://tenant.vii.mattr.global/location": {
9  "@type": "Place",
10  "address": {
11    "@type": "PostalAddress",
12    "addressLocality": "Denver",
13    "addressRegion": "CO",
14    "postalCode": "80209",
15    "streetAddress": "7 S. Broadway"
16      },
17  "name": "The Place"
18  },

As part of the claimMappings in the OIDC bridge Credential Issuer, you would need

json
Copy to clipboard.
1"claimMappings": [
2     {
3         "oidcClaim": "given_name",
4         "jsonLdTerm": "givenName"
5     },
6     {
7        "oidcClaim": "picture",
8        "jsonLdTerm": "image"
9    },
10    {
11        "oidcClaim": "birthdate",
12        "jsonLdTerm": "birthDate"
13    
14    },
15     {
16         "oidcClaim": "https://tenant.vii.mattr.global/location",
17         "jsonLdTerm": "location"
18     }
19 ]

Credential type & UI Overlays

In the MATTR mobile wallet app the use of certain credential Types will trigger a user-interface overlay to display the credential data in an easy to read format.

Example overlays coming to the mobile wallet, please get in touch if you would like to learn more about our future plans.

https://www.datocms-assets.com/38428/1625181071-human-friendly-credentials.png?auto=format