Creating Presentation Definitions
This article explains what presentation definitions are and how to configure them within the credential verification serviceto 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 credential verification service uses these definitions to request certain information from wallets. You can have multiple presentation definitions within your credential verification service, 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": [ // (1)!
{
"id": "studentCard", // (2)!
"name": "University Student Card", // (3)!
"constraints": { // (4)!
"fields": [ // (5)!
{
"id": "studentId", // (6)!
"name": "Student ID", // (7)!
"path": [ // (8)!
"$.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"
]
}
]
}
}
]
}
- 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.
- A string that serves as an identifier for the input descriptor. This value is used when the credential verification service receives information from the wallet, and therefore must not conflict with other IDs.
- A human-readable string for the input descriptor.
- An object which establishes the requirements each claim presented by the wallet must meet.
- An array of claims the wallet must present.
- A string that serves as an identifier for the claim. The value is used when the credential verification service receives information from the wallet, and therefore must not conflict with other IDs.
- A human-readable string describing the desired information.
- 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 credential verification service with your Presentation Definition
To set up the credential verification service with your newly created presentation definition, call the /presentation-definition/create endpoint on the credential verification service.
Another option is to use curl:
curl -X 'POST' \
'{credential_verification_service_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 credential verification service 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 credential verification service instance.