# @verifiables/request-converter

> Convert DIF Presentation Exchange Presentation Definitions and DCQL queries to ISO 18013-5 mDoc DeviceRequest structures

Latest version **0.2.0** (published 2026-03-24) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @verifiables/request-converter
pnpm add @verifiables/request-converter
yarn add @verifiables/request-converter
bun add @verifiables/request-converter
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2026-03-24 |
| First published | 2025-11-27 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 0 |
| Unpacked size | 97.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Verifiables |
| Maintainers | marsouin |
| Keywords | presentation-definition, dcql, digital-credentials-query-language, mdoc, iso-18013-5, mdl, mobile-driver-license, verifiable-credentials, digital-identity, dif, presentation-exchange, eudi-wallet, openid4vp, oid4vp |

## Links

- npm: https://www.npmjs.com/package/@verifiables/request-converter
- Repository: https://github.com/verifiablestech/request-converter
- Homepage: https://github.com/verifiablestech/request-converter#readme
- Issues: https://github.com/verifiablestech/request-converter/issues
- npm.io page: https://npm.io/package/@verifiables/request-converter

## 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

- 0.2.0 (latest) — 2026-03-24
- 0.1.1 — 2025-11-27
- 0.1.0 — 2025-11-27

## README

# Presentation Definition & DCQL to mDoc DeviceRequest Converter

