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:

Verifiable Credentials
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

httpCopy to clipboard. 
POST 
https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/credentials

jsonCopy to clipboard. 
{
    "issuer": {
        "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
        "name": "tenant"
    },
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://schema.org"
    ],
    "subjectId": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
    "type": [
        "VerifiableCredential",
        "CourseCredential"
    ],
    "claims": {
        "givenName": "Chris",
        "familyName": "Shin",
        "educationalCredentialAwarded": "Certificate Name"
    },
    "persist": false,
    "revocable": false
}

Use the Public DID (menu > Settings > Public DID) from your MATTR mobile wallet as the subjectId

Response

jsonCopy to clipboard. 
{
  "id": "c6667bb7-9442-49a5-bb0b-fce269e97fc6",
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      {
        "@vocab": "https://w3id.org/security/undefinedTerm#"
      },
      "https://schema.org"
    ],
    "type": [
      "VerifiableCredential",
      "CourseCredential"
    ],
    "issuer": {
      "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
      "name": "tenant"
    },
    "issuanceDate": "2021-07-26T01:05:05.152Z",
    "credentialSubject": {
      "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
      "givenName": "Chris",
      "familyName": "Shin",
      "educationalCredentialAwarded": "Certificate Name"
    },
    "proof": {
      "type": "Ed25519Signature2018",
      "created": "2021-07-26T01:05:06Z",
      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..o6hnrrWpArG8LQz2Ex_u66_BtuPdp3Hkz18nhNdNhJ7J1k_2lmCCwsNdmo-kNFirZdSIMzqO-V3wEjMDphVEAA",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
    }
  },
  "issuanceDate": "2021-07-26T01:05:05.152Z"
}

Convert a credential to CBOR-LD

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

httpCopy to clipboard. 
POST
https://YOUR_TENANT_SUBDOMAIN.vii.mattr.glboal/core/v1/linkeddata/convert

Request

jsonCopy to clipboard. 
{
  "options": {
    "inputFormat": "jsonld",
    "outputFormat": "cborld"
  },
  "data": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      {
        "@vocab": "https://w3id.org/security/undefinedTerm#"
      },
      "https://schema.org"
    ],
    "type": [
      "VerifiableCredential",
      "CourseCredential"
    ],
    "issuer": {
      "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
      "name": "tenant"
    },
    "issuanceDate": "2021-07-26T01:05:05.152Z",
    "credentialSubject": {
      "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
      "givenName": "Chris",
      "familyName": "Shin",
      "educationalCredentialAwarded": "Certificate Name"
    },
    "proof": {
      "type": "Ed25519Signature2018",
      "created": "2021-07-26T01:05:06Z",
      "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..o6hnrrWpArG8LQz2Ex_u66_BtuPdp3Hkz18nhNdNhJ7J1k_2lmCCwsNdmo-kNFirZdSIMzqO-V3wEjMDphVEAA",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
    }
  }
}

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

jsonCopy to clipboard. 
{
  "metadata": {
    "encoding": "base64",
    "format": "cborld"
  },
  "data": "2QUBpgGDEaFmQHZvY2FieChodHRwczovL3czaWQub3JnL3NlY3VyaXR5L3VuZGVmaW5lZFRlcm0jcmh0dHBzOi8vc2NoZW1hLm9yZxhypRh0GGgZFmYaYP4KQhkWaniQZXlKaGJHY2lPaUpGWkVSVFFTSXNJbUkyTkNJNlptRnNjMlVzSW1OeWFYUWlPbHNpWWpZMElsMTkuLm82aG5ycldwQXJHOExRejJFeF91NjZfQnR1UGRwM0hrejE4bmhOZE5oSjdKMWtfMmxtQ0N3c05kbW8ta05GaXJaZFNJTXpxTy1WM3dFak1EcGhWRUFBGRZuGRZ0GRZygxkEAVgi7QF5Zstx+ThTpsnM6PT9HUGF+M9xvreJOA19iXiGHF+h1Fgi7QF5Zstx+ThTpsnM6PT9HUGF+M9xvreJOA19iXiGHF+h1Bh1ghhscENvdXJzZUNyZWRlbnRpYWwZFlCkGHCCGQQBWCLtARZTDdo2+1dGfSuuFZwIr5V7W0wCy12o/1rlCaugUC67GQ5EcENlcnRpZmljYXRlIE5hbWUZDtpkU2hpbhkPUmVDaHJpcxkWWIIaYP4KQRiYGRZcohhwghkEAVgi7QF5Zstx+ThTpsnM6PT9HUGF+M9xvreJOA19iXiGHF+h1BkRomZ0ZW5hbnQ="
}

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.

