Credential Queries

Credential Queries are the fundamental building blocks of DCQL requests. Each credential query specifies requirements for a single type of credential that the verifier needs from the holder’s wallet. These queries define what credential format is required, which issuer should have issued it, and optionally what specific data fields (claims) are needed from within that credential.

What is a credential query?

A credential query is a JSON object that describes one credential request. When a verifier needs to verify someone’s identity, education, employment, or any other attribute, they create a credential query for each type of credential they want to receive.

For example, if a verifier needs to see a university degree credential, they create a credential query specifying that format, potentially restricting it to credentials from trusted universities, and optionally requesting only specific fields like the degree type and graduation date rather than the entire credential.

Core structure

Every credential query must include three required fields:

id: A unique string identifier for this query within the DCQL request. This ID is used to reference the credential in credential sets and in the wallet’s response. It should be descriptive (like “university_degree” or “photo_id”) to make queries readable.

format: Specifies the credential format that must be used. Common formats include mso_mdoc (ISO mobile driving license format), dc+sd-jwt (Selective Disclosure JWT), jwt_vc_json (JWT-based Verifiable Credential), and others. This ensures the wallet returns credentials in the expected format.

meta: An object containing format-specific metadata constraints. For mso_mdoc credentials, this includes doctype_value to specify the document type. For dc+sd-jwt credentials, this includes vct_values (verifiable credential type values) to specify the credential schema. An empty object {} means no specific metadata constraints.

Optional fields

Credential queries support several optional fields for more precise requirements:

multiple: A boolean indicating whether the wallet can return multiple credentials matching this single query. Defaults to false. When set to true, useful for scenarios like requesting multiple bank statements or transaction records.

claims: An array of claim query objects specifying individual data fields requested from the credential. If omitted, the verifier accepts the entire credential without selective disclosure.

claim_sets: An array defining acceptable combinations of the claims specified in the claims array. This enables expressing alternatives and preferences for which claims to share.

trusted_authorities: An array of objects specifying which credential issuers are acceptable. This helps wallets filter credentials before presenting them to the user, improving privacy.

require_cryptographic_holder_binding: A boolean indicating whether the verifier requires proof that the credential holder is the same entity presenting the credential. Defaults to true for security.

Format specification

The format field is critical for interoperability. It tells the wallet exactly what credential format to return. Each format has specific characteristics:

mso_mdoc: ISO 18013-5 mobile document format, commonly used for mobile driver’s licenses and identity documents. Supports selective disclosure at the attribute level.

dc+sd-jwt: SD-JWT-based Verifiable Credentials with selective disclosure capabilities. Claims can be selectively revealed using SD-JWT disclosure mechanisms.

jwt_vc_json: JSON Web Token-based Verifiable Credentials following W3C VC data model. Entire credential is typically shared.

ldp_vc: Linked Data Proof-based Verifiable Credentials using JSON-LD. Supports various cryptographic suites.

Meta object and constraints

The meta object provides format-specific filtering. For mso_mdoc credentials:

"meta": {
  "doctype_value": "org.iso.18013.5.1.mDL"
}

This restricts the query to mobile driver’s license documents specifically.

For dc+sd-jwt credentials:

"meta": {
  "vct_values": [
    "https://credentials.example.edu/university_degree"
  ]
}

This ensures only credentials with the specified verifiable credential type are matched.

Selective disclosure support

Credential queries enable selective disclosure through the claims and claim_sets fields. Instead of requesting entire credentials, verifiers can specify exactly which fields they need. The wallet then uses format-specific selective disclosure mechanisms to reveal only those fields.

This is fundamental to privacy preservation. For example, when verifying age, a verifier can request an age_over_18 boolean claim rather than the full birth date. The credential query structure makes this privacy-preserving pattern explicit and standardized.

Multiple credentials

The multiple field addresses scenarios where multiple instances of the same credential type are needed. Setting "multiple": true allows the wallet to return several credentials matching the query.

Use cases include:

Requesting last six months of bank statements
Collecting multiple transaction receipts
Gathering attendance records from different events

Without this flag, the wallet returns at most one credential per query. With it enabled, the wallet can provide all matching credentials, and the holder chooses how many to share.

Cryptographic holder binding

The require_cryptographic_holder_binding field ensures the credential presenter is the credential subject. When true (the default), the wallet must provide cryptographic proof linking the credential to the presenter’s identity.

This prevents credential theft and unauthorized presentation. The specific binding mechanism depends on the credential format (key binding for SD-JWT, device authentication for mDL, etc.).

Example: university degree query

A basic credential query requesting a university degree:

{
    "id": "university_degree",
    "format": "dc+sd-jwt",
    "meta": {
        "vct_values": ["https://credentials.example.edu/degree"]
    },
    "require_cryptographic_holder_binding": true
}

This query:

Identifies itself as “university_degree”
Requires SD-JWT format credentials
Restricts to credentials with the specified type
Requires proof the presenter is the degree holder
Accepts the entire credential (no claims specified)

Example: photo ID with trusted issuer

A credential query requesting government-issued photo ID from trusted authorities:

{
    "id": "photo_id",
    "format": "mso_mdoc",
    "meta": {
        "doctype_value": "org.iso.18013.5.1.mDL"
    },
    "trusted_authorities": [
        {
            "type": "etsi_tl",
            "values": ["https://example.gov/trust-list.xml"]
        }
    ]
}

This query adds issuer trust requirements, ensuring only credentials from authorities in the specified trust list are accepted.

Role in Vidos

In Vidos, the Authorizer service generates credential queries based on authorization policies. When a policy requires specific credentials, it’s translated into credential query format. The Validator service then checks that presentations contain credentials matching these queries.

Credential queries form the foundation of Vidos’ DCQL support, enabling precise, privacy-preserving credential requests that align with policy requirements.

Summary

Credential queries are the building blocks of DCQL, specifying individual credential requirements with format constraints, metadata filters, selective disclosure options, and trust requirements. They provide a clear, standardized way to request credentials while preserving holder privacy through selective disclosure and trusted issuer filtering.