OpenID4VP DCQL

A Dart library for building and validating Digital Credentials Query Language (DCQL) queries as defined in the OpenID for Verifiable Presentations (OpenID4VP) v1.0 specification.

Build complex credential queries with a fluent, type-safe API, validate them against the spec, and serialize them to JSON for transmission.

Package version to Spec

List of package versions and what specs they support

version	Spec
v1.0.0	v1.0

Why

• Fluent Builder API: Construct complex nested queries with readable, chainable methods.
• Type Safety: Compile-time checks for known credential types (mdoc, sd-jwt) and claims.
• Spec Compliance: Built-in validation ensures your queries meet the DCQL specification requirements.
• Zero Boilerplate: No need to manually construct deeply nested Maps or JSON objects.

What

This library focuses exclusively on the Digital Credentials Query Language (DCQL) part of the OpenID4VP specification.

It does not handle

• Cryptographic operations (signing, encryption, or verification of credentials).
• PKI or Key Management.
• Transport protocols (OID4VP request/response handling).

It is designed to be used within a larger OpenID4VP implementation or by a Verifier application that needs to construct queries.

Install

dart pub add openid4vp_dcql

Core Example

import 'dart:convert';
import 'package:openid4vp_dcql/openid4vp_dcql.dart';

void main() {
  final query = DcqlBuilder()
      // Request an mDoc Driving License
      .credential('credential-1', type: CredentialType.mdocDl)
          .claim(Claims.mdocDl.firstName, id: 'first_name')
          .claim(Claims.mdocDl.documentNumber, id: 'doc_number')
          // Define combinations of claims that satisfy the requirement
          .claimSet(["first_name", "doc_number"])
      
      // Request an SD-JWT PID
      .credential('credential-2', type: CredentialType.sdJwtPid)
          .claim(Claims.sdJwtPid.documentNumber)
      
      // Define logic between credentials (e.g., Credential 1 OR Credential 2)
      .credentialSet()
          .option(['credential-1'])
          .option(['credential-2'])
      
      .build();

  // Validate the query structure
  final validation = DcqlValidator().validate(query);
  if (validation.isValid) {
    print(jsonEncode(query.toJson()));
  } else {
    print('Invalid query: ${validation.errors}');
  }
}

Manual Construction

You can also construct the query object directly without using the builder. However, you will lose some conveniences, such as automatic path prefixing (namespaces) for claims.

import 'dart:convert';
import 'package:openid4vp_dcql/openid4vp_dcql.dart';

void main() {
  final query = DcqlQuery(
    credentials: [
      Credential(
        id: 'credential-1',
        format: Formats.mso_mdoc,
        meta: Meta(meta: {'doctype_value': 'org.iso.18013.5.1.mDL'}),
        claims: [
          Claim(id: 'first_name', path: ['org.iso.18013.5.1', 'first_name']),
          Claim(id: 'doc_number', path: ['org.iso.18013.5.1', 'document_number']),
        ],
        claimSets: [
          ['first_name', 'doc_number']
        ],
      ),
      Credential(
        id: 'credential-2',
        format: Formats.sd_jwt,
        meta: Meta(meta: {'vcts_values': ['urn:eu.europa.ec.eudi.pid.1']}),
        claims: [
          Claim(path: ['document_number']),
        ],
      ),
    ],
    credentialSets: [
      CredentialSet(
        options: [
          ['credential-1'],
          ['credential-2'],
        ],
      ),
    ],
  );

  // Validate the query structure
  final validation = DcqlValidator().validate(query);
  if (validation.isValid) {
    print(jsonEncode(query.toJson()));
  } else {
    print('Invalid query: ${validation.errors}');
  }
}

Features

Fluent Builder

The DcqlBuilder allows you to chain methods to define credentials, claims, and sets naturally.

Validation

The library includes a robust validator that checks for:

• Unique IDs for credentials and claims.
• Valid references in claim_sets and credential_sets.
• Correct value types and non-empty paths.

Supported Formats

• mso_mdoc (Mobile Driving License, etc.)
• dc+sd-jwt (SD-JWT VC)
• jwt_vc_json (W3C Verifiable Credentials)

Contributing

Open an issue for discussion, then PR with tests.

License

MIT