Creating DCQL Queries

This article explains what DCQL queries are and how to configure them within the credential verification service to request information from the wallet using these queries.

What is a DCQL Query?

A DCQL query 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 queries to request certain information from wallets. You can have multiple DCQL queries within your credential verification service, depending on your own use cases and needs.

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

DCQL Query Example:

{
  "credentials": [ // (1)!
    {
      "id": "studentCard", // (2)!
      "format": "jwt_vc_json-ld", // (3)!
      "meta": {}, // (4)!
      "claims": [ // (5)!
        {
          "id": "studentId", // (6)!
          "path": [ "credentialSubject", "studentId" ] // (7)!
        },
        {
          "id": "dateOfBirth",
          "path": [ "credentialSubject", "dateOfBirth" ]
        },
        {
          "id": "enrollmentYear",
          "path": [ "credentialSubject", "enrollmentYear" ]
        }
      ]
    }
  ]
}

1. This is an array of credential queries. Each credential query specifies the type of information (claims) the wallet must present for this requested credential. A single DCQL query can contain multiple credential queries, and the wallet must present all of them in the presentation.
2. A string that serves as an identifier for the credential query. This value is used when the wallet prepares the presentation, and therefore must not conflict with other IDs.
3. The format of the requested credential.
4. An object defining additional properties requested by the Verifier that apply to the metadata and validity data of the Credential. This is a required field, but it can be an empty object if no additional properties are requested.
5. An array of Claim Queries specifying which claims the wallet must present.
6. A string that serves as an identifier for the claim query. This is an optional field, but it can be useful for keeping track of claims and their values. If used, the value must not conflict with other IDs.
7. An array of strings specifying a path to the requested claim value within a credential.

Creating a DCQL Query

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

The main part of a DCQL query are the list of Claims Queries that specify the information to be requested from the wallet. Within each Claim Query object, you must define path and optionally an id (recommended). The path is an array of strings specifying a path to where the information is located within the credential.

{
    "id": "dateOfBirth",
    "path": ["credentialSubject", "dateOfBirth"]
}

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

Set up the credential verification service with your DCQL Query

To set up the credential verification service with your newly created DCQL query, call the /dcql-query/create endpoint on the credential verification service.

Another option is to use curl:

curl -X 'POST' \
  '{credential_verification_service_URL}/dcql-query/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "credentials": [
    {
      "id": "studentCard",
      "format": "jwt_vc_json-ld",
      "meta": {},
      "claims": [
        {
          "id": "studentId",
          "path": ["credentialSubject", "firstName"]
        },
        {
          "id": "dateOfBirth",
          "path": ["credentialSubject", "dateOfBirth"]
        },
        {
          "id": "enrollmentYear",
          "path": ["credentialSubject", "enrollmentYear"]
        }
      ]
    }
  ]
}'

The credential verification service returns a 201 - created response with the ID of the newly created DCQL query. This confirms successful setup, and the system is now ready to request wallets to create presentations that adhere to the specified query.

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