Creating Presentation Definitions

This article explains what presentation definitions are and how to configure them within the Credential Verification Service (CVS) to request information from the wallet using these definitions.

What is a Presentation Definition?

A presentation definition is a structured representation of the data that the wallet should present to the verifier during the presentation protocol. The CVS uses these definitions to request certain information from wallets. You can have multiple presentation definitions within your CVS, depending on your own use cases and needs.

The following is a complete example of a presentation definition. In this example, the presentation definition instructs the wallet to include the values studentId, dateOfBirth and enrollmentYear in a verifiable presentation:

Presentation Definition Example:

{
  "input_descriptors": [
    {
      "id": "studentCard",
      "name": "University Student Card",
      "constraints": {
        "fields": [
          {
            "id": "studentId",
            "name": "Student ID",
            "path": [
              "$.credentialSubject.studentId",
              "$.vc.credentialSubject.studentId"
            ]
          },
          {
            "id": "dateOfBirth",
            "name": "Date of birth",
            "path": [
              "$.credentialSubject.dateOfBirth",
              "$.vc.credentialSubject.dateOfBirth"
            ]
          },
          {
            "id": "enrollmentYear",
            "name": "Enrollment year",
            "path": [
              "$.credentialSubject.enrollmentYear",
              "$.vc.credentialSubject.enrollmentYear"
            ]
          }
        ]
      }
    }
  ]
}

Here's a brief explanation of the fields of the example:

• input_descriptors This is an array of input descriptors. Input descriptors specify the type of information (claims) the wallet must present, including its identifier, human-readable name, and the constraints which specify which information must be presented by the wallet.
  • id A string that serves as an identifier for the input descriptor. This value is used when the CVS receives information from the wallet, and therefore must not conflict with other IDs.
  • name A human-readable string for the input descriptor.
  • constraints An object which establishes the requirements each claim presented by the wallet must meet.
    • fields An array of claims the wallet must present.
      • id A string that serves as an identifier for the claim. The value is used when the CVS receives information from the wallet, and therefore must not conflict with other IDs.
      • name A human-readable string describing the desired information.
      • path An array of JSON paths (strings) where the desired information may come from within the credential.

Creating a Presentation Definition

The overall structure of your own presentation definition must be updated and maintained. Therefore, use the example above as a guideline and starting point.

Begin by creating the id and name of your input descriptor. These values may be presented to the user (holder) by the wallet. Thus, both fields must be meaningful, and the name in particular should accurately describe the requested information.

The next step is to specify the information to be requested from the wallet by defining a claim for each piece of information required. Each object in the fields array corresponds to a claim. Within each object, you must define an id, a name and path. The path is an array of JSON paths where the information is located within the credential, as shown in the example above.

Use both $.credentialSubject and $.vc.credentialSubject as base paths for the path value to accommodate potential variations in credential formats. Additionally, it may make sense to specify multiple options, such as dateOfBirth and dob to ensure compatibility.

{
  "id": "dateOfBirth",
  "name": "Date of birth",
  "path": [
    "$.credentialSubject.dateOfBirth",
    "$.vc.credentialSubject.dateOfBirth",
    "$.credentialSubject.dob",
    "$.vc.credentialSubject.dob"
  ]
}

Add these object blocks into the fields array in the JSON structure separated by a comma.

Set up the CVS with your Presentation Definition

To set up the CVS with your newly created presentation definition, call the URL-to-your-CVS/openapi/presentation-definition/create endpoint on the CVS.

This can be done through the OpenAPI UI accessible on URL-to-your-CVS/openapi. From here you can interact with the endpoint by clicking on the "Try it out" button, and adding your own presentation definition in the request body before hitting execute.

Another option is to use curl:

curl -X 'POST' \
  '{CVS_URL}/presentation-definition/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "input_descriptors": [
    {
      "id": "studentCard",
      "name": "University Student Card",
      "constraints": {
        "fields": [
          {
            "id": "studentId",
            "name": "Student ID",
            "path": [
              "$.credentialSubject.studentId",
              "$.vc.credentialSubject.studentId"
            ]
          },
          {
            "id": "dateOfBirth",
            "name": "Date of birth",
            "path": [
              "$.credentialSubject.dateOfBirth",
              "$.vc.credentialSubject.dateOfBirth"
            ]
          },
          {
            "id": "enrollmentYear",
            "name": "Enrollment year",
            "path": [
              "$.credentialSubject.enrollmentYear",
              "$.vc.credentialSubject.enrollmentYear"
            ]
          }
        ]
      }
    }
  ]
}'

The CVS returns a 201 - created response with the ID of the newly created presentation definition. This confirms successful setup, and the system is now ready to request wallets to create presentations that adhere to the specified definition.

Follow this guide to make sure that your application receives the verification results from your CVS instance.