jsonCopy to clipboard. 
"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.

httpCopy to clipboard. 
POST
﻿https:﻿//YOUR_TENANT_SUBDOMAIN.vii.mattr.glboal/core/v1/linkeddata/convert

Request

jsonCopy to clipboard. 
{
  "options": {
    "inputFormat": "cborld",
    "outputFormat": "jsonld",
    "outputEncoding": "none"
  },
  "data": "2QUBpgGBERhweCRiYTNlMDRiMS00MjcwLTRlNmItODE3Yi0wNjQ3Yjg4YWJlN2IYc4KnGHQYaBh+eCRlMWIzNWFlMC05ZTBlLTExZWEtOWJiZi1hMzg3YjI3YzllNjAYgBph3MNOGIJubXktY3VzdG9tLnBhZ2UYhniQZXlKaGJHY2lPaUpGWkVSVFFTSXNJbUkyTkNJNlptRnNjMlVzSW1OeWFYUWlPbHNpWWpZMElsMTkuLk5ybjJRMnkyX1lua3FuRmUxNjgzUjVyRUxKN1ctODVmSHlWcThMaWk2UnNYWkEyMVN1VV95QVltWkxMVHFuXzBrQ3hIR2pqUE1KUUhYdUJLSlpQckRnGIoYlBiOgxkEAVgi7QG+rqIxMBLR9pW6OdeZxPtu1aFLXwIhFXb5+05PkkH581gi7QG+rqIxMBLR9pW6OdeZxPtu1aFLXwIhFXb5+05PkkH586cYdBhoGH54JGUxYjM1YWUwLTllMGUtMTFlYS05YmJmLWEzODdiMjdjOWU2MBiAGmHcw04Ygm5teS1jdXN0b20ucGFnZRiGeJBleUpoYkdjaU9pSkZaRVJUUVNJc0ltSTJOQ0k2Wm1Gc2MyVXNJbU55YVhRaU9sc2lZalkwSWwxOS4uRG1YRFBCR004dS1BSGJqOFpEUE5tcVJmazB3OXYyclNackx1bzNiaURHcVhYTUJlWDhmXzJGUS13OTNEdk0zd2tEWFd5bFFZS3lhbFhZT3BCeDRoQ1EYihiUGI6DGQQBWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecGHWBGG4YeIIZBAFYIu0Bvq6iMTAS0faVujnXmcT7btWhS18CIRV2+ftOT5JB+fMYfYGmAYMRoWZAdm9jYWJ4KGh0dHBzOi8vdzNpZC5vcmcvc2VjdXJpdHkvdW5kZWZpbmVkVGVybSNyaHR0cHM6Ly9zY2hlbWEub3JnGHKlGHQYaBiAGmHcwpkYhniQZXlKaGJHY2lPaUpGWkVSVFFTSXNJbUkyTkNJNlptRnNjMlVzSW1OeWFYUWlPbHNpWWpZMElsMTkuLkxnV2trWEFzRWdOVGlTMzZpdHpXaTBrZFloWnFhV2ZVTlFtTlJpTnZ2NXpaVGJUV1V5VWI3RkZIQVY1MG5GMUl3cnE2UTN3MVJNVmxOellEaEkxTERnGIoYkhiOgxkEAVgi7QFXU+8b//tmdAPWiB2LYWsQAiLUy4+0uiwaXRpo4Is3nFgi7QFXU+8b//tmdAPWiB2LYWsQAiLUy4+0uiwaXRpo4Is3nBh1ghhscENvdXJzZUNyZWRlbnRpYWwZFmqkGHCCGQQBWCLtAVdT7xv/+2Z0A9aIHYthaxACItTLj7S6LBpdGmjgizecGQ5kcENlcnRpZmljYXRlIE5hbWUZDvhkU2hpbhkPcGVDaHJpcxkWcIIaYdzCmBkC7BkWdKIYcIIZBAFYIu0BV1PvG//7ZnQD1ogdi2FrEAIi1MuPtLosGl0aaOCLN5wZEcBmdGVuYW50"
}

We want the output to be in plain JSON, so set the outputEncoding to none (the default value is base64).

Response

