Converting payloads

The MATTR VII API has an endpoint to be able to convert linked-data between JSON-LD and a binary format, CBOR-LD, in a lossless manner.

The API is general purpose and can convert any data model however there are 2 types of model that we'll focus on:

  1. Verifiable Credentials

  2. Verifiable Presentations

This implementation of compressed credentials using CBOR-LD is currently in a Technical Preview. This means we may change how this feature is implemented resulting in breaking changes to the API as well as the feature set being limited in some capacity.

Create a JSON-LD Credential

Follow the tutorial on creating credentials, start with a basic credential as using ZKP-enabled or complex credentials will hit some limitations discussed later on in the guide.

Request

http
Copy to clipboard.
1POST 
2https://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        "familyName": "Shin",
18        "educationalCredentialAwarded": "Certificate Name"
19    },
20    "persist": false,
21    "revocable": false
22}
  • Use the Public DID (menu > Settings > Public DID) from your MATTR mobile wallet as the subjectId

Response

json
Copy to clipboard.
1{
2  "id": "c6667bb7-9442-49a5-bb0b-fce269e97fc6",
3  "credential": {
4    "@context": [
5      "https://www.w3.org/2018/credentials/v1",
6      {
7        "@vocab": "https://w3id.org/security/undefinedTerm#"
8      },
9      "https://schema.org"
10    ],
11    "type": [
12      "VerifiableCredential",
13      "CourseCredential"
14    ],
15    "issuer": {
16      "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
17      "name": "tenant"
18    },
19    "issuanceDate": "2021-07-26T01:05:05.152Z",
20    "credentialSubject": {
21      "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
22      "givenName": "Chris",
23      "familyName": "Shin",
24      "educationalCredentialAwarded": "Certificate Name"
25    },
26    "proof": {
27      "type": "Ed25519Signature2018",
28      "created": "2021-07-26T01:05:06Z",
29      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..o6hnrrWpArG8LQz2Ex_u66_BtuPdp3Hkz18nhNdNhJ7J1k_2lmCCwsNdmo-kNFirZdSIMzqO-V3wEjMDphVEAA",
30      "proofPurpose": "assertionMethod",
31      "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
32    }
33  },
34  "issuanceDate": "2021-07-26T01:05:05.152Z"
35}

Convert a credential to CBOR-LD

To convert this JSON-LD credential into a CBOR-LD representation use the Convert Linked Data endpoint.

http
Copy to clipboard.
1POST
2https://YOUR_TENANT_SUBDOMAIN.vii.mattr.glboal/core/v1/linkeddata/convert

Request

json
Copy to clipboard.
1{
2  "options": {
3    "inputFormat": "jsonld",
4    "outputFormat": "cborld"
5  },
6  "data": {
7    "@context": [
8      "https://www.w3.org/2018/credentials/v1",
9      {
10        "@vocab": "https://w3id.org/security/undefinedTerm#"
11      },
12      "https://schema.org"
13    ],
14    "type": [
15      "VerifiableCredential",
16      "CourseCredential"
17    ],
18    "issuer": {
19      "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
20      "name": "tenant"
21    },
22    "issuanceDate": "2021-07-26T01:05:05.152Z",
23    "credentialSubject": {
24      "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
25      "givenName": "Chris",
26      "familyName": "Shin",
27      "educationalCredentialAwarded": "Certificate Name"
28    },
29    "proof": {
30      "type": "Ed25519Signature2018",
31      "created": "2021-07-26T01:05:06Z",
32      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..o6hnrrWpArG8LQz2Ex_u66_BtuPdp3Hkz18nhNdNhJ7J1k_2lmCCwsNdmo-kNFirZdSIMzqO-V3wEjMDphVEAA",
33      "proofPurpose": "assertionMethod",
34      "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
35    }
36  }
37}
38
39
  • The options parameters are used to determine how the API will handle the data, in this example, we are converting from JSON-LD as the inputFormat to CBOR-LD as the outputFormat so these fields can be set this way.

  • Use the credential object from the Create Credential API response as the data payload body.

