How to create a basic QueryByExample 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 basic presentation template uses the W3C Verifiable Presentation Request Specification QuerybyExample query method.

Prerequisites

You must know the required credential properties:

• The credential type.
• What claims are included in the credential (i.e. its JSON-LD schema).
• Trusted Issuers’ DIDs.

Request

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

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

Request body

{
    "domain": "learn.vii.au01.mattr.global",
    "name": "certificate-presentation",
    "query": [
        {
            "type": "QueryByExample",
            "credentialQuery": [
                {
                    "required": true,
                    "reason": "Please provide your certificate.",
                    "example": {
                        "@context": ["https://exampleschema.com"],
                        "type": "CourseCredential",
                        "trustedIssuer": [
                            {
                                "required": true,
                                "issuer": "did:web:organization.com"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

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

  If you set up a custom domain later, any templates where the domain is your tenant URL will become invalid until you update their domain with your custom domain URL.

• 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 basic presentation templates you must use QueryByExample.

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

    • example : This details the credential to query for.

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

      • 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.
        • required : Indicates whether this issuer is required for a credential to be accepted in this workflow. 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.

Response

{
    "id": "f95e71b0-9bdf-11ea-aec9-3b5c35fc28c8",
    "name": "certificate-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.