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 create verifiable presentations which only include the required claims, meaning non-essential information is not delivered to the verifier. This derived presentation is still verifiable as being issued by the trusted issuer and that it has not been tampered with.

The selective-disclosure presentation template uses the JSON-LD Framing queryByFrame query method.

Prerequisites

  • Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.

  • Requested credential properties:

    • The credential type.

    • What claims are included in the credential (i.e. its JSON-LD schema).

    • What specific claims you are requesting from the holder.

    • The Issuers DIDs whos credentials you are willing to accept. Remember that issuers must use a BLS12381G2 key type to support selective disclosure. It's always good practice to confirm with the issuer what type of key they have used to sign their credentials.

Request

Make a request of the following structure to create a selective-disclosure presentation template:

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

  • domain: Informs the wallet holder what domain is the verification request coming from. The value must match your tenant URL or your custom domain (if you have one set up). If the domain validation is not successful, the wallet will not let the user proceed with the verification workflow.

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.

  • name: Unique value that is used internally to manage your templates. It must be unique across all presentation templates on your tenant, but is not shown to the holder.

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

    • type: Indicates what type of query method would be used by presentation requests created from this presentation template. For selective-disclosure presentation templates you must use QueryByFrame. Refer to Create a basic presentation template for additional supported query methods.

    • credentialQuery:

      • required: When set to true, the verification workflow will fail if a matching credential is not provided in the verifiable presentation response. You can only change this to false when your templates has multiple credentialQuery objects.

      • reason: This value is displayed in the mobile wallet to provide the holder with context around why a credential is being requested. Ensure that this is written exactly as you would like it to appear to the user.

      • frame:

        • @context: This is the JSON-LD schema that will be used to expand the example in the query. This example query would match any credential that has the same expanded "http://exampleschema.com/CourseCredential" type, and only matched credentials will be included in the presentation response.

          In case the credential uses a specific JSON-LD schema, you must add that schema into the @context array so that the credential could be matched against the presentation request.

        • type: The credential type that the mobile wallet will use to return matching credentials. In this example, the verifier is seeking to obtain credential of type CourseCredential. Upon the holder's consent, the wallet would only return credentials that match this type and have been issued by the issuers included in the trustedIssuer object. Credentials type is set when you issue a credential. When you include multiple credential types, the wallet will only return credentials that include all of the included types.

        • credentialSubject: This object details what claims are required for this verification workflow. Only claims included in this object will be included in the verifiable presentation, as long as you set @explicit to true.

          This example only asks for the educationlCredentialAwarded and givenName claims from matching credentials. MATTR VII supports explicit matches. For example, familyName: "Smith" will make the wallet only show credentials where the family name matches the exact value provided.

        • trustedIssuer: This array is used to determine what credential issuers to accept in this verification workflow. For example, an employer might only accept credentials issued by certain universities.

          Each object includes a issuer field which holds the issuer's DID, and a required field which indicates whether this issuer is required for a credential to be accepted in this workflow.

          For selective-disclosure credentials, the did must use a BLS key type.

          In this example only one issuer is trusted but you can add multiple trusted issuers. Alternatively, if you want to accept credentials from any issuer as long as they match the defined credential type, leave this array empty.

All the attributes are case-sensitive. For example, if you use incorrect casing 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 of all the claims within the selected credential.

Be sure to check capitalisation and thoroughly test your configuration before running them in production.

Response

json
Copy to clipboard.
1{
2    "id": "6d597607-d64d-4209-8d2e-7e5a4587bbc8",
3    "name": "selective-disclosure-presentation",
4//... rest of Basic presentation
5}

  • id: Unique identifier for this presentation template on your tenant. You will need it to create a presentation request based on this template. You can also use it to retrieve, update (for example to include from trusted issuers or to update a custom domain) or remove this presentation template.

What's next?

Once you created a presentation template, you can use it to verify a credential using a callback or using OIDC Bridge. Refer to verifying a selective-disclosure credential for more details on how to use this template's unique capabilities.