Query Language

When the Verifier creates an authorization request, it must describe exactly which credentials it will accept and which fields it needs from them. You express those requirements using one of two standard query forms — a DCQL (Digital Credentials Query Language) query or a DIF Presentation Exchange v2 definition — supplied inline in the request body. The wallet uses your query to select matching credentials and, for SD-JWT credentials, to disclose only the requested claims.

Key Concepts

• Query forms: Credential requirements are expressed as either a dcqlQuery object or a presentationDefinition object. Both are standard formats, so wallets that follow the OpenID4VP specification understand them without any vendor-specific extensions.

• Where the query lives: The query is not stored or referenced by ID — it is sent inline in the body of POST /verifiers/:verifierId/authorization-requests (and its /qr-code variant). Each request carries its own query.

• One form per request: Supply exactly one of dcqlQuery or presentationDefinition. If you omit both, the request is rejected with 400 Bad Request and the message Either dcqlQuery or presentationDefinition must be provided. Sending both passes the service's own input validation but fails downstream for every version value, surfacing as a 500.

• Paths and filters (Presentation Exchange): Inside a Presentation Exchange input descriptor, constraints.fields use JSONPath expressions in path to locate a value in the credential, and an optional JSON Schema (Draft 7) filter to validate it (for example type, enum, pattern, or contains).

• Selective disclosure: For SD-JWT VC credentials, the claims your query asks for are the claims the wallet selectively discloses. Fields the credential supports but the query does not request stay hidden, so the holder shares only what the Verifier needs.

DCQL Example

DCQL is a compact, credential-centric query format. The following query requests an EmployeeBadge SD-JWT VC and asks the wallet to disclose only the employee_id and department claims:

{
  "responseMode": "direct_post.jwt",
  "version": "v1",
  "dcqlQuery": {
    "credentials": [
      {
        "id": "employee_badge",
        "format": "dc+sd-jwt",
        "meta": {
          "vct_values": ["https://issuer.example.com/vct/employee-badge"]
        },
        "claims": [
          { "path": ["employee_id"] },
          { "path": ["department"] }
        ]
      }
    ]
  }
}

• format is the requested credential format (for example dc+sd-jwt for SD-JWT VC).

• meta.vct_values restricts the request to credentials with a matching vct (verifiable credential type).

• Each entry in claims names a claim with a path, and those are the claims the wallet discloses.

Presentation Exchange Example

A DIF Presentation Exchange v2 definition is more verbose but lets you attach JSON Schema filters to individual fields. presentationDefinition requires version v1.draft21 or v1.draft24 (the default v1 supports only dcqlQuery). The following definition requests a credential whose type array contains EmploymentCredential and whose subject is identified by a did:web identifier:

{
  "responseMode": "direct_post.jwt",
  "version": "v1.draft24",
  "presentationDefinition": {
    "id": "pd-employment",
    "input_descriptors": [
      {
        "id": "employment_vc",
        "format": { "jwt_vc_json": { "alg": ["EdDSA"] } },
        "constraints": {
          "fields": [
            {
              "path": ["$.type"],
              "filter": {
                "type": "array",
                "contains": { "const": "EmploymentCredential" }
              }
            },
            {
              "path": ["$.credentialSubject.id"],
              "filter": {
                "type": "string",
                "pattern": "^did:web:.*$"
              }
            }
          ]
        }
      }
    ]
  }
}

• path holds one or more JSONPath expressions; the first one that resolves is used.

• filter is a JSON Schema (Draft 7) the extracted value must satisfy. Use a method-agnostic pattern (for example ^did:.*$) when you do not need to constrain the DID method.

Response

A successful request returns the authorization request URI and the verification session you can poll or stream for results:

{
  "authorizationRequestUri": "openid4vp://?request_uri=...",
  "verificationSessionId": "18b760b1-4ab8-4d38-9d42-6b4c25a4d2e0",
  "authorizationRequestId": "1b8a6a8b-2ac1-4f0b-9d9c-6b9c859b1af2",
  "expiresAt": "2024-08-09T12:34:56.789Z"
}

Pick whichever form fits your stack — both let you constrain credential types, claims, and field values.