Data structure

Overview

CWT 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, CWT 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.

CWT 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. CWT and Semantic CWT 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 CWT 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 CWT 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), 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 claim types are predefined in the CWT standard to support interoperability.

You should only use predefined claims for their intended purpose. Attempting to use any of the predefined claims names as the name of a custom claim that represents a different data type will result in an error.

iss (Issuer): Represents the party who issued the credential. This a required field for both CWT and Semantic CWT 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.

Semantic CWT credentials claims

Custom claims are embedded in Semantic CWT 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 Semantic CWT 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"
    }
}

jti : Must be a valid URI according to the W3C Verifiable Credentials Data Model 1.0. To meet these requirements the decoded form of the cti claim must be a UUID.

Types Revocation