Response

json
Copy to clipboard.
1{
2  "metadata": {
3    "encoding": "base64",
4    "format": "cborld"
5  },
6  "data": "2QUBpgGDEaFmQHZvY2FieChodHRwczovL3czaWQub3JnL3NlY3VyaXR5L3VuZGVmaW5lZFRlcm0jcmh0dHBzOi8vc2NoZW1hLm9yZxhypRh0GGgZFmYaYP4KQhkWaniQZXlKaGJHY2lPaUpGWkVSVFFTSXNJbUkyTkNJNlptRnNjMlVzSW1OeWFYUWlPbHNpWWpZMElsMTkuLm82aG5ycldwQXJHOExRejJFeF91NjZfQnR1UGRwM0hrejE4bmhOZE5oSjdKMWtfMmxtQ0N3c05kbW8ta05GaXJaZFNJTXpxTy1WM3dFak1EcGhWRUFBGRZuGRZ0GRZygxkEAVgi7QF5Zstx+ThTpsnM6PT9HUGF+M9xvreJOA19iXiGHF+h1Fgi7QF5Zstx+ThTpsnM6PT9HUGF+M9xvreJOA19iXiGHF+h1Bh1ghhscENvdXJzZUNyZWRlbnRpYWwZFlCkGHCCGQQBWCLtARZTDdo2+1dGfSuuFZwIr5V7W0wCy12o/1rlCaugUC67GQ5EcENlcnRpZmljYXRlIE5hbWUZDtpkU2hpbhkPUmVDaHJpcxkWWIIaYP4KQRiYGRZcohhwghkEAVgi7QF5Zstx+ThTpsnM6PT9HUGF+M9xvreJOA19iXiGHF+h1BkRomZ0ZW5hbnQ="
7}
  • The metadata field provides information about the response, for CBOR-LD format the data is always Base64 encoded.

  • The data payload has gone from 1082 characters to 664, approximately a reduction of a third. This can vary depending on the content of the credential, in particular how the expanded Linked Data is represented, further information is available later on in this tutorial.

Convert a Verifiable Presentation to JSON-LD

Along with credentials, presentations can be converted using the API in the exact same way, in this example, we will convert a CBOR-LD encoded Verifiable Presentation into JSON-LD.

The MATTR Mobile Wallet is able to generate Verifiable Presentations in a CBOR-LD format and encode them into a QR code (note in the wallet, first the binary is Gzipped then Base32 encoded), once read it will need to be decoded to binary, inflated then converted to Base64.

The MATTR sample app, Verify CBOR-LD presentation, provides an example of how to achieve this.

This is an example of a Verifiable Presentation in a CBOR-LD format with Base64 encoding.

