Learn

Create a selective-disclosure presentation template

As a verifier it is generally in your interest to only request essential information from credential holders. Selective-disclosure enabled credentials allow the mobile wallet to derive presentations of only the verifiable credential claims that are required, meaning non-essential information is not delivered to the verifier. This derived presentation is still verifiable as being issued by the trusted issuer and cannot be tampered with.

Prerequisites

To request only part of the information requested within a credential, you would use a selective-disclosure presentation template. As with a basic presentation template, in order to request a certain credential, you need to know the following properties of that credential:

  • the type of the credential

  • the JSON-LD schema of the credential (ie. what claims are in the credential)

  • the public DIDs of issuers whose credentials you are willing to accept

Additionally for selective disclosure enabled credentials, you will also need:

  • to know the exact claims you are requesting from the holder

  • to be certain that the issuer’s DID is using a BLS key type

To facilitate the request of specific fields and matching of available credentials a query type of queryByFrame using JSON-LD Framing is used. You will also need to ascertain that the credentials you want to verify using selective disclosure have been issued using the BLS12381G2 key type.
It's good practice to confirm with the issuer what type of key they have used to sign their credentials.

Request

As an example, a verifier asking for a credential of type CourseCredential would create the template request below. In a basic presentation request, you would use a QueryByExample to ask for the entire credential. However, in this template, we are only asking for the attributes familyName and educationalCredentialAwarded from the credential that matches.

json
Copy to clipboard. 
1{
2    "domain":"YOUR_TENANT_URL",
3    "name":"zkp-certificate-presentation",
4    "query": [{
5         "type":"QueryByFrame",
6         "credentialQuery":[
7            {
8               "reason": "Please provide your educational award and surname from your Certificate",
9               "frame":{
10                  "@context":[
11                    "https://schema.org"
12                  ],
13                  "type": ["CourseCredential"],
14                  "credentialSubject":{
15                     "@explicit":true,
16                     "educationalCredentialAwarded":{ },
17                     "givenName": { },
18                  }
19               },
20               "trustedIssuer":[
21                  {
22                     "issuer":"did:web:organization.com",
23                     "required":true
24                  }
25               ],
26               "required":true
27            }
28         ]
29      }]
30}

The domain indicates to the mobile wallet user the domain of the verifier that the request is coming from. This must always match your tenant URL or custom domain if you have set one up. You can learn more about setting up a custom domain here.

If you set up a custom domain later, any previous templates created where the domain is your tenant URL will become invalid. You will need to change any prior templates to use the custom domain.

If the domain validation is not successful, the wallet will not let the user proceed with sending you a credential.

The name is a unique value that is intended to be used internally to let you manage your templates. It will not be shown to the wallet user.

The reason is shown in the mobile wallet to give context around why a credential is being requested. Ensure that this is written exactly as you would like it to appear to the user.

You can request multiple credentials in one request by adding objects to the query array. In the case above, the query array only contains a single query and is therefore asking for one credential.

As part of the frame query:

  • @context is the JSON-LD schema, which is used to expand the example in the query. Match is performed on the expanded type of the credential.

For example, in this example query, the expanded type

"http://schema.org/CourseCredential" would match any credential that has the same

expanded type.

  • The wallet will use type to match credentials that it holds, however, the first type will always need to be set to VerifiableCredential.

  • The credentialSubject states which of the claims from the credential are required for the presentation, only these claims are required in the derived credential sent to be verified. Mattr VII platform also supports for explicit matches inside of credentialSubject like familyName: "Smith" will match the exact value and the wallet will allow the user to select credentials where the family name matches the exact value provided.

  • The issuer in trustedIssuer filters which credentials will be acceptable. An employer, for instance, might only accept the public DIDs of certain universities. For ZKP-enabled credentials, you need to ensure this DID is using a BLS key type.

Before creating your presentation template, check the case sensitivity and nesting of all values in the JSON payload against the examples above, or the API Reference.


⚠️ Warning
The presentation template must conform to the specification exactly in order to correctly enable selective disclosure presentations.

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 educationalCredentialAwarded and familyName. Instead the wallet will return a full presentation/disclosure of all the claims within the selected credential.

Response

json
Copy to clipboard. 
1{
2  "id": "6d597607-d64d-4209-8d2e-7e5a4587bbc8",
3  "name": "zkp-certificate-presentation",
4  "domain": "YOUR_TENANT_URL",
5  "query": [
6    {
7      "type": "QueryByFrame",
8      "credentialQuery": [
9        {
10          "reason": "Please provide your educational award and surname from your Certificate",
11          "frame": {
12            "@context": [
13              "https://schema.org"
14           ],
15            "type": "VerifiableCredential",
16            "credentialSubject": {
17              "@explicit": true,
18              "educationalCredentialAwarded": {},
19              "givenName": {}
20            }
21          },
22          "trustedIssuer": [
23            {
24              "issuer": "did:web:organization.com",
25              "required": true
26            }
27          ],
28          "required": true
29        }
30      ]
31    }
32  ]
33}

Take a note of the id generated for your template. You will use this to create presentation requests.

Further configuration options

Both basic and selective-disclosure forms of Presentation Templates accept an array of queries inside a single request, it is recommended that you experiment with adding multiple credential requests into a single template to ensure you get the desired outcomes.

Next steps

Once you have the Presentation Request Template configured, the template ID can be used in setting up your tenant to verify a credential using a callback or using OIDC Bridge. Take a look at verifying a ZKP-enabled credential for more details on how to use this template.