Presentation Template Troubleshooting & Best Practices
Creating a presentation template requires careful crafting of the template. This page provides a list of common misconceptions, mistakes and best practices.
All guides on MATTR VII assume using the MATTR Wallet production app. If you are using an app built on our SDK, there might be different error messages or behaviours you may encounter.
If the help on this page does not resolve your issue, please get in touch with us either through the Slack community group or through our contact page.
I do not know which template to use
MATTR VII provides two types of templates - QueryByExample and QueryByFrame. If you want to simply get an entire credential from a wallet holder which includes all of its claims and details about the issuer, use our basic presentation template guide that goes over QueryByExample.
If you want to only get select claims from a credential, eg. just a firstName attribute from a student ID credential, you would use QueryByFrame. See our Selective-disclosure presentation template guide on how to use it. Do note that the credential you are wanting to verify needs to be issued using a DID which has the BLS12381G2 key type.
I'm not seeing the credential in the verification request
Credential Types:
When the wallet looks at a presentation request, it tries to match against all the types you defined in your template. The credential in the wallet should have all the types match with what you defined. Here are a few examples of what will work and what won't:
Credential has types: [VerifiableCredential, AcademicCertificate]
Presentation Template has types: [VerifiableCredential, AcademicCertificate]This will work because both the credential and the template have exactly the same types.
Credential has types: [VerifiableCredential, AcademicCertificate]
Presentation Template has types: [AcademicCertificate]This will work because the template asks for only one type condition to be met. The credential has an array of two types but it contains the AcademicCertificate type and so will be valid.
Credential has types: [VerifiableCredential, AcademicDegree]
Presentation Template has types: [VerifiableCredential, AcademicCertificate]This will not work because the credential has a type of AcademicCertificate and the template has AcademicDegree. All the conditions in the template must be satisfied for a match and in this case, our credential does not have a type AcademicDegree.
Trusted Issuers:
Along with the types, the template also matches against trusted issuers. Check that you have included the issuer DID from the credential you want to accept into the trusted Issuers array.
Alternatively, if you want to accept credentials from any issuer as long as it matches the types that you have configured, you can leave the array empty which lets the wallet know that you do not have an issuer DID constraint.
How do I request multiple credentials?
You can add multiple credential requests as additional array items inside the credentialQuery array. For example, let's say we want to ask for a StudentID credential in addition to the CourseCredential we defined in the basic presentation template guide. You would create an additional credentialQuery item and provide relevant reason, type, and trustedIssuer attributes as shown below.
Selective disclosure presentation templates follow the same change to add multiple credential requests.
1{
2 "domain":"YOUR_TENANT_URL",
3 "name":"certificate-presentation",
4 "query":[{
5 "type": "QueryByExample",
6 "credentialQuery": [{
7 "required": true,
8 "reason": "Please provide your certificate.",
9 "example": {
10 "@context": ["https://schema.org"],
11 "type": "CourseCredential",
12 "trustedIssuer": [{
13 "required": true,
14 "issuer": "did:web:organization.com"
15 }]
16 }
17 },
18 // Add the student ID request inside the credentialQuery array
19 {
20 "required": true,
21 "reason": "Please provide your student ID.",
22 "example": {
23 "@context": ["https://schema.org"],
24 "type": "StudentID",
25 "trustedIssuer": [{
26 "required": true,
27 "issuer": "did:web:organization.com"
28 }]
29 }
30 }]
31 }]
32}
How can I make some credentials be optional to present?
You may have a case where you are asking for multiple credentials in a request but some of them are optional. To set this, change the required property to false inside the correct credentialQuery array element. This will show the wallet holder an option to select none of the credentials for that part of the request.
Can I ask for a credential where a claim in it matches a certain value?
No. At the moment, MATTR VII currently only supports wildcard matching from JSON-LD framing. This means that trying to ask for explicit matches inside of credentialSubject like familyName: "Smith" will not work and the wallet will allow the user to select credentials where the family name does not match.
Why am I getting all the claims from a credential when I only asked for some?
Check that you are using selective-disclosure enabled QueryByFrame and not the basic QueryByExample template.
Also ensure that you have set "@explicit":true inside the credentialSubject object. This will let the wallet know to only select those claims. Also check that you have used curly brackets as the values for the claims and not some other symbol. Eg. "familyName":{ } and not "familyName": [] or familyName: ().
Be sure to check the case sensitivity and nesting of all values in the JSON payload against the API Reference. For example, if you use the incorrect character casing in the template for credentialSubject, the wallet will not understand that the request is looking for a selective disclosure of just familyName. Instead the wallet will return a full presentation/disclosure of all the claims within the selected credential.