jsonCopy to clipboard. 
{
  "metadata": {
    "encoding": "none",
    "format": "jsonld"
  },
  "data": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1"
    ],
    "type": [
      "VerifiablePresentation"
    ],
    "holder": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx",
    "id": "ba3e04b1-4270-4e6b-817b-0647b88abe7b",
    "proof": [
      {
        "type": "Ed25519Signature2018",
        "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60",
        "created": "2022-01-10T23:37:50Z",
        "domain": "my-custom.page",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..Nrn2Q2y2_YnkqnFe1683R5rELJ7W-85fHyVq8Lii6RsXZA21SuU_yAYmZLLTqn_0kCxHGjjPMJQHXuBKJZPrDg",
        "proofPurpose": "authentication",
        "verificationMethod": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx#z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx"
      },
      {
        "type": "Ed25519Signature2018",
        "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60",
        "created": "2022-01-10T23:37:50Z",
        "domain": "my-custom.page",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..DmXDPBGM8u-AHbj8ZDPNmqRfk0w9v2rSZrLuo3biDGqXXMBeX8f_2FQ-w93DvM3wkDXWylQYKyalXYOpBx4hCQ",
        "proofPurpose": "authentication",
        "verificationMethod": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j#z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
      }
    ],
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          {
            "@vocab": "https://w3id.org/security/undefinedTerm#"
          },
          "https://schema.org"
        ],
        "type": [
          "VerifiableCredential",
          "CourseCredential"
        ],
        "credentialSubject": {
          "educationalCredentialAwarded": "Certificate Name",
          "familyName": "Shin",
          "givenName": "Chris",
          "id": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
        },
        "issuanceDate": "2022-01-10T23:34:48.748Z",
        "issuer": {
          "id": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j",
          "name": "tenant"
        },
        "proof": {
          "type": "Ed25519Signature2018",
          "created": "2022-01-10T23:34:49Z",
          "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..LgWkkXAsEgNTiS36itzWi0kdYhZqaWfUNQmNRiNvv5zZTbTWUyUb7FFHAV50nF1Iwrq6Q3w1RMVlNzYDhI1LDg",
          "proofPurpose": "assertionMethod",
          "verificationMethod": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j#z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
        }
      }
    ]
  }
}

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

httpCopy to clipboard. 
POST 
﻿https:﻿//YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/presentations/verify

Request

jsonCopy to clipboard. 
{
  "presentation": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1"
    ],
    "type": [
      "VerifiablePresentation"
    ],
    "holder": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx",
    "id": "ba3e04b1-4270-4e6b-817b-0647b88abe7b",
    "proof": [
      {
        "type": "Ed25519Signature2018",
        "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60",
        "created": "2022-01-10T23:37:50Z",
        "domain": "my-custom.page",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..Nrn2Q2y2_YnkqnFe1683R5rELJ7W-85fHyVq8Lii6RsXZA21SuU_yAYmZLLTqn_0kCxHGjjPMJQHXuBKJZPrDg",
        "proofPurpose": "authentication",
        "verificationMethod": "did:key:z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx#z6MksHbxLQoQvsPRezXsJJiKXuaV9frAiuwKfbuHHTRn53jx"
      },
      {
        "type": "Ed25519Signature2018",
        "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60",
        "created": "2022-01-10T23:37:50Z",
        "domain": "my-custom.page",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..DmXDPBGM8u-AHbj8ZDPNmqRfk0w9v2rSZrLuo3biDGqXXMBeX8f_2FQ-w93DvM3wkDXWylQYKyalXYOpBx4hCQ",
        "proofPurpose": "authentication",
        "verificationMethod": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j#z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
      }
    ],
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          {
            "@vocab": "https://w3id.org/security/undefinedTerm#"
          },
          "https://schema.org"
        ],
        "type": [
          "VerifiableCredential",
          "CourseCredential"
        ],
        "credentialSubject": {
          "educationalCredentialAwarded": "Certificate Name",
          "familyName": "Shin",
          "givenName": "Chris",
          "id": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
        },
        "issuanceDate": "2022-01-10T23:34:48.748Z",
        "issuer": {
          "id": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j",
          "name": "tenant"
        },
        "proof": {
          "type": "Ed25519Signature2018",
          "created": "2022-01-10T23:34:49Z",
          "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..LgWkkXAsEgNTiS36itzWi0kdYhZqaWfUNQmNRiNvv5zZTbTWUyUb7FFHAV50nF1Iwrq6Q3w1RMVlNzYDhI1LDg",
          "proofPurpose": "assertionMethod",
          "verificationMethod": "did:key:z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j#z6MkkL9kGggqk12KZV7XE9uBoDhGGEwHYqe7CB7Qanq2vX6j"
        }
      }
    ]
  }
}

Response

jsonCopy to clipboard. 
{
  "verified": true
}