Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

DCQL queries

The Digital Credentials Query Language (DCQL) is defined in Section 6 of the OpenID4VP 1.0 specification. A relying party uses DCQL to state which credentials and which claims it requires from a wallet. The credential verifier evaluates the query against the presentations that the wallet returns.

A DCQL query is a JSON object. The query travels in the dcql_query parameter of an authorization request. For the surrounding request parameters, see OpenID4VP authorization request parameters.

Query structure

A query holds one or more credential queries. The fields below belong to two nested objects. A credential query holds id, format, meta, claims, and the optional claim_sets. A claim query holds path, values, and the optional id and intent_to_retain.

FieldRequiredDescription
credentialsYesThe list of credential queries.
credential_setsNoGroups of alternative credential queries. The wallet satisfies the query when it can satisfy one complete option.
idYesThe identifier of one credential query. The authorization response uses this identifier as a key.
formatYesThe credential format. Age verification uses mso_mdoc, which means an ISO mobile document such as a mobile driving licence or a proof of age.
metaYes for mso_mdocFormat-specific metadata. An mso_mdoc query names the document type in doctype_value.
claimsYesThe claims to request from the credential.
claim_setsNoAlternative combinations of claims. A claim query needs an id only when a claim_sets entry references it.
pathYesThe location of one claim. The first element is the namespace and the second element is the claim name.
valuesNoThe permitted values for a claim. The wallet returns the claim only when its value appears in this list.
intent_to_retainNoWhether the relying party intends to keep the claim. The field is omitted in this system, which is equivalent to false, the safe default.

Namespaces

A claim path starts with the namespace of the credential. Age verification uses two namespaces.

NamespaceDescriptionDocument type
eu.europa.ec.av.1The EU Age Verification namespace (proof of age).eu.europa.ec.av.1
org.iso.18013.5.1The ISO mobile driving licence namespace.org.iso.18013.5.1.mDL

Age verification query examples

Minimal age over 18

The simplest age verification request asks only for age_over_18 from a proof of age.

{
  "credentials": [
    {
      "id": "proof_of_age",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_18"]
        }
      ]
    }
  ]
}

Age over 21

For a jurisdiction that requires age 21 or older, request age_over_21 instead.

{
  "credentials": [
    {
      "id": "proof_of_age",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_21"]
        }
      ]
    }
  ]
}

Value matching

Add a values list to accept the claim only when its value matches. The example below accepts the presentation only when age_over_18 is true.

{
  "credentials": [
    {
      "id": "proof_of_age",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_18"],
          "values": [true]
        }
      ]
    }
  ]
}

mDL fallback

If the user holds a mobile driving licence instead of a proof of age, request the same claim from the ISO mobile driving licence namespace.

{
  "credentials": [
    {
      "id": "age_from_mdl",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "org.iso.18013.5.1.mDL"
      },
      "claims": [
        {
          "path": ["org.iso.18013.5.1", "age_over_18"]
        }
      ]
    }
  ]
}

Multiple credential options

A credential_sets list lets the wallet choose between alternatives. Each option is an array of credential identifiers, and the wallet satisfies the set when it can satisfy one complete option. The example below accepts a proof of age or a mobile driving licence.

{
  "credentials": [
    {
      "id": "eu_age_proof",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_18"]
        }
      ]
    },
    {
      "id": "mdl_age_proof",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "org.iso.18013.5.1.mDL"
      },
      "claims": [
        {
          "path": ["org.iso.18013.5.1", "age_over_18"]
        }
      ]
    }
  ],
  "credential_sets": [
    {
      "options": [["eu_age_proof"], ["mdl_age_proof"]]
    }
  ]
}

The vp_token response

The wallet returns the presentation in the vp_token parameter. With a DCQL query, the token is a JSON object whose keys are the credential identifiers from the query. Each value is an array of presentations.

{
  "proof_of_age": ["base64url encoded DeviceResponse"]
}

An mso_mdoc presentation is a CBOR-encoded device response as defined in ISO/IEC 18013-5. The wallet does not send a presentation_submission field with a DCQL query.