json
Copy to clipboard.
1"2QUBpgGBERhweCRiYTNlMDRiMS00MjcwLTRlNmItODE3Yi0wNjQ3Yjg4YWJlN2IYc4KnGHQYaBh+eCRlMWIzNWFlMC05ZTBlLTExZWEtOWJiZi1hMzg3YjI3YzllNjAYgBph3MNOGIJubXktY3VzdG9tLnBhZ2UYhniQZXlKaGJHY2lPaUpGWkVSVFFTSXNJbUkyTkNJNlptRnNjMlVzSW1OeWFYUWlPbHNpWWpZMElsMTkuLk5ybjJRMnkyX1lua3FuRmUxNjgzUjVyRUxKN1ctODVmSHlWcThMaWk2UnNYWkEyMVN1VV95QVltWkxMVHFuXzBrQ3hIR2pqUE1KUUhYdUJLSlpQckRnGIoYlBiOgxkEAVgi7QG+rqIxMBLR9pW6OdeZxPtu1aFLXwIhFXb5+05PkkH581gi7QG+rqIxMBLR9pW6OdeZxPtu1aFLXwIhFXb5+05PkkH586cYdBhoGH54JGUxYjM1YWUwLTllMGUtMTFlYS05YmJmLWEzODdiMjdjOWU2MBiAGmHcw04Ygm5teS1jdXN0b20ucGFnZRiGeJBleUpoYkdjaU9pSkZaRVJUUVNJc0ltSTJOQ0k2Wm1Gc2MyVXNJbU55YVhRaU9sc2lZalkwSWwxOS4uRG1YRFBCR004dS1BSGJqOFpEUE5tcVJmazB3OXYyclNackx1bzNiaURHcVhYTUJlWDhmXzJGUS13OTNEdk0zd2tEWFd5bFFZS3lhbFhZT3BCeDRoQ1EYihiUGI6DGQQBWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecGHWBGG4YeIIZBAFYIu0Bvq6iMTAS0faVujnXmcT7btWhS18CIRV2+ftOT5JB+fMYfYGmAYMRoWZAdm9jYWJ4KGh0dHBzOi8vdzNpZC5vcmcvc2VjdXJpdHkvdW5kZWZpbmVkVGVybSNyaHR0cHM6Ly9zY2hlbWEub3JnGHKlGHQYaBiAGmHcwpkYhniQZXlKaGJHY2lPaUpGWkVSVFFTSXNJbUkyTkNJNlptRnNjMlVzSW1OeWFYUWlPbHNpWWpZMElsMTkuLkxnV2trWEFzRWdOVGlTMzZpdHpXaTBrZFloWnFhV2ZVTlFtTlJpTnZ2NXpaVGJUV1V5VWI3RkZIQVY1MG5GMUl3cnE2UTN3MVJNVmxOellEaEkxTERnGIoYkhiOgxkEAVgi7QFXU+8b//tmdAPWiB2LYWsQAiLUy4+0uiwaXRpo4Is3nFgi7QFXU+8b//tmdAPWiB2LYWsQAiLUy4+0uiwaXRpo4Is3nBh1ghhscENvdXJzZUNyZWRlbnRpYWwZFmqkGHCCGQQBWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecGQ5kcENlcnRpZmljYXRlIE5hbWUZDvhkU2hpbhkPcGVDaHJpcxkWcIIaYdzCmBkC7BkWdKIYcIIZBAFYIu0BV1PvG//7ZnQD1ogdi2FrEAIi1MuPtLosGl0aaOCLN5wZEcBmdGVuYW50"

To validate if the presentation is valid, first, we need to convert it to JSON-LD, then it can be used with the Verify a Presentation endpoint.

http
Copy to clipboard.
1POST
2https://YOUR_TENANT_SUBDOMAIN.vii.mattr.glboal/core/v1/linkeddata/convert

Request

