Learn

Data structure

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. There are two types of custom claims variants for Compact and Compact Semantic Credentials.

Standard Claims

Standard claims are represented on the top level of the decoded object, whereas the entire CBOR Web Token (CWT) with the associated string prefixed can be found in the encoded object of the signed credential:

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}

The following standard claims can be included in a Compact or Compact Semantic Credential:

  • iss (issuer, claim key 1): The party who issued the credential. This must be a did:web using a P-256 key type that must be publicly available on the tenant. This is the only standard claim that is required for both Compact and Compact Semantic Credentials.

  • sub (subject, claim key 2): The subject of the credential. If this claim is presented its value must be a text string.

  • kid (key identifier, claim key 4): References the signing key material. Its value corresponds to a relative reference to the key used to verify the signature of the credential, which must be combined with the iss value to resolve the public key.

  • alg (algorithm, claim key 4): Algorithm used for creating the signature.

  • exp (expiry, claim key 4): Credential expiry date, expressed as a timestamp encoded as an integer in the NumericDate format. Beyond that date, the credential cannot be verified as valid.

  • nbf (not before, claim key 5): The date the credential will be valid from, expressed as a timestamp encoded as an integer in the NumericDate format. Prior to that date, the credential cannot be verified as valid.

  • iat (issued at, claim key 6): Credential issuance date, expressed as a timestamp encoded as an integer in the NumericDate format.

  • cti: (credential id, claim key 7): Unique credential identifier, presented as a byte string.

  • status (claim key of -65537 in the private range): Specifies the credential revocation status.

Custom claims

Any custom claims can be included as part of Compact and Compact Semantic Credentials, with two payload variants based on the selected profile.

Compact Credentials

Custom claims are embedded in Compact Credentials just like standard claims in the top level. The following example shows a Compact Credential with two custom claims named custom_claim1 and custom_claim2:

json
Copy to clipboard.
1{
2  "iss": "did:web:learn.vii.au01.mattr.global",
3  "nbf": 1615084531,
4  "exp": 1836009331,
5  "jti": "Z2kmyTU-RBa08U3Kb8ZeZw",
6  "status": {
7    "url": "https://learn.vii.au01.vii.mattr.global/core/v2/credentials/compact/revocation-lists/8f25e8a5-c878-411e-8141-43fb2d257137",
8    "index": 23434
9  },
10  "custom_claim1": "value1",
11  "custom_claim2": "value2"
12}

The value of any custom claims in the credential must be either a boolean, a string or a number.

The jti claim is transformed from a byte string of the cti standard claim (credential identifier) to its equivalent string-based representation. The decoded jti value will be encoded with base64URL without padding.

Compact Semantic Credentials

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 decoded payload:

json
Copy to clipboard.
1{
2  "iss": "did:web:example.nz",
3  "nbf": 1516239022,
4  "exp": 1516239922,
5  "jti": "urn:uuid:cc599d04-0d51-4f7e-8ef5-d7b5f8461c5f",
6  "vc": {
7    "@context": ["https://www.w3.org/2018/credentials/v1"],
8    "type": ["VerifiableCredential"],
9    "credentialSubject": {
10      "givenName": "John Andrew",
11      "familyName": "Doe",
12      "dob": "1979-04-14"
13    }
14  }
15  "status": {
16    "url": "https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v2/credentials/compact/revocation-lists/8f25e8a5-c878-411e-8141-43fb2d257137",
17    "index": 23434
18  }
19}

The value of any dynamic claims within vc.credentialSubject must be either a boolean, a string or a number. However, this can be extended to support more complex values in the future.

The jti claim 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.