DCQL explained: how a verifier asks a wallet for exactly what it needs

The problem DCQL solves

Asking for a fallback: claim_sets

claim_sets lists groups of claim ids, in order of preference. The wallet returns the first group it can fully satisfy from what the holder actually holds, instead of the verifier having to send two separate requests for a precise case and a fallback case.

{
  "credentials": [
    {
      "id": "company_registration",
      "format": "dc+sd-jwt",
      "meta": { "vct_values": ["urn:eudi:business:company-registration:1"] },
      "claims": [
        { "id": "reg_no", "path": ["registration_number"] },
        { "id": "legal_name", "path": ["legal_name"] }
      ],
      "claim_sets": [
        ["reg_no", "legal_name"],
        ["legal_name"]
      ]
    }
  ]
}

Here the verifier prefers a registration number plus the legal name, but will accept the legal name on its own if the holder’s credential does not carry a registration number claim.

{
  "vp_token": {
    "company_registration": [
      "<issuer-signed JWT>~<disclosure: legal_name>~<key binding JWT>"
    ]
  }
}

{
  "vct": "urn:eudi:business:company-registration:1",
  "legal_name": "Example Logistics B.V."
}

Combining credentials: credential_sets

credential_sets works one level up from claim_sets. Each entry lists options, where every option is a group of credential query ids. The wallet has to satisfy one option of every required entry, which gives a verifier AND and OR logic across credentials in a single request.

"credential_sets": [
  { "options": [["company_registration"]] },
  { "options": [["vat_registration"], ["bank_account"]] }
]

Example response: registration plus bank account

What the wallet sends

{
  "vp_token": {
    "company_registration": [
      "<issuer-signed JWT>~<disclosures>~<key binding JWT>"
    ],
    "bank_account": [
      "<issuer-signed JWT>~<disclosures>~<key binding JWT>"
    ]
  }
}

Claims the verifier sees after validation

{
  "company_registration": {
    "vct": "urn:eudi:business:company-registration:1",
    "registration_number": "12345678",
    "legal_name": "Example Logistics B.V."
  },
  "bank_account": {
    "vct": "urn:eudi:business:bank-account:1",
    "iban": "NL91ABNA0417164300",
    "account_holder": "Example Logistics B.V."
  }
}

The holder has no VAT registration credential, so the wallet chose the second option of the second set. Query ids that were not used, here vat_registration, are simply absent from vp_token.

Only trusted issuers: trusted_authorities

trusted_authorities narrows a credential query to credentials whose issuer is backed by an authority the verifier trusts. Each entry has a type and a list of values: aki for an authority key identifier, etsi_tl for an ETSI trusted list, or openid_federation for a federation trust anchor. The wallet only offers credentials that match.

Worked example: a registration from a listed issuer

{
  "credentials": [
    {
      "id": "company_registration",
      "format": "dc+sd-jwt",
      "meta": { "vct_values": ["urn:eudi:business:company-registration:1"] },
      "trusted_authorities": [
        {
          "type": "etsi_tl",
          "values": ["https://ec.europa.eu/tools/lotl/eu-lotl.xml"]
        }
      ],
      "claims": [
        { "id": "reg_no", "path": ["registration_number"] },
        { "id": "legal_name", "path": ["legal_name"] }
      ]
    }
  ]
}

Example response: only the listed issuer’s credential

What the wallet sends

{
  "vp_token": {
    "company_registration": [
      "<issuer-signed JWT>~<disclosure: registration_number>~<disclosure: legal_name>~<key binding JWT>"
    ]
  }
}

Claims the verifier sees after validation

{
  "vct": "urn:eudi:business:company-registration:1",
  "registration_number": "12345678",
  "legal_name": "Example Logistics B.V."
}

The holder also had a registration credential from an unlisted issuer, but the wallet did not offer it. trusted_authorities is a filter for the wallet, not a guarantee: the verifier still checks the issuer against the trusted list itself when it validates the presentation.

Matching a value: claims.values

A claim query can carry values, a list of strings, integers or booleans. The wallet only returns the claim when its type and value exactly match one of them, so a verifier can check a condition without asking for anything else first.

Worked example: only companies registered in the Netherlands or Belgium

{
  "credentials": [
    {
      "id": "company_registration",
      "format": "dc+sd-jwt",
      "meta": { "vct_values": ["urn:eudi:business:company-registration:1"] },
      "claims": [
        { "id": "legal_name", "path": ["legal_name"] },
        {
          "id": "reg_country",
          "path": ["registration_country"],
          "values": ["NL", "BE"]
        }
      ]
    }
  ]
}

Example response: a Dutch company

What the wallet sends

{
  "vp_token": {
    "company_registration": [
      "<issuer-signed JWT>~<disclosure: legal_name>~<disclosure: registration_country>~<key binding JWT>"
    ]
  }
}

Claims the verifier sees after validation

{
  "vct": "urn:eudi:business:company-registration:1",
  "legal_name": "Example Logistics B.V.",
  "registration_country": "NL"
}

A German company’s credential has registration_country "DE", so it does not satisfy the query and the wallet has nothing to return for it. The verifier should still check the value in the validated claims rather than rely on the wallet’s filtering.

Where DCQL stands today

• DCQL is defined within the OpenID4VP specification itself, not as a separate document, and has been part of the draft since the mechanism was introduced to replace an earlier dependency on DIF Presentation Exchange for OpenID4VP requests.
• The EUDI Wallet Architecture and Reference Framework specifies OpenID4VP as the presentation protocol and, with it, DCQL as the query mechanism relying parties and wallets in the ecosystem are expected to support.
• Wallet and verifier reference implementations in the EUDI Wallet Reference Implementation program have converged on DCQL, so new business-wallet integrations built against OpenID4VP today should assume DCQL rather than Presentation Exchange as the query format for presentation requests.

Frequently asked questions

This page is informational and does not constitute legal advice. For authoritative guidance consult the OpenID Foundation and the European Commission directly.