json
Copy to clipboard.
1{
2  "options": {
3    "inputFormat": "cborld",
4    "outputFormat": "jsonld",
5    "outputEncoding": "none"
6  },
7  "data": "2QUBpgGBERhweCRiYTNlMDRiMS00MjcwLTRlNmItODE3Yi0wNjQ3Yjg4YWJlN2IYc4KnGHQYaBh+eCRlMWIzNWFlMC05ZTBlLTExZWEtOWJiZi1hMzg3YjI3YzllNjAYgBph3MNOGIJubXktY3VzdG9tLnBhZ2UYhniQZXlKaGJHY2lPaUpGWkVSVFFTSXNJbUkyTkNJNlptRnNjMlVzSW1OeWFYUWlPbHNpWWpZMElsMTkuLk5ybjJRMnkyX1lua3FuRmUxNjgzUjVyRUxKN1ctODVmSHlWcThMaWk2UnNYWkEyMVN1VV95QVltWkxMVHFuXzBrQ3hIR2pqUE1KUUhYdUJLSlpQckRnGIoYlBiOgxkEAVgi7QG+rqIxMBLR9pW6OdeZxPtu1aFLXwIhFXb5+05PkkH581gi7QG+rqIxMBLR9pW6OdeZxPtu1aFLXwIhFXb5+05PkkH586cYdBhoGH54JGUxYjM1YWUwLTllMGUtMTFlYS05YmJmLWEzODdiMjdjOWU2MBiAGmHcw04Ygm5teS1jdXN0b20ucGFnZRiGeJBleUpoYkdjaU9pSkZaRVJUUVNJc0ltSTJOQ0k2Wm1Gc2MyVXNJbU55YVhRaU9sc2lZalkwSWwxOS4uRG1YRFBCR004dS1BSGJqOFpEUE5tcVJmazB3OXYyclNackx1bzNiaURHcVhYTUJlWDhmXzJGUS13OTNEdk0zd2tEWFd5bFFZS3lhbFhZT3BCeDRoQ1EYihiUGI6DGQQBWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecGHWBGG4YeIIZBAFYIu0Bvq6iMTAS0faVujnXmcT7btWhS18CIRV2+ftOT5JB+fMYfYGmAYMRoWZAdm9jYWJ4KGh0dHBzOi8vdzNpZC5vcmcvc2VjdXJpdHkvdW5kZWZpbmVkVGVybSNyaHR0cHM6Ly9zY2hlbWEub3JnGHKlGHQYaBiAGmHcwpkYhniQZXlKaGJHY2lPaUpGWkVSVFFTSXNJbUkyTkNJNlptRnNjMlVzSW1OeWFYUWlPbHNpWWpZMElsMTkuLkxnV2trWEFzRWdOVGlTMzZpdHpXaTBrZFloWnFhV2ZVTlFtTlJpTnZ2NXpaVGJUV1V5VWI3RkZIQVY1MG5GMUl3cnE2UTN3MVJNVmxOellEaEkxTERnGIoYkhiOgxkEAVgi7QFXU+8b//tmdAPWiB2LYWsQAiLUy4+0uiwaXRpo4Is3nFgi7QFXU+8b//tmdAPWiB2LYWsQAiLUy4+0uiwaXRpo4Is3nBh1ghhscENvdXJzZUNyZWRlbnRpYWwZFmqkGHCCGQQBWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecGQ5kcENlcnRpZmljYXRlIE5hbWUZDvhkU2hpbhkPcGVDaHJpcxkWcIIaYdzCmBkC7BkWdKIYcIIZBAFYIu0BV1PvG//7ZnQD1ogdi2FrEAIi1MuPtLosGl0aaOCLN5wZEcBmdGVuYW50"
8}
  • We want the output to be in plain JSON, so set the outputEncoding to none (the default value is base64).

Response

json
Copy to clipboard.
1{
2  "metadata": {
3    "encoding": "none",
4    "format": "jsonld"
5  },
6  "data": {
7    "@context": [
8      "https://www.w3.org/2018/credentials/v1"
9    ],
10    "type": [
11      "VerifiablePresentation"
12    ],
13    "holder": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx",
14    "id": "ba3e04b1-4270-4e6b-817b-0647b88abe7b",
15    "proof": [
16      {
17        "type": "Ed25519Signature2018",
18        "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60",
19        "created": "2022-01-10T23:37:50Z",
20        "domain": "my-custom.page",
21        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..Nrn2Q2y2_YnkqnFe1683R5rELJ7W-85fHyVq8Lii6RsXZA21SuU_yAYmZLLTqn_0kCxHGjjPMJQHXuBKJZPrDg",
22        "proofPurpose": "authentication",
23        "verificationMethod": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx#z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx"
24      },
25      {
26        "type": "Ed25519Signature2018",
27        "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60",
28        "created": "2022-01-10T23:37:50Z",
29        "domain": "my-custom.page",
30        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..DmXDPBGM8u-AHbj8ZDPNmqRfk0w9v2rSZrLuo3biDGqXXMBeX8f_2FQ-w93DvM3wkDXWylQYKyalXYOpBx4hCQ",
31        "proofPurpose": "authentication",
32        "verificationMethod": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j#z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
33      }
34    ],
35    "verifiableCredential": [
36      {
37        "@context": [
38          "https://www.w3.org/2018/credentials/v1",
39          {
40            "@vocab": "https://w3id.org/security/undefinedTerm#"
41          },
42          "https://schema.org"
43        ],
44        "type": [
45          "VerifiableCredential",
46          "CourseCredential"
47        ],
48        "credentialSubject": {
49          "educationalCredentialAwarded": "Certificate Name",
50          "familyName": "Shin",
51          "givenName": "Chris",
52          "id": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
53        },
54        "issuanceDate": "2022-01-10T23:34:48.748Z",
55        "issuer": {
56          "id": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j",
57          "name": "tenant"
58        },
59        "proof": {
60          "type": "Ed25519Signature2018",
61          "created": "2022-01-10T23:34:49Z",
62          "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..LgWkkXAsEgNTiS36itzWi0kdYhZqaWfUNQmNRiNvv5zZTbTWUyUb7FFHAV50nF1Iwrq6Q3w1RMVlNzYDhI1LDg",
63          "proofPurpose": "assertionMethod",
64          "verificationMethod": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j#z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
65        }
66      }
67    ]
68  }
69}

