Skip to main content

DCQL (Digital Credentials Query Language)

The dcql_query of a presentation configuration tells the wallet which credentials and claims to present. EUDIPLO uses the DCQL of OpenID4VP 1.0 and checks the response against the same query. Every field is listed in the presentation configuration reference.

Request a credential​

Each entry in credentials is one credential query. id, format, meta and trusted_authorities are required; meta identifies the credential type, trusted_authorities the issuers you accept (below). The examples on this page leave trusted_authorities out to focus on the other options.

{
"credentials": [
{
"id": "membership",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:membership:1"] },
"claims": [{ "path": ["name"] }, { "path": ["member_id"] }]
}
]
}

For mDOC, meta.doctype_value names the document type and each claim path is [namespace, element]:

{
"credentials": [
{
"id": "pid",
"format": "mso_mdoc",
"meta": { "doctype_value": "eu.europa.ec.eudi.pid.1" },
"claims": [
{ "path": ["eu.europa.ec.eudi.pid.1", "given_name"] },
{ "path": ["eu.europa.ec.eudi.pid.1", "family_name"] }
]
}
]
}
  • credentials needs at least one query. Query IDs use letters, digits, _ and - and are unique; results, credential_sets and transaction data refer to them. EUDIPLO rejects configurations that break these rules.
  • SD-JWT VC paths are property names, with numbers as array indexes (["address", "locality"], ["nationalities", 0]).
  • Without claim_sets, the presented credential must disclose every listed claim; otherwise the presentation fails.

Check a credential without requesting claims​

Leave out claims to only check that the user holds a valid credential of a type, for example a valid membership, without asking for any of its data:

{
"credentials": [
{
"id": "membership",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:membership:1"] }
}
]
}

The wallet then presents only what the credential always discloses: for SD-JWT VC the issuer-signed JWT with its claims that are not selectively disclosable, for mDOC no data elements. EUDIPLO checks signature, issuer trust, status and holder binding as usual. OpenID4VP does not allow an empty claims array, so leave the field out instead, and leave out claim_sets as well. In the Web Client, remove all claims of the credential (visual query builder).

This works for OpenID4VP requests; for ISO 18013-7 requests request at least one mDOC claim.

Accept specific values​

values lists the accepted values of a claim: strings, integers or booleans. It is sent to the wallet, which only offers matching credentials:

{ "path": ["membership_level"], "values": ["gold", "platinum"] }

In OpenID4VP flows EUDIPLO checks the presented value again, because a wallet may ignore the constraint. The disclosed value must equal one of the listed values in type and value: true does not match "true", and 18 does not match "18". Otherwise the presentation fails with the code claim_value_mismatch (failure codes). A yes/no check, such as an age check, therefore only completes with the expected answer:

{ "path": ["age_equal_or_over", "18"], "values": [true] }

With claim_sets, a set counts only if all its claims are disclosed with accepted values. If a path selects several array elements, one of them must match. mDOC values are compared by element name, like the presence check. ISO 18013-7 requests do not check values.

Alternative claims​

claim_sets lists alternative claim combinations by claim id. The credential must disclose every claim of at least one set; list the preferred set first. Each ID must match the id of a claim in the same query, otherwise the configuration is rejected:

{
"id": "pid",
"format": "mso_mdoc",
"meta": { "doctype_value": "eu.europa.ec.eudi.pid.1" },
"claims": [
{ "id": "over18", "path": ["eu.europa.ec.eudi.pid.1", "age_over_18"] },
{ "id": "birth_date", "path": ["eu.europa.ec.eudi.pid.1", "birth_date"] }
],
"claim_sets": [["over18"], ["birth_date"]]
}

Alternative credentials​

credential_sets combines credential queries by id. Each entry has options, a list of alternatives; every option lists queries that must be presented together. A set is required unless it has "required": false. Without credential_sets, every query in credentials is required.

This query accepts the PID either as SD-JWT VC or as mDOC, and optionally a membership credential:

{
"credentials": [
{
"id": "pid_sd_jwt",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:eudi:pid:1"] },
"claims": [{ "path": ["family_name"] }]
},
{
"id": "pid_mdoc",
"format": "mso_mdoc",
"meta": { "doctype_value": "eu.europa.ec.eudi.pid.1" },
"claims": [{ "path": ["eu.europa.ec.eudi.pid.1", "family_name"] }]
},
{
"id": "membership",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:membership:1"] },
"claims": [{ "path": ["member_id"] }]
}
],
"credential_sets": [
{ "options": [["pid_sd_jwt"], ["pid_mdoc"]] },
{ "options": [["membership"]], "required": false }
]
}

EUDIPLO rejects a response that does not satisfy one option of every required set. Your backend sees which queries were answered by the id of each entry in the result.

Several credentials of one type​

By default a query matches one credential, and a response with several presentations for the same query fails. Set "multiple": true to accept several, for example all employee badges in the wallet:

{
"id": "badges",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:employee-badge:1"] },
"multiple": true,
"claims": [{ "path": ["badge_id"] }]
}

Intent to retain (mDOC)​

For mso_mdoc claims, intent_to_retain: true tells the wallet and the user that you store the element after the presentation. It is sent in OpenID4VP requests; ISO 18013-7 requests always send false.

{ "path": ["eu.europa.ec.eudi.pid.1", "family_name"], "intent_to_retain": true }

Accept only trusted issuers​

Every credential query names the issuers it accepts in trusted_authorities, from a trust list or an OpenID Federation:

{
"trusted_authorities": [{ "type": "etsi_tl", "values": [{ "trustListId": "membership-issuers" }] }]
}

How trust lists are resolved, what the wallet receives (aki values) and how the issuer chain is checked is described in Trust Lists; federation trust anchors in OpenID Federation.

A presentation configuration with a credential query without trusted_authorities is rejected with 400, and a configuration stored before 9.0 without them fails verification. For development and interoperability tests, SKIP_TRUST_AUTHORITY=true allows such queries; EUDIPLO then verifies the signature but not who issued the credential. See Skip flags.