Learn

Data structure

Introduction

Compact Credentials are represented as QR codes, and as a result their payload size and complexity are limited by the size of the generated QR code. To maximise content, Compact Credentials are signed using a Concise Binary Object Representation (CBOR) data format called CBOR Web Token (CWT). This data format is used to represent credentials that become cryptographically verifiable when signed by an issuer.

CBOR is a binary data format derived from JSON and allows utilising data types like numbers, strings & arrays. Being binary, it offers a much more compact message size. Often when CBOR is being discussed or documented, we can represent the same data using JSON to simplify data viewing and modelling. 

JSON Object Signing & Encryption (JOSE) is used to create ubiquitous JSON Web Tokens (JWT) in the signed (JWS) and encrypted (JWE) flavours. Similarly, CBOR Object Signing & Encryption (COSE) is a general-purpose digital signature encoding format that supports several different cryptographic algorithms. It can be used to create CBOR Web Tokens (CWT) in corresponding CWS (signed) and CWE (encrypted) formats.

Compact credentials issued by the MATTR platform are CWTs that have been cryptographically signed using an issuer DID controlled by the tenant. This DID must be a did:web using a P-256 key type. Our experience shows that DIDs of this type make offline verification easier by using standard caching mechanisms and better support for the cryptographic primitives. 

Claims

Information included in the credential is referred to as claims. Compact and Compact Semantic Credentials can include two types of claims:

  • Standard claims: These claims reference specific types of information such as the issuer of the credential and its validity period.

  • Custom claims: These can be any type of claims you wish to include in the credential. The value of any custom claim must be either a boolean, a string or a number.

The following example is a signed Compact Credential returned by the MATTR VII sign endpoint:

json
Copy to clipboard.
1{
2    "id": "bKcrxojFSuSZvI5qhKInxA",
3    "decoded": {
4        "iss": "did:web:learn.vii.au01.mattr.global",
5        "nbf": 1704099600,
6        "type": "Course Credential",
7        "exp": 1767258000,
8        "name": "Emma Jane Tasma",
9        "code": "HS.278",
10        "certificationName": "Working at Heights",
11        "certificationLevel": "Level 4",
12        "issuerName": "Advanced Safety Training",
13        "status": {
14            "index": 3,
15            "url": "https://learn.vii.au01.mattr.global/core/v2/credentials/compact/revocation-lists/887cd140-e4d7-4518-b70f-305b23778848"
16        },
17        "jti": "bKcrxojFSuSZvI5qhKInxA"
18    },
19    "encoded": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU"
20}

  • id: Unique identifier of this Compact Credential.

  • decoded: Includes both standard and custom claims. In the above example iss, nbf, type, exp, status and jti are standard claims, while all other properties are custom claims (name, code, certificationName, certificationLevel and issuerName).

  • encoded: This is a CBOR Web Token (CWT), which is the decoded object represented as an encoded string. The CSC:/1 prefix indicates the CWT scheme (COSE Sign Compact profile, CSC) and the version (1).

The following standard claims can be included in a Compact or Compact Semantic Credential (note that you cannot use these as custom claims names):

  • iss (Issuer): Represents the party who issued the credential. This a required field for both Compact and Compact Semantic Credentials. Its decoded value must be a did:web using a P-256 key type that must be publicly available on the tenant.

  • sub: (Subject): Represents the subject of the credential. When present, must be a text string.

  • kid (Key Identifier): References the signing key material. It must be present in the protected header section. Its value is used with the iss value internally by MATTR VII to resolve the referenced public key (<iss>#<kid>) and verify the signature of the COSE payload.

  • alg (Signature Algorithm): Represents what algorithm is used for creating the signature. It must be present in the protected header section and must be ES256. Its value is used internally by MATTR VII to verify the signature of the COSE payload.

  • exp (Expiration time): Represents the date and time after which the credential is considered expired by the issuer. When present, must be a timestamp encoded as an integer in the NumericDate format as specified in RFC8392 section 2.

  • nbf (Not Before): Represents the earliest date and time at which the credential is considered valid by the issuer. When present, must be a timestamp encoded as an integer in the NumericDate format as specified in RFC8392 section 2.

  • iat (Issued At): Represents the credential issuance time and date. When present, must be a timestamp encoded as an integer in the NumericDate format as specified in RFC8392 section 2.

  • cti (CWT ID): Represents a unique credential identifier as a byte string. Since the decoded object is represented as a JWT, the cti claim is mapped to the equivalent JWT jti claim, presented as a string. The decoded jti value is encoded with base64URL without padding.

  • status (Status): Provides information required to discover the current revocation status of the credential.

  • type (Type): Represents the unique type of this credential. When present, its value must be a text string. MATTR highly encourages including a type claim for issued credentials to enable various capabilities in consuming workflows, such as creating and validating Ecosystem policies.

Compact Semantic Credentials Claims

Custom claims are embedded in Compact Semantic Credentials into a standard vc property. This provides semantic context to the claims and is also compliant with the W3C Verifiable Credentials Data Model 1.0.

The following is an example of a signed Compact Semantic Credential with custom claims inside a vc object.:

json
Copy to clipboard.
1{
2    "id": "bKcrxojFSuSZvI5qhKInxA",
3    "decoded": {
4        "iss": "did:web:learn.vii.au01.mattr.global",
5        "nbf": 1516239022,
6        "type": "Course Credential",
7        "exp": 1516239922,
8        "jti": "urn:uuid:cc599d04-0d51-4f7e-8ef5-d7b5f8461c5f",
9        "vc": {
10          "@context": ["https://www.w3.org/2018/credentials/v1"],
11          "type": ["VerifiableCredential"],
12          "credentialSubject": {
13          "givenName": "Emma Jane",
14          "familyName": "Tasma",
15          "dob": "1979-04-14"
16          }
17        "status": {
18            "index": 3,
19            "url": "https://learn.vii.au01.mattr.global/core/v2/credentials/compact/revocation-lists/887cd140-e4d7-4518-b70f-305b23778848"
20        },
21    },
22    "encoded": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU"
23}