> For the complete documentation index, see [llms.txt](https://docs.empe.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.empe.io/develop/verifier/query-language.md). # Query Language When the Verifier creates an authorization request, it must describe exactly which credentials it will accept and which fields it needs from them. You express those requirements using one of two standard query forms — a **DCQL** (Digital Credentials Query Language) query or a **DIF Presentation Exchange v2** definition — supplied inline in the request body. The wallet uses your query to select matching credentials and, for SD-JWT credentials, to disclose only the requested claims. ## Key Concepts * **Query forms**: Credential requirements are expressed as either a `dcqlQuery` object or a `presentationDefinition` object. Both are standard formats, so wallets that follow the OpenID4VP specification understand them without any vendor-specific extensions. * **Where the query lives**: The query is not stored or referenced by ID — it is sent inline in the body of `POST /verifiers/:verifierId/authorization-requests` (and its `/qr-code` variant). Each request carries its own query. * **One form per request**: Supply exactly one of `dcqlQuery` or `presentationDefinition`. If you omit both, the request is rejected with `400 Bad Request` and the message `Either dcqlQuery or presentationDefinition must be provided.` Sending both passes the service's own input validation but fails downstream for every `version` value, surfacing as a `500`. * **Paths and filters** (Presentation Exchange): Inside a Presentation Exchange input descriptor, `constraints.fields` use JSONPath expressions in `path` to locate a value in the credential, and an optional JSON Schema (Draft 7) `filter` to validate it (for example `type`, `enum`, `pattern`, or `contains`). * **Selective disclosure**: For SD-JWT VC credentials, the claims your query asks for are the claims the wallet selectively discloses. Fields the credential supports but the query does not request stay hidden, so the holder shares only what the Verifier needs. ## DCQL Example DCQL is a compact, credential-centric query format. The following query requests an `EmployeeBadge` SD-JWT VC and asks the wallet to disclose only the `employee_id` and `department` claims: ```json { "responseMode": "direct_post.jwt", "version": "v1", "dcqlQuery": { "credentials": [ { "id": "employee_badge", "format": "dc+sd-jwt", "meta": { "vct_values": ["https://issuer.example.com/vct/employee-badge"] }, "claims": [ { "path": ["employee_id"] }, { "path": ["department"] } ] } ] } } ``` * `format` is the requested credential format (for example `dc+sd-jwt` for SD-JWT VC). * `meta.vct_values` restricts the request to credentials with a matching `vct` (verifiable credential type). * Each entry in `claims` names a claim with a `path`, and those are the claims the wallet discloses. ## Presentation Exchange Example A DIF Presentation Exchange v2 definition is more verbose but lets you attach JSON Schema filters to individual fields. `presentationDefinition` requires `version` `v1.draft21` or `v1.draft24` (the default `v1` supports only `dcqlQuery`). The following definition requests a credential whose `type` array contains `EmploymentCredential` and whose subject is identified by a `did:web` identifier: ```json { "responseMode": "direct_post.jwt", "version": "v1.draft24", "presentationDefinition": { "id": "pd-employment", "input_descriptors": [ { "id": "employment_vc", "format": { "jwt_vc_json": { "alg": ["EdDSA"] } }, "constraints": { "fields": [ { "path": ["$.type"], "filter": { "type": "array", "contains": { "const": "EmploymentCredential" } } }, { "path": ["$.credentialSubject.id"], "filter": { "type": "string", "pattern": "^did:web:.*$" } } ] } } ] } } ``` * `path` holds one or more JSONPath expressions; the first one that resolves is used. * `filter` is a JSON Schema (Draft 7) the extracted value must satisfy. Use a method-agnostic pattern (for example `^did:.*$`) when you do not need to constrain the DID method. ## Response A successful request returns the authorization request URI and the verification session you can poll or stream for results: ```json { "authorizationRequestUri": "openid4vp://?request_uri=...", "verificationSessionId": "18b760b1-4ab8-4d38-9d42-6b4c25a4d2e0", "authorizationRequestId": "1b8a6a8b-2ac1-4f0b-9d9c-6b9c859b1af2", "expiresAt": "2024-08-09T12:34:56.789Z" } ``` Pick whichever form fits your stack — both let you constrain credential types, claims, and field values. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.empe.io/develop/verifier/query-language.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.