DCQL (Digital Credential Query Language)
The Digital Credential Query Language (DCQL, pronounced "dak-l") is a JSON-based query language introduced in the OpenID for Verifiable Presentations (OpenID4VP) 1.0 specification. It enables verifiers to express precise requirements for the credentials they need from a holder's wallet.
A DCQL query is a JSON object with two top-level properties:
credentials(required): An array of Credential Query objects, each describing a specific credential the verifier is interested in.credential_sets(optional): An array defining logical groupings and requirements across the requested credentials.
For the full specification, business context, and real-world payment examples, see our concepts article on DCQL in the EUDI Wallet ecosystem.
Building Blocks
DCQL provides a small set of composable building blocks that cover a wide range of verification scenarios:
| Building block | Purpose |
|---|---|
| Credential Query | Requests a specific credential by format, metadata, and claims. The fundamental unit of a DCQL query. |
trusted_authorities | Restricts accepted credentials to those issued by specific trust anchors (EU Trust List, EBSI, OpenID Federation). |
claims | Specifies which individual claims within a credential are requested, enabling selective disclosure. |
claim_sets | Defines acceptable combinations of claims, allowing preferred claims with fallback alternatives. |
credential_sets | Groups multiple credential queries with logical rules (AND/OR), supporting mandatory and optional sets. |
multiple | When set to true, allows several instances of the same credential type to be returned in a single flow. |
values | Constrains accepted claim values to a predefined allowed list. |
Developer Workflow Examples
Each example below demonstrates a specific DCQL building block through a complete developer workflow with runnable API calls. You can also try these scenarios live in the iGrant.io DCQL demos and watch walkthroughs on the iGrant.io YouTube channel.
| Example | DCQL feature | Scenario |
|---|---|---|
| Trusted Authorities | trusted_authorities | Request a University Degree credential only from issuers in the EU Trust List, EBSI, or an OpenID Federation trust anchor. |
| Claim Sets (Selective Disclosure) | claim_sets | Verify age from a PID credential, preferring a boolean over_21 claim and falling back to the full birthdate. |
| Credential Sets (Alternatives) | credential_sets | Accept any one of a Passport, PID, or Photo ID for proof of identity. |
| Combined Credential Sets | Multiple required credential_sets | Require a Photo ID plus a Proof of Address (Utility Bill or Bank Statement). |
| Mandatory and Optional Sets | Mandatory + optional credential_sets | Require PID and student proof, with optional address proof for an additional discount. |
| Multiple Credential Instances | multiple: true | Request six recent Bank Statement credentials in a single verification flow. |
| Values Constraint | values | Accept a PID credential only if the postal code matches an allowed list. |
Related
- OpenID4VP credential verification shows where a DCQL query fits in the full verifier flow.
- OpenID4VCI credential issuance covers how the credentials that DCQL queries are first issued.