Docs
Credential Profiles
Compact Credentials
Data structure

Data structure

Overview

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) (opens in a new tab) data format called CBOR Web Token (CWT) (opens in a new tab). 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) (opens in a new tab) is used to create ubiquitous JSON Web Tokens (JWT) in the signed (JWS) and encrypted (JWE) flavours. Similarly, CBOR Object Signing & Encryption (COSE) (opens in a new tab) 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
{
    "id": "bKcrxojFSuSZvI5qhKInxA",
    "decoded": {
        "iss": "did:web:learn.vii.au01.mattr.global",
        "nbf": 1704099600,
        "type": "Course Credential",
        "exp": 1767258000,
        "name": "Emma Jane Tasma",
        "code": "HS.278",
        "certificationName": "Working at Heights",
        "certificationLevel": "Level 4",
        "issuerName": "Advanced Safety Training",
        "status": {
            "index": 3,
            "url": "https://learn.vii.au01.mattr.global/v2/credentials/compact/revocation-lists/887cd140-e4d7-4518-b70f-305b23778848"
        },
        "jti": "bKcrxojFSuSZvI5qhKInxA"
    },
    "encoded": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU"
}
  • id : Unique identifier of this Compact Credential. This is the jti claim, which is the CBOR Web Token (CWT) identifier detailed below.
  • 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) (opens in a new tab), 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 (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab).

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

{
    "id": "bKcrxojFSuSZvI5qhKInxA",
    "decoded": {
        "iss": "did:web:learn.vii.au01.mattr.global",
        "nbf": 1516239022,
        "type": "Course Credential",
        "exp": 1516239922,
        "jti": "urn:uuid:cc599d04-0d51-4f7e-8ef5-d7b5f8461c5f",
        "vc": {
            "@context": ["https://www.w3.org/2018/credentials/v1"],
            "type": ["VerifiableCredential"],
            "credentialSubject": {
                "givenName": "Emma Jane",
                "familyName": "Tasma",
                "dob": "1979-04-14"
            },
            "status": {
                "index": 3,
                "url": "https://learn.vii.au01.mattr.global/v2/credentials/compact/revocation-lists/887cd140-e4d7-4518-b70f-305b23778848"
            }
        },
        "encoded": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU"
    }
}
Core capabilitiesCredential profiles