Skip to main content

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 blockPurpose
Credential QueryRequests a specific credential by format, metadata, and claims. The fundamental unit of a DCQL query.
trusted_authoritiesRestricts accepted credentials to those issued by specific trust anchors (EU Trust List, EBSI, OpenID Federation).
claimsSpecifies which individual claims within a credential are requested, enabling selective disclosure.
claim_setsDefines acceptable combinations of claims, allowing preferred claims with fallback alternatives.
credential_setsGroups multiple credential queries with logical rules (AND/OR), supporting mandatory and optional sets.
multipleWhen set to true, allows several instances of the same credential type to be returned in a single flow.
valuesConstrains accepted claim values to a predefined allowed list.

Rules of the iGrant.io API​

Store the DCQL query in a presentation definition (POST /v2/config/digital-wallet/openid/sdjwt/presentation-definition) with version set to version_01. The API checks the query when you save it:

  • Every Credential Query needs id, format and meta. The id holds letters, digits, _ and - only.
  • The format sets the meta key: vct_values for dc+sd-jwt, doctype_value for mso_mdoc, and type_values for jwt_vc_json.
  • An mso_mdoc claim path holds exactly two strings: the namespace and the data element.
  • A jwt_vc_json claim path starts with a member of the credential, so a subject claim starts with credentialSubject.
  • claims and trusted_authorities must not be empty when you send them, and claim_sets needs claims.

See Create presentation definition for the full 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.

ExampleDCQL featureScenario
Trusted Authoritiestrusted_authoritiesRequest a University Degree credential only from issuers in the EU Trust List, EBSI, or an OpenID Federation trust anchor.
Claim Sets (Selective Disclosure)claim_setsVerify age from a PID credential, preferring a boolean over_21 claim and falling back to the full birthdate.
Credential Sets (Alternatives)credential_setsAccept any one of a Passport, PID, or Photo ID for proof of identity.
Combined Credential SetsMultiple required credential_setsRequire a Photo ID plus a Proof of Address (Utility Bill or Bank Statement).
Mandatory and Optional SetsMandatory + optional credential_setsRequire PID and student proof, with optional address proof for an additional discount.
Multiple Credential Instancesmultiple: trueRequest six recent Bank Statement credentials in a single verification flow.
Values ConstraintvaluesAccept a PID credential only if the postal code matches an allowed list.