dcql-components.yml

openapi: 3.0.4
info:
  title: OID4VP DCQL Query Configuration API Components
  version: 0.1.0
  description: Entity schemas and path parameters for the OID4VP DCQL Query Configuration Admin API.
paths: {}
components:
  parameters:
    QueryId:
      name: queryId
      in: path
      required: true
      description: >
        Stable identifier of the DCQL query configuration, unique within the tenant.
        This is the value you chose at create time and use to reference the
        configuration in presentation requests.
      schema:
        type: string
        minLength: 1
        example: identity-verification

    VerifierId:
      name: verifierId
      in: path
      required: true
      description: Identifier of the verifier instance.
      schema:
        type: string
        minLength: 1

    ActivationId:
      name: activationId
      in: path
      required: true
      description: Identifier of a verifier DCQL binding activation.
      schema:
        type: string
        minLength: 1

    Version:
      name: version
      in: path
      required: true
      description: Version number of the DCQL query configuration.
      schema:
        type: integer
        minimum: 1

  schemas:
    DcqlQueryConfiguration:
      type: object
      description: >
        A stored DCQL query configuration, referenced by `queryId`. Holds the DCQL
        query the verifier sends to a wallet plus its metadata and audit timestamps.
      required: [queryId, name, dcqlQuery, enabled, createdAt, updatedAt]
      properties:
        queryId:
          type: string
          description: Stable identifier for the configuration, unique within the tenant.
          example: identity-verification
        name:
          type: string
          description: Human-readable name shown in admin tooling.
          example: Identity verification
        description:
          type: string
          nullable: true
          description: Optional free-text description of the configuration's purpose.
          example: Verify a person's identity credential
        dcqlQuery:
          $ref: "#/components/schemas/DcqlQuery"
        enabled:
          type: boolean
          description: >
            Whether the configuration is available for use. Disabled configurations
            remain stored but should not be referenced by new presentation requests.
          example: true
        createdAt:
          type: integer
          format: int64
          description: Creation timestamp, epoch milliseconds (UTC).
          example: 1749312000000
        updatedAt:
          type: integer
          format: int64
          description: Last-update timestamp, epoch milliseconds (UTC).
          example: 1749312000000
      example:
        queryId: identity-verification
        name: Identity verification
        description: Verify a person's identity credential
        dcqlQuery:
          credentials:
            - id: identity_credential
              format: dc+sd-jwt
              claims:
                - path: [first_name]
        enabled: true
        createdAt: 1749312000000
        updatedAt: 1749312000000

    DcqlQuery:
      type: object
      description: >
        An OpenID4VP 1.0 DCQL query: the verifier's statement of which credentials and
        claims it wants from the wallet. At least one of `credentials` or
        `credential_sets` must be present. See the OpenID4VP 1.0 specification,
        section 6 (Digital Credentials Query Language), for the full grammar.
      properties:
        credentials:
          type: array
          description: The credentials requested by the verifier. Each entry is a single credential query.
          items:
            $ref: "#/components/schemas/DcqlCredentialQuery"
        credential_sets:
          type: array
          description: >
            Disjunctions of credentials that satisfy the verifier's request: the holder
            may present any one option from a set. Use this when several credential types
            can satisfy the same need (for example a passport OR a national ID).
          items:
            type: object
            additionalProperties: true
      anyOf:
        - required: [credentials]
        - required: [credential_sets]
      example:
        credentials:
          - id: EmployeeCredential
            format: dc+sd-jwt
            meta:
              vct_values:
                - https://issuer.acme.example/employee
            claims:
              - path: [given_name]
              - path: [family_name]
              - path: [email]
              - path: [job_title]
          - id: BusinessCardMdoc
            format: mso_mdoc
            meta:
              doctype_value: org.acme.businesscard.1
            claims:
              - path: [org.acme.businesscard.1, given_name]

    DcqlCredentialQuery:
      type: object
      description: >
        A single credential requested within a DCQL query, optionally constrained by
        format, format-specific metadata, and the specific claims to disclose.
      required: [id]
      properties:
        id:
          type: string
          description: >
            Identifier for this credential query, unique within the DCQL query. The
            wallet echoes it back so the verifier can match each presented credential
            to the request that asked for it.
          example: EmployeeCredential
        format:
          type: string
          nullable: true
          description: >
            Requested credential format, for example `dc+sd-jwt` (IETF SD-JWT VC) or
            `mso_mdoc` (ISO/IEC 18013-5 mdoc).
          example: dc+sd-jwt
        meta:
          type: object
          nullable: true
          additionalProperties: true
          description: >
            Format-specific metadata constraints. For `dc+sd-jwt` use `vct_values`
            (the accepted credential type URLs); for `mso_mdoc` use `doctype_value`
            (the accepted document type).
          example:
            vct_values:
              - https://issuer.acme.example/employee
        claims:
          type: array
          nullable: true
          description: The specific claims to request from this credential. Omit to request the whole credential.
          items:
            $ref: "#/components/schemas/DcqlClaimQuery"
        claim_sets:
          type: array
          nullable: true
          description: >
            Disjunctions of claim groups: the holder may satisfy this credential query
            by disclosing any one of the listed claim sets.
          items:
            type: object
            additionalProperties: true
        require_cryptographic_holder_binding:
          type: boolean
          default: true
          description: Whether the credential must be cryptographically bound to the holder.
          example: true
        multiple:
          type: boolean
          default: false
          description: Whether multiple matching credentials may be returned for this query.
          example: false
        trusted_authorities:
          type: array
          nullable: true
          description: >
            Trusted authority constraints: only credentials issued under one of these
            authorities satisfy the query.
          items:
            type: object
            additionalProperties: true
      example:
        id: EmployeeCredential
        format: dc+sd-jwt
        meta:
          vct_values:
            - https://issuer.acme.example/employee
        claims:
          - path: [given_name]
          - path: [family_name]
          - path: [email]
          - path: [job_title]

    DcqlClaimQuery:
      type: object
      description: >
        A claim requested within a credential query. The claim is addressed by a `path`,
        an array that navigates the credential's JSON structure.
      required: [path]
      properties:
        path:
          type: array
          description: >
            JSON path components addressing the requested claim. A single-element path
            such as `["given_name"]` targets a top-level claim; for `mso_mdoc` the first
            element is the namespace, for example `["org.acme.businesscard.1",
            "given_name"]`. Nested SD-JWT claims use one element per level, for example
            `["address", "street_address"]`.
          items:
            type: string
          example: [given_name]
        values:
          type: array
          nullable: true
          description: >
            If present, the claim only satisfies the query when its value matches one of
            these values. For example `{"path": ["over_18"], "values": [true]}`.
          items: {}
        intent_to_retain:
          type: boolean
          nullable: true
          description: Whether the verifier intends to retain (store) the disclosed claim value.
          example: true
      example:
        path: [email]
        intent_to_retain: true

    # ── Authoring / versioning (EDK enterprise layer) ──
    ChannelRef:
      type: object
      description: >
        A version-pinned reference to a profile-bound verifiable-credential definition.
        Each reference resolves to one set-backed definition and contributes exactly one
        credential query to the derived DCQL query.
      required: [channelId, channelVersion]
      properties:
        channelId:
          type: string
          format: uuid
          description: The referenced verifiable-credential definition id.
          example: 0d4f9c2e-7b1a-4e8f-9c3d-2a6b5e8f1c4d
        channelVersion:
          type: integer
          format: int64
          minimum: 1
          description: The pinned definition snapshot version (monotonic, starting at 1).
          example: 3

    DcqlCredentialProvenance:
      type: object
      description: >
        The resolution provenance of one credential query within a derived DCQL query:
        which definition produced it, the wire claim paths that were emitted, and the
        derived wire-format identity.
      required: [credentialQueryId, channelRef, generatedClaimPaths, format]
      properties:
        credentialQueryId:
          type: string
          description: >
            The id of the credential query within the derived DCQL query this provenance
            belongs to.
          example: EmployeeCredential
        channelRef:
          $ref: '#/components/schemas/ChannelRef'
        generatedClaimPaths:
          type: array
          description: >
            The wire claim paths emitted for this credential query, in order. Each path is
            a flat list of wire segments; a segment may itself contain dots (for example an
            mdoc namespace).
          items:
            type: array
            items:
              type: string
          example: [[given_name], [family_name]]
        format:
          type: string
          description: The credential wire format, for example `dc+sd-jwt` or `mso_mdoc`.
          example: dc+sd-jwt
        vct:
          type: string
          nullable: true
          description: The SD-JWT VC type identifier, when the format carries one.
          example: https://issuer.acme.example/employee
        doctype:
          type: string
          nullable: true
          description: The mdoc document type, when the format carries one.
          example: org.iso.18013.5.1.mDL

    PreviewDcqlQueryRequest:
      type: object
      description: >
        Request to derive a DCQL query from profile-bound verifiable-credential
        definitions without persisting it.
      required: [channelRefs]
      properties:
        channelRefs:
          type: array
          minItems: 1
          description: >
            The version-pinned definition references to project, in order. Each contributes
            exactly one credential query to the derived DCQL query.
          items:
            $ref: '#/components/schemas/ChannelRef'
        intentToRetain:
          type: boolean
          default: false
          description: Stamped onto every emitted DCQL claim query.
        useCredentialSets:
          type: boolean
          default: false
          description: >
            When true, wraps the derived credential query ids in a single required
            credential set.

    PreviewDcqlQueryResult:
      type: object
      description: >
        The derived DCQL query plus per-credential-query provenance. Nothing is persisted.
      required: [dcqlQuery, provenance]
      properties:
        dcqlQuery:
          $ref: '#/components/schemas/DcqlQuery'
        provenance:
          type: array
          description: Per-credential-query resolution provenance, in input order.
          items:
            $ref: '#/components/schemas/DcqlCredentialProvenance'
        warnings:
          type: array
          description: Non-fatal conversion warnings.
          items:
            type: string

    AuthorDcqlQueryRequest:
      type: object
      description: >
        Request to derive a DCQL query from profile-bound verifiable-credential
        definitions and persist it to the versioned DCQL store.
      required: [queryId, name, channelRefs]
      properties:
        queryId:
          type: string
          minLength: 1
          description: >
            The DCQL store key to persist under, unique within the tenant. Authoring an
            existing `queryId` appends a new version.
          example: identity-verification
        name:
          type: string
          description: Human-readable name stored on the DCQL query configuration.
          example: Identity verification
        description:
          type: string
          nullable: true
          description: Optional free-text description stored on the configuration.
        channelRefs:
          type: array
          minItems: 1
          description: >
            The version-pinned definition references to project, in order. Each contributes
            exactly one credential query to the derived DCQL query.
          items:
            $ref: '#/components/schemas/ChannelRef'
        intentToRetain:
          type: boolean
          default: false
          description: Stamped onto every emitted DCQL claim query.
        useCredentialSets:
          type: boolean
          default: false
          description: >
            When true, wraps the derived credential query ids in a single required
            credential set.

    AuthoredDcqlQueryResult:
      type: object
      description: >
        The persisted DCQL query: its store key and version, the derived query body, and
        the per-credential-query provenance the usage lineage was recorded from.
      required: [queryId, version, dcqlQuery, provenance]
      properties:
        queryId:
          type: string
          description: The DCQL store key the query was persisted under.
          example: identity-verification
        version:
          type: integer
          format: int64
          description: >
            The version the versioned store advanced to (1 for a fresh query, monotonic
            thereafter).
          example: 1
        dcqlQuery:
          $ref: '#/components/schemas/DcqlQuery'
        provenance:
          type: array
          description: Per-credential-query resolution provenance, in input order.
          items:
            $ref: '#/components/schemas/DcqlCredentialProvenance'
        warnings:
          type: array
          description: Non-fatal conversion warnings.
          items:
            type: string

    DcqlQueryVersionSummary:
      type: object
      description: Summary of a single version in a DCQL query configuration's history.
      required: [version, createdAt]
      properties:
        version:
          type: integer
          description: Monotonic version number.
        createdAt:
          type: integer
          format: int64
          description: Version creation timestamp, epoch milliseconds.
        createdBy:
          type: string
          nullable: true
          description: Principal that created this version.

    DcqlQueryVersionRecord:
      type: object
      description: A full version record of a DCQL query configuration.
      required: [identifier, version, dcqlQuery, createdAt]
      properties:
        identifier:
          type: string
          description: Stable identifier of the configuration this version belongs to.
        version:
          type: integer
          description: Monotonic version number.
        dcqlQuery:
          $ref: '#/components/schemas/DcqlQuery'
        createdAt:
          type: integer
          format: int64
          description: Version creation timestamp, epoch milliseconds.
        createdBy:
          type: string
          nullable: true
          description: Principal that created this version.

    RestoreDcqlQueryVersionRequest:
      type: object
      description: Request body for restoring a previous version of a DCQL query configuration.
      properties:
        note:
          type: string
          nullable: true
          description: Optional note recorded with the restore operation.

    # ── Verifier bindings / activations (VDX platform layer) ──
    VerifierDcqlBinding:
      type: object
      description: A binding between a verifier instance and a DCQL query configuration.
      required: [id, tenantId, verifierId, queryId, pinnedVersion, enabled, createdAt, updatedAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        verifierId:
          type: string
        queryId:
          type: string
          description: Identifier of the bound DCQL query configuration.
        pinnedVersion:
          type: integer
          description: The configuration version this binding is pinned to.
        enabled:
          type: boolean
        alias:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    BindVerifierDcqlRequest:
      type: object
      description: Request body for binding a DCQL query to a verifier.
      required: [queryId]
      properties:
        queryId:
          type: string
          description: Identifier of the DCQL query to bind.
        version:
          type: integer
          nullable: true
          description: Version to pin. Defaults to the current version at bind time when omitted.

    UpdateVerifierDcqlBindingRequest:
      type: object
      description: Request body for updating a verifier's DCQL binding.
      properties:
        pinnedVersion:
          type: integer
          nullable: true
          description: New pinned version (advance or roll back).
        enabled:
          type: boolean
          nullable: true
        alias:
          type: string
          nullable: true

    VerifierDcqlBindingActivation:
      type: object
      description: A scheduled future activation of a verifier's DCQL binding to a target version.
      required: [activationId, verifierId, queryId, pinnedVersion, effectiveAt, status]
      properties:
        activationId:
          type: string
          description: Identifier of the scheduled activation.
        verifierId:
          type: string
        queryId:
          type: string
          description: Identifier of the bound DCQL query configuration.
        pinnedVersion:
          type: integer
          description: The configuration version this activation will pin.
        effectiveAt:
          type: string
          format: date-time
          description: When the activation takes effect.
        status:
          type: string
          enum: [PENDING, APPLIED, CANCELLED, FAILED]
          description: Lifecycle status of the scheduled activation.

    ActivateVerifierDcqlBindingRequest:
      type: object
      description: Request body for scheduling a verifier DCQL binding activation.
      required: [effectiveAt]
      properties:
        pinnedVersion:
          type: integer
          nullable: true
          description: Version to pin. Defaults to the latest version when omitted.
        effectiveAt:
          type: string
          format: date-time
          description: When the activation should take effect.