A TypeScript library for converting [DIF Presentation Exchange](https://identity.foundation/presentation-exchange/) Presentation Definitions and [DCQL (Digital Credentials Query Language)](https://openid.net/specs/openid-4-verifiable-presentations-1_0-24.html#section-6) queries to [ISO 18013-5](https://www.iso.org/standard/69084.html) mDoc DeviceRequest structures.

## Overview

This library bridges important standards in the digital identity space:

- **DIF Presentation Exchange v2.x**: A specification that defines how Verifiers can express proof requirements and how Holders can describe proof submissions.
- **DCQL (Digital Credentials Query Language)**: The new query language defined in OpenID4VP for requesting verifiable credentials in a more flexible way.
- **ISO 18013-5 (mDL)**: The international standard for mobile driver's licenses, which defines the DeviceRequest structure for requesting credential data.

The converter is particularly useful for:
- OpenID4VP implementations that use Presentation Exchange or DCQL with mDoc credentials
- EUDI Wallet ecosystem implementations
- Any system bridging W3C/DIF/OpenID standards with ISO 18013-5 mDoc credentials

## Installation

```bash
npm install @verifiables/request-converter
```

Or with your preferred package manager:

```bash
yarn add @verifiables/request-converter
pnpm add @verifiables/request-converter
```

## Quick Start

### DCQL Query Conversion

```typescript
import { convertDcqlQueryToDeviceRequest } from '@verifiables/request-converter';

// DCQL query (as used in OpenID4VP)
const dcqlQuery = {
  credentials: [{
    id: 'my_mdl',
    format: 'mso_mdoc',
    meta: { doctype_value: 'org.iso.18013.5.1.mDL' },
    claims: [
      { path: ['org.iso.18013.5.1', 'family_name'], intent_to_retain: false },
      { path: ['org.iso.18013.5.1', 'given_name'], intent_to_retain: false },
    ]
  }]
};

const result = convertDcqlQueryToDeviceRequest(dcqlQuery);
console.log(result.deviceRequest);
// {
//   version: "1.0",
//   docRequests: [{
//     itemsRequest: {
//       docType: "org.iso.18013.5.1.mDL",
//       nameSpaces: {
//         "org.iso.18013.5.1": {
//           family_name: false,
//           given_name: false
//         }
//       }
//     }
//   }]
// }
```

### Presentation Definition Conversion

```typescript
import { convertPresentationDefinitionToDeviceRequest } from '@verifiables/request-converter';

const presentationDefinition = {
  id: "mDL-request",
  input_descriptors: [{
    id: "org.iso.18013.5.1.mDL",
    format: { mso_mdoc: { alg: ["ES256"] } },
    constraints: {
      limit_disclosure: "required",
      fields: [
        { path: ["$['org.iso.18013.5.1']['family_name']"], intent_to_retain: false },
        { path: ["$['org.iso.18013.5.1']['given_name']"], intent_to_retain: false }
      ]
    }
  }]
};

const result = convertPresentationDefinitionToDeviceRequest(presentationDefinition);
```

### Auto-detect Input Type

```typescript
import { convertToDeviceRequest } from '@verifiables/request-converter';

// Works with both DCQL and Presentation Definition
const result = convertToDeviceRequest(input); // Auto-detects input type
```

## API Reference

### DCQL Conversion

#### `convertDcqlQueryToDeviceRequest(dcqlQuery, options?)`

Converts a DCQL query to a DeviceRequest.

**Parameters:**

- `dcqlQuery`: The DCQL query object with `credentials` array
- `options` (optional): Conversion options
  - `version`: DeviceRequest version string (default: `"1.0"`)
  - `defaultIntentToRetain`: Default intent_to_retain value if not specified (default: `false`)
  - `mdocOnly`: Only process mso_mdoc format credentials (default: `true`)
  - `validate`: Whether to validate input (default: `true`)

### Presentation Definition Conversion

#### `convertPresentationDefinitionToDeviceRequest(presentationDefinition, options?)`

Converts a Presentation Definition to a DeviceRequest.

**Parameters:**

- `presentationDefinition`: The DIF Presentation Exchange Presentation Definition
- `options` (optional): Conversion options (same as above)

### Unified Conversion

#### `convertToDeviceRequest(input, options?)`

Auto-detects input type and converts to DeviceRequest.

### Utility Functions

#### `createDeviceRequest(docType, elements, version?)`

Creates a DeviceRequest directly from docType and elements.

```typescript
const deviceRequest = createDeviceRequest(
  'org.iso.18013.5.1.mDL',
  [
    { namespace: 'org.iso.18013.5.1', element: 'family_name', intentToRetain: false },
    { namespace: 'org.iso.18013.5.1', element: 'given_name', intentToRetain: false },
  ]
);
```

#### `createDcqlQueryFromDeviceRequest(deviceRequest, options?)`

Reverse conversion: creates a DCQL query from a DeviceRequest.

```typescript
const dcqlQuery = createDcqlQueryFromDeviceRequest(deviceRequest);
```

#### `createPresentationDefinitionFromDeviceRequest(deviceRequest, options?)`

Reverse conversion: creates a Presentation Definition from a DeviceRequest.

### Interoperability Functions

#### `convertDcqlCredentialQueryToInputDescriptor(credentialQuery)`

Converts a single DCQL credential query to a Presentation Definition input descriptor.

#### `convertInputDescriptorToDcqlCredentialQuery(inputDescriptor)`

Converts a Presentation Definition input descriptor to a DCQL credential query.

### Validation

#### `validateDeviceRequest(deviceRequest)`

Validates a DeviceRequest structure.

```typescript
const { valid, errors } = validateDeviceRequest(deviceRequest);
```

## DCQL Path Format

For mDoc credentials, DCQL uses a simple path format:

```typescript
claims: [
  { path: ['namespace', 'element'], intent_to_retain: boolean }
]
```

Examples:
- `['org.iso.18013.5.1', 'family_name']`
- `['eu.europa.ec.eudi.pid.1', 'birth_date']`
- `['org.iso.7367.1', 'vehicle_holder']`

## Presentation Definition Path Format

Presentation Definitions use JSONPath-style expressions:

```
$['namespace']['element']
```

Examples:
- `$['org.iso.18013.5.1']['family_name']`
- `$['eu.europa.ec.eudi.pid.1']['nationality']`

## Supported Document Types

The converter recognizes common mDoc document types:

| Document Type | Default Namespace |
|--------------|-------------------|
| `org.iso.18013.5.1.mDL` | `org.iso.18013.5.1` |
| `eu.europa.ec.eudi.pid.1` | `eu.europa.ec.eudi.pid.1` |
| `org.iso.7367.1.mVRC` | `org.iso.7367.1` |

## Examples

### DCQL: Multiple Credentials

```typescript
const dcqlQuery = {
  credentials: [
    {
      id: 'pid',
      format: 'mso_mdoc',
      meta: { doctype_value: 'eu.europa.ec.eudi.pid.1' },
      claims: [
        { path: ['eu.europa.ec.eudi.pid.1', 'family_name'] },
        { path: ['eu.europa.ec.eudi.pid.1', 'age_over_18'] },
      ]
    },
    {
      id: 'mdl',
      format: 'mso_mdoc',
      meta: { doctype_value: 'org.iso.18013.5.1.mDL' },
      claims: [
        { path: ['org.iso.18013.5.1', 'driving_privileges'] },
      ]
    }
  ],
  credential_sets: [
    { options: [['pid'], ['pid', 'mdl']], required: true }
  ]
};

const result = convertDcqlQueryToDeviceRequest(dcqlQuery);
// Result contains two docRequests, one for PID and one for mDL
```

### KYC with Data Retention

```typescript
const kycQuery = {
  credentials: [{
    id: 'kyc',
    format: 'mso_mdoc',
    meta: { doctype_value: 'org.iso.18013.5.1.mDL' },
    claims: [
      { path: ['org.iso.18013.5.1', 'family_name'], intent_to_retain: true },
      { path: ['org.iso.18013.5.1', 'document_number'], intent_to_retain: true },
      { path: ['org.iso.18013.5.1', 'portrait'], intent_to_retain: false }, // Only verify
    ]
  }]
};
```

## Type Definitions

The library exports comprehensive TypeScript types:

```typescript
import type {
  // DCQL types
  DcqlQuery,
  DcqlCredentialQuery,
  DcqlCredentialMeta,
  DcqlClaimQuery,
  DcqlClaimSetQuery,
  DcqlCredentialSetQuery,

  // Presentation Definition types
  PresentationDefinition,
  InputDescriptor,
  Constraints,
  Field,

  // DeviceRequest types
  DeviceRequest,
  DocRequest,
  ItemsRequest,
  NameSpaces,
  DataElements,

  // Conversion types
  ConversionResult,
  ConversionOptions,
  DcqlConversionOptions,
} from '@verifiables/request-converter';
```

## Integration with Other Libraries

### With @animo-id/mdoc

The DeviceRequest output is designed to work directly with [@animo-id/mdoc](https://github.com/animo/mdoc)'s holder functions:

```typescript
import { 
  createDeviceResponseForDeviceRequest,
  DataItem
} from '@animo-id/mdoc';
import { 
  convertDcqlQueryToDeviceRequest,
} from '@verifiables/request-converter';


// Convert DCQL query (from OID4VP authorization request) to DeviceRequest
const dcqlQuery = {
  credentials: [{
    id: 'mdl',
    format: 'mso_mdoc',
    meta: { doctype_value: 'org.iso.18013.5.1.mDL' },
    claims: [
      { path: ['org.iso.18013.5.1', 'family_name'], intent_to_retain: false },
      { path: ['org.iso.18013.5.1', 'portrait'], intent_to_retain: false },
    ]
  }]
};

const { deviceRequest } = convertDcqlQueryToDeviceRequest(dcqlQuery);

deviceRequest.docRequests = deviceRequest.docRequests.map((docRequest: any) => {
  docRequest.itemsRequest = DataItem.fromData(docRequest.itemsRequest)
  return docRequest
})

// Use the DeviceRequest directly with @animo-id/mdoc holder
const deviceResponse = await createDeviceResponseForDeviceRequest({
  deviceRequest,
  sessionTranscript, // SessionTranscript bytes,
  issuerSigned, // issuerSigned from mDoc,
  signature, // a signature object including a CoseKey signingKey
}, context); // the mdoc context

// deviceResponse is ready to send back to the verifier
```

### With dcql-ts

```typescript
import { DcqlQuery } from 'dcql';
import { convertDcqlQueryToDeviceRequest } from '@verifiables/request-converter';

// Parse and validate DCQL query using dcql-ts
const parsedQuery = DcqlQuery.parse(rawQuery);
DcqlQuery.validate(parsedQuery);

// Convert to DeviceRequest
const { deviceRequest } = convertDcqlQueryToDeviceRequest(parsedQuery);
```

## Why Proper intent_to_retain Handling Matters

The `intent_to_retain` field is crucial for privacy compliance (GDPR, etc.):

- **`false`**: Data is only verified in real-time, not stored
- **`true`**: Verifier intends to retain the data

This library properly extracts `intent_to_retain` from DCQL claims, unlike simplistic implementations that hardcode it to `false`.

## Related Standards

- [DCQL (OpenID4VP)](https://openid.net/specs/openid-4-verifiable-presentations-1_0-24.html#section-6)
- [DIF Presentation Exchange v2.x](https://identity.foundation/presentation-exchange/)
- [ISO 18013-5:2021](https://www.iso.org/standard/69084.html) - Mobile driving licence (mDL) application
- [ISO 18013-7](https://www.iso.org/standard/82772.html) - Mobile driving licence add-on functions
- [dcql-ts](https://github.com/openwallet-foundation-labs/dcql-ts) - DCQL TypeScript implementation

## License

Apache-2.0

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

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