Skip to main content
Version: v0.25.0 (Latest)

DCQL Authoring

A DCQL query tells a wallet which credentials and claims a verifier needs. The EDK can derive that query from one or more published verifiable-credential channels. Each channel already binds a version-pinned data product to a credential format, credential-type identity, and claim mappings, so the verifier does not have to reproduce those decisions by hand.

The same projection supports two REST operations:

OperationEndpointResult
PreviewPOST /api/dcql/v1/queries/previewReturns the derived query, provenance, and warnings without writing to the DCQL store
AuthorPOST /api/dcql/v1/queries/authoredPersists the derived query as a versioned configuration and records REQUEST-role usage lineage

Both operations require the semantic-modeling.v1 feature. They resolve the tenant from the authenticated session and never accept a tenant identifier in the request body.

Conversion contract​

The converter accepts version-pinned channel references. Every referenced channel contributes one credential query to the resulting DcqlQuery.

interface ChannelToDcqlConverter {
    suspend fun convert(
        request: DefinitionToDcqlConversionRequest,
    ): IdkResult<DcqlFromChannelResult, IdkError>
}

data class DefinitionToDcqlConversionRequest(
    val channelRefs: List<ChannelRef>,
    val useCredentialSets: Boolean = false,
)

data class ChannelRef(
    val channelId: Uuid,
    val channelVersion: Long,
)

channelRefs must contain at least one verifiable-credential channel. channelVersion starts at 1 and pins the exact published channel snapshot used for the projection. When useCredentialSets is true, the converter wraps the emitted credential-query identifiers in one required DCQL credential set.

The result contains the query and enough provenance to explain each generated credential query:

data class DcqlFromChannelResult(
    val dcqlQuery: DcqlQuery,
    val provenance: List<DcqlCredentialProvenance>,
    val warnings: List<String> = emptyList(),
)

data class DcqlCredentialProvenance(
    val credentialQueryId: String,
    val channelRef: ChannelRef,
    val generatedClaimPaths: List<List<String>>,
    val format: String,
    val vct: String? = null,
    val doctype: String? = null,
)

How projection works​

For each channel reference, the converter:

  1. Loads the pinned verifiable-credential channel.
  2. Resolves its pinned data product and the data product's object model and data domains.
  3. Reads the channel's claim mappings in their authored order.
  4. Emits the corresponding DCQL claim paths.
  5. Applies the channel's credential format and its vct or doctype identity.
  6. Adds one credential query and one provenance entry to the result.

The converter is mechanical. Constraints and selection decisions come from the semantic model; the channel supplies the wire representation.

Preview a query​

Use preview while reviewing a verifier design. It runs the complete projection but does not persist the result or record lineage.

POST /api/dcql/v1/queries/preview
Authorization: Bearer <operator-token>
Content-Type: application/json
{
  "channelRefs": [
    {
      "channelId": "51c066a7-30ef-4415-b6e6-c5c662d1f130",
      "channelVersion": 2
    },
    {
      "channelId": "5a43008a-c48c-49fb-aea0-2aba9e983938",
      "channelVersion": 1
    }
  ],
  "useCredentialSets": true
}

The response contains one credential query per channel, followed by matching provenance entries in the same order. A provenance entry reports the pinned channel, generated claim paths, credential format, and format-specific type identifier.

Author and persist a query​

The authored operation uses the same conversion and stores the resulting query under the caller-supplied queryId.

POST /api/dcql/v1/queries/authored
Authorization: Bearer <operator-token>
Content-Type: application/json
{
  "queryId": "employee-and-business-card",
  "name": "Employee and business card verification",
  "description": "Requests the governed employee identity and business-card claims.",
  "channelRefs": [
    {
      "channelId": "51c066a7-30ef-4415-b6e6-c5c662d1f130",
      "channelVersion": 2
    },
    {
      "channelId": "5a43008a-c48c-49fb-aea0-2aba9e983938",
      "channelVersion": 1
    }
  ],
  "useCredentialSets": true
}

For a new queryId, the response reports version 1. Authoring the same identifier again appends an immutable version and advances the current-version pointer. The operation also records REQUEST-role usage lineage for every selected business-term path that contributed to the query.

Errors and warnings​

The operation fails without persisting when:

  • a channel reference is missing or points to an unavailable version;
  • a referenced channel is not a verifiable-credential channel;
  • a channel cannot resolve its pinned data product;
  • the request contains no channel references;
  • the active license does not include semantic-modeling.v1.

Non-fatal projection issues are returned in warnings. Preview and author use the same converter, so the same input produces the same DCQL body and provenance.