The value from the data object can now be sent to the Verify a Presentation endpoint to validate if the Presentation is valid.

http
Copy to clipboard.
1POST 
2https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/presentations/verify

Request

json
Copy to clipboard.
1{
2  "presentation": {
3    "@context": [
4      "https://www.w3.org/2018/credentials/v1"
5    ],
6    "type": [
7      "VerifiablePresentation"
8    ],
9    "holder": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx",
10    "id": "ba3e04b1-4270-4e6b-817b-0647b88abe7b",
11    "proof": [
12      {
13        "type": "Ed25519Signature2018",
14        "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60",
15        "created": "2022-01-10T23:37:50Z",
16        "domain": "my-custom.page",
17        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..Nrn2Q2y2_YnkqnFe1683R5rELJ7W-85fHyVq8Lii6RsXZA21SuU_yAYmZLLTqn_0kCxHGjjPMJQHXuBKJZPrDg",
18        "proofPurpose": "authentication",
19        "verificationMethod": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx#z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx"
20      },
21      {
22        "type": "Ed25519Signature2018",
23        "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60",
24        "created": "2022-01-10T23:37:50Z",
25        "domain": "my-custom.page",
26        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..DmXDPBGM8u-AHbj8ZDPNmqRfk0w9v2rSZrLuo3biDGqXXMBeX8f_2FQ-w93DvM3wkDXWylQYKyalXYOpBx4hCQ",
27        "proofPurpose": "authentication",
28        "verificationMethod": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j#z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
29      }
30    ],
31    "verifiableCredential": [
32      {
33        "@context": [
34          "https://www.w3.org/2018/credentials/v1",
35          {
36            "@vocab": "https://w3id.org/security/undefinedTerm#"
37          },
38          "https://schema.org"
39        ],
40        "type": [
41          "VerifiableCredential",
42          "CourseCredential"
43        ],
44        "credentialSubject": {
45          "educationalCredentialAwarded": "Certificate Name",
46          "familyName": "Shin",
47          "givenName": "Chris",
48          "id": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
49        },
50        "issuanceDate": "2022-01-10T23:34:48.748Z",
51        "issuer": {
52          "id": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j",
53          "name": "tenant"
54        },
55        "proof": {
56          "type": "Ed25519Signature2018",
57          "created": "2022-01-10T23:34:49Z",
58          "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..LgWkkXAsEgNTiS36itzWi0kdYhZqaWfUNQmNRiNvv5zZTbTWUyUb7FFHAV50nF1Iwrq6Q3w1RMVlNzYDhI1LDg",
59          "proofPurpose": "assertionMethod",
60          "verificationMethod": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j#z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
61        }
62      }
63    ]
64  }
65}

Response

json
Copy to clipboard.
1{
2  "verified": true
3}