# dcql

> Digital Credentials Query Language (DCQL)

Latest version **3.0.1** (published 2026-09-16) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install dcql
pnpm add dcql
yarn add dcql
bun add dcql
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2026-09-16 |
| First published | 2024-10-25 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 1.3 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 30 |
| Author | Martin Auer |
| Maintainers | timoglastra, openwalletfoundation, ausweis |
| Keywords | Digital Credentials Query Language (DCQL), Credentials Query Language, Verifiable Presentation Query Language, Verifiable Presentations, Presentation Definition, Credentials, SSI, OpenID, SIOP, Self Issued OpenId Provider, OpenId for Verifiable Presentations, SIOPv2, OID4VC, OID4VP, OpenID4VP, OpenID4VC, OIDC4VP |

## Links

- npm: https://www.npmjs.com/package/dcql
- Repository: https://github.com/openwallet-foundation-labs/identity-common-ts
- Homepage: https://github.com/openwallet-foundation-labs/identity-common-ts/tree/main/packages/dcql
- Issues: https://github.com/openwallet-foundation-labs/identity-common-ts/issues
- npm.io page: https://npm.io/package/dcql

## Dependencies (1)

- [valibot](https://npm.io/package/valibot.md) ^1.4.2

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 3.0.1 (latest) — 2026-09-16
- 4.0.0-alpha-20260922110620 (alpha) — 2026-09-22
- 4.0.0-alpha-20260921121727 — 2026-09-21
- 4.0.0-alpha-20260920163617 — 2026-09-20
- 4.0.0-alpha-20260920143658 — 2026-09-20
- 4.0.0-alpha-20260920133054 — 2026-09-20
- 4.0.0-alpha-20260919211014 — 2026-09-19
- 4.0.0-alpha-20260919112629 — 2026-09-19
- 4.0.0-alpha-20260919100859 — 2026-09-19
- 4.0.0-alpha-20260919094428 — 2026-09-19
- 4.0.0-alpha-20260918081040 — 2026-09-18
- 3.1.0-alpha-20260918080827 — 2026-09-18
- 3.1.0-alpha-20260917172451 — 2026-09-17
- 3.1.0-alpha-20260917125442 — 2026-09-17
- 3.0.2-alpha-20260917111104 — 2026-09-17
- … 98 more at https://npm.io/package/dcql/versions

## README

# dcql

[![npm version](https://img.shields.io/npm/v/dcql)](https://npmjs.com/package/dcql)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/LICENSE)

A TypeScript implementation of the Digital Credentials Query Language (DCQL, pronounced [ˈdakl̩]) - a JSON-encoded query language for requesting and validating Verifiable Presentations.

This package was previously developed in the [dcql-ts](https://github.com/openwallet-foundation-labs/dcql-ts) repository. It is versioned separately from the other packages in this repository.

## Overview

DCQL enables Verifiers to request Verifiable Presentations that match specific queries. The library provides functionality to:

- Create and validate DCQL queries
- Match queries against Verifiable Credentials
- Validate presentation results
- Handle various credential formats including mso_mdoc, dc+sd-jwt and w3c vc's.
- Create and parse DCQL queries from OID4VP Draft 22 up to version 1.0.

## Installation

```bash
npm install dcql
# or
yarn add dcql
# or
pnpm add dcql
```

## Quick Start

```typescript
import { DcqlQuery, type DcqlCredential } from 'dcql'

const credentials = [
  {
    credential_format: 'mso_mdoc',
    doctype: 'org.iso.7367.1.mVRC',
    cryptographic_holder_binding: true,
    namespaces: {
      'org.iso.7367.1': {
        vehicle_holder: 'John Doe',
      },
      'org.iso.18013.5.1': {
        first_name: 'John',
      },
    },
    authority: {
      type: 'aki',
      values: ['21cbb5a0-9d1e-46dc-b8aa-0e85036af442'],
    },
  },
] satisfies DcqlCredential[]

// Create a DCQL query
const query = {
  credentials: [
    {
      id: 'my_credential',
      format: 'mso_mdoc',
      meta: { doctype_value: 'org.iso.7367.1.mVRC' },
      claims: [
        {
          path: ['org.iso.7367.1', 'vehicle_holder'],
          intent_to_retain: true,
        },
        {
          path: ['org.iso.18013.5.1', 'first_name'],
        },
      ],
    },
  ],
} satisfies DcqlQuery.Input

// Parse (structural) and validate (content) the query
const parsedQuery = DcqlQuery.parse(query)
DcqlQuery.validate(parsedQuery)

// Execute the query against credentials
const queryResult = DcqlQuery.query(parsedQuery, credentials)
```

## Features

- **Query Construction**: Build structured DCQL queries with type safety
- **Validation**: Comprehensive query validation and parsing
- **Credential Matching**: Match credentials against query requirements
- **Result Processing**: Process and validate presentation results
- **Type Safety**: Full TypeScript support with detailed type definitions
- **Format Support**: Support for multiple credential formats
- **Extensible**: Easy to extend for custom credential formats

## Query Result Structure

The query result provides detailed information about the match:

```typescript
// Execute the query against credentials
const queryResult = DcqlQuery.query(parsedQuery, credentials)

// Check if query can be satisfied
console.log(queryResult.can_be_satisfied)

// Access matched credentials
console.log(queryResult.credential_matches)

// The result of a specific credential query
const credentialMatch = queryResult.credential_matches.credential_query_id
console.log(credentialMatch.success) // True if the query is fulfillable
```

## Validating Presentations

Validate presentation results against queries:

```ts
const presentationQueryResult = DcqlPresentationResult.fromDcqlPresentation(
  {
    my_credential: [
      {
        credential_format: 'mso_mdoc',
        doctype: 'org.iso.7367.1.mVRC',
        namespaces: {
          'org.iso.7367.1': { vehicle_holder: 'Martin Auer' },
          'org.iso.18013.5.1': { first_name: 'Martin Auer' },
        },
        cryptographic_holder_binding: true,
      },
    ],
  },
  { dcqlQuery: parsedQuery }
)
```

## Dependencies

- [valibot](https://www.npmjs.com/package/valibot)

## Platform Support

This library is **platform agnostic** and works in:

- ✅ Node.js (>=22)
- ✅ Browsers (modern browsers with ES2020 support)
- ✅ React Native

## Contributing

See the [Contributing Guide](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/CONTRIBUTING.md) for details on how to contribute to this project.

## License

This project is licensed under the [Apache License Version 2.0](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/LICENSE) (Apache-2.0).

## Credits

This library was initially created by [Martin Auer](https://github.com/auer-martin) for [Animo](https://github.com/animo) as part of the [SPRIN-D EUDI Wallet Prototypes Funke](https://www.sprind.org/en/impulses/challenges/eudi-wallet-prototypes).

---
_Source: https://npm.io/package/dcql · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._