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:
{
"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 thejti
claim, which is the CBOR Web Token (CWT) identifier detailed below.decoded
: Includes both standard and custom claims. In the above exampleiss
,nbf
,type
,exp
,status
andjti
are standard claims, while all other properties are custom claims (name
,code
,certificationName
,certificationLevel
andissuerName
).encoded
: This is a CBOR Web Token (CWT) (opens in a new tab), which is the decoded object represented as an encoded string. TheCSC:/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 adid:web
using aP-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 theiss
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 beES256
. 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 theNumericDate
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 theNumericDate
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 theNumericDate
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"
}
}
jti
: Must be a valid URI according to the W3C Verifiable Credentials Data Model 1.0 (opens in a new tab). To meet these requirements the decoded form of thecti
claim must be a UUID.