How to create a selective disclosure QueryByFrame presentation template

Presentation templates define what type of credential is required for a particular verification workflow. They are used to create presentation requests that are shared with a specific holder. The selective disclosure presentation template uses the W3C Verifiable Presentation Request Specification (opens in a new tab) QuerybyFrame query method (opens in a new tab).

Prerequisites

You must know the required 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.
• Trusted Issuers' DIDs.

Request

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

POST /v2/credentials/web-semantic/presentations/templates

Request body

{
    "domain": "learn.vii.au01.mattr.global",
    "name": "selective-disclosure-presentation",
    "query": [
        {
            "type": "QueryByFrame",
            "credentialQuery": [
                {
                    "required": true,
                    "reason": "Please provide your educational award and surname from your Certificate",
                    "frame": {
                        "@context": ["https://schema.org"],
                        "type": ["CourseCredential"],
                        "credentialSubject": {
                            "@explicit": true,
                            "educationalCredentialAwarded": {},
                            "givenName": {}
                        }
                    },
                    "trustedIssuer": [
                        {
                            "issuer": "did:web:organization.com",
                            "required": true
                        }
                    ]
                }
            ]
        }
    ]
}

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

• 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 exposed to the holder.

• query :

  • 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.

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

    • 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 template has multiple credentialQuery objects.

    • reason : This value is displayed to the holder by their wallet to provide context around why a credential is being requested.

    • 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. Only matched credentials will be included in the presentation response.
      If the requested credential uses a specific JSON-LD schema, you must add that schema to the @context array so that the credential could be matched against the presentation request.

      • type : The credential type that the wallet will use to return matching credentials. In this example, the verifier requires a 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. The credential 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. 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.
        • @explicit : Set this to true to only return claims included in the credentialSubject object in the verifiable presentation.

    • 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. In this example only one issuer is trusted but you can add multiple trusted issuers. If you want to accept credentials from any issuer as long as they match the defined credential type, leave this array empty.

      • issuer : Holds the issuer's identifier, which must use a BLS12381G2 key type.
      • required : Indicates whether this issuer is required for a credential to be accepted in this workflow.

Response

{
    "id": "6d597607-d64d-4209-8d2e-7e5a4587bbc8",
    "name": "selective-disclosure-presentation"
    //... rest of Basic presentation
}

• id : Unique identifier for this presentation template on your MATTR VII 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 delete this presentation template.

Once you've created the template, you can use it in Callback URL or OIDC Bridge verification workflows.