oid4vci-issuer-components.yml

openapi: 3.0.4
info:
  title: OID4VCI Issuer Integration API Components
  version: 0.1.0
  description: |
    Entity schemas, enums, and path parameters for the OID4VCI Issuer server-to-server
    integration API (offer management and the connector-backed attribute-provisioning pipeline).
    Shapes mirror the backing service-command request and response models. Property names are the
    wire names: compact OID4VCI endpoint DTOs use camelCase, while command envelopes keep their
    explicit snake_case names where declared by the service.
paths: {}
components:
  parameters:
    CorrelationId:
      name: correlationId
      in: path
      required: true
      description: |
        The external correlation handle that keys the issuance pipeline session. Either supplied
        by the caller when the session was initialised or generated by the server and returned in
        the init response.
      schema:
        type: string

    CallbackToken:
      name: callbackToken
      in: path
      required: true
      description: |
        Opaque capability token minted by the issuer when an asynchronous connector contributor was
        dispatched. It authorises an out-of-band contribution to a specific session and is
        cross-checked against the path correlation id.
      schema:
        type: string

  schemas:
    # ---------------------------------------------------------------------------
    # Shared attribute-flow primitives (mirror the backing Kotlin records).
    # ---------------------------------------------------------------------------

    AttributeRecord:
      description: |
        A single attribute contributed to a pipeline session bag, with full provenance. The
        bag uses `priority` (then `timestamp`) to decide which record wins for a given `path`.
      type: object
      required: [path, value, producerId, phase, timestamp]
      properties:
        path:
          type: string
          description: |
            Opaque attribute path identifying where this attribute lives in the bag. The string
            form (dotted path, JSON pointer, or flat key) is producer-defined; treat it as an
            identity key.
        value:
          $ref: '#/components/schemas/AttributeValue'
        producerId:
          type: string
          description: Opaque identifier of the connector contributor that produced this record.
        producerDetail:
          type: string
          description: Contributor-specific detail (e.g. an IDV node id, an OIDC issuer, an HR-API endpoint).
        phase:
          type: string
          description: |
            The pipeline phase during which this record was contributed. An opaque, extensible
            string. Shared values include `session_init`, `resolution`, `idv_completed`,
            `credential_assembly`, and `post_issuance`. The OID4VCI flow also uses
            `oid4vci_credential_request` and `oid4vci_deferred`.
        timestamp:
          type: string
          format: date-time
          description: When this record was contributed by its source.
        assurance:
          type: string
          description: Assurance level derived from IDV evidence or an OIDC `acr`.
          enum: [low, substantial, high]
        priority:
          type: integer
          default: 0
          description: Conflict-resolution priority. Higher wins; ties are broken by `timestamp`.
        retention:
          $ref: '#/components/schemas/AttributeRetentionPolicy'
        verified:
          type: boolean
          default: false
          description: Whether this attribute has been verified by an identity-verification process.

    AttributeValue:
      description: |
        The typed value carried by an `AttributeRecord`, discriminated by `type`. Most attributes
        are plain JSON data; some carry a reference to a stored blob, a cryptographic key, or
        supporting verification evidence.
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [data, blob, key, evidence]
          description: |
            Discriminates the value variant. `data` carries a plain JSON `value`; `blob`, `key`,
            and `evidence` carry reference structures. For integration callers, `data` is by far
            the most common.
        value:
          description: |
            For `type: data`, any JSON value (string, number, boolean, object, array, null). Not
            present for the reference variants.
      additionalProperties: true

    AttributeEvidence:
      description: |
        A reference to supporting evidence (a document scan, an IDV result, an audit log). Used
        on the approval endpoint to record the evidence captured at approval time.
      type: object
      required: [evidenceId, evidenceType]
      properties:
        evidenceId:
          type: string
        evidenceType:
          type: string
        hash:
          type: string
        hashAlgorithm:
          type: string
        uri:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string

    AttributeRetentionPolicy:
      description: |
        How long an attribute may be retained and under what legal basis, discriminated by `type`.
      oneOf:
        - $ref: '#/components/schemas/EphemeralRetention'
        - $ref: '#/components/schemas/SessionRetention'
        - $ref: '#/components/schemas/RetainedRetention'
      discriminator:
        propertyName: type
        mapping:
          ephemeral: '#/components/schemas/EphemeralRetention'
          session: '#/components/schemas/SessionRetention'
          retained: '#/components/schemas/RetainedRetention'

    EphemeralRetention:
      description: In-memory only. Never serialized to persistent storage.
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [ephemeral]

    SessionRetention:
      description: Stored encrypted in the session store; cleared on session completion or expiry.
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [session]
        encryptionRequired:
          type: boolean
          default: true

    RetainedRetention:
      description: |
        Persisted long-term with an explicit retention period, legal basis, and jurisdiction
        context.
      type: object
      required: [type, retentionDays, legalBasis]
      properties:
        type:
          type: string
          enum: [retained]
        retentionDays:
          type: integer
        legalBasis:
          type: string
          description: Legal basis for retention (e.g. a GDPR Article 6(1) basis, AML record-keeping).
        regulatoryFramework:
          type: string
          description: Regulatory framework governing this data (e.g. eIDAS, NIST, UK DIATF).
        territoryId:
          type: string
          description: Territory / jurisdiction for data residency (ISO 3166 country code).
        territoryRestriction:
          type: string
        encryptionRequired:
          type: boolean
          default: true
        purpose:
          type: string
          description: Purpose limitation.
        consentObtained:
          type: boolean
          default: false

    ConnectorFields:
      description: |
        Opaque field inputs for connector invocations. Field names are part of the connector
        invocation binding contract; values may be any JSON value and are stored as sensitive
        pipeline session data.
      type: object
      additionalProperties:
        description: Any JSON value (string, number, boolean, object, array, null).

    # ---------------------------------------------------------------------------
    # Pipeline configuration (init-session request).
    # ---------------------------------------------------------------------------

    PipelineConfiguration:
      description: |
        A registered pipeline: the connector invocation bindings that can run at each issuance
        phase, the credential-claims bindings it can assemble, and the connector fields the caller is
        expected to supply at session init. `invocationBindings` and `claimsBindings` are
        issuer-side wiring structures; integration callers usually reference an already-registered
        pipeline by its `pipelineId` and leave the binding lists empty.
      type: object
      required: [pipelineId]
      properties:
        pipelineId:
          type: string
          description: Stable identifier of the pipeline this session runs.
        invocationBindings:
          type: array
          description: |
            Connector invocation bindings bound into this pipeline. Each binding declares the
            owner surface, owner reference, issuance stage, role, execution policy, target route or
            operation, subset mapping, and protocol/governance context for connector-native
            execution across the issuance lifecycle.
          items:
            $ref: './connector-components.yml#/components/schemas/ConnectorInvocationBinding'
        claimsBindings:
          type: array
          description: |
            The credentials this pipeline can assemble claims for. An issuer-side wiring
            structure; modelled here as opaque objects.
          items:
            type: object
            additionalProperties: true
        expectedInitialConnectorFields:
          type: array
          description: |
            Names of connector fields the caller is expected to provide at session init. A connector
            invocation may consume one of these without any earlier invocation producing it.
          items:
            type: string

    CompactRetentionPolicy:
      description: |
        Retention override used by compact OID4VCI provisioning bodies. The compact wire shape uses
        `kind` as discriminator.
      oneOf:
        - $ref: '#/components/schemas/CompactEphemeralRetention'
        - $ref: '#/components/schemas/CompactSessionRetention'
        - $ref: '#/components/schemas/CompactRetainedRetention'
      discriminator:
        propertyName: kind
        mapping:
          ephemeral: '#/components/schemas/CompactEphemeralRetention'
          session: '#/components/schemas/CompactSessionRetention'
          retained: '#/components/schemas/CompactRetainedRetention'

    CompactEphemeralRetention:
      type: object
      required: [kind]
      properties:
        kind:
          type: string
          enum: [ephemeral]

    CompactSessionRetention:
      type: object
      required: [kind]
      properties:
        kind:
          type: string
          enum: [session]
        encryptionRequired:
          type: boolean

    CompactRetainedRetention:
      type: object
      required: [kind, retentionDays, legalBasis]
      properties:
        kind:
          type: string
          enum: [retained]
        retentionDays:
          type: integer
        legalBasis:
          type: string
        regulatoryFramework:
          type: string
        territoryId:
          type: string
        territoryRestriction:
          type: string
        encryptionRequired:
          type: boolean
        purpose:
          type: string
        consentObtained:
          type: boolean

    SemanticSetAttributeItem:
      type: object
      required: [term, value]
      properties:
        term:
          type: string
        value:
          description: Any JSON value.
        retention:
          $ref: '#/components/schemas/CompactRetentionPolicy'
        priority:
          type: integer
        assurance:
          type: string
          enum: [low, substantial, high]
        verified:
          type: boolean
        contributorDetail:
          type: string
        sdPolicy:
          type: string

    SemanticSetEntry:
      type: object
      required: [bundleId]
      properties:
        bundleId:
          type: string
        version:
          type: string
        retention:
          $ref: '#/components/schemas/CompactRetentionPolicy'
        values:
          type: object
          additionalProperties:
            description: Any JSON value keyed by semantic term.
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/SemanticSetAttributeItem'

    RawAttributeItem:
      type: object
      required: [path, value]
      properties:
        path:
          type: string
        value:
          description: Any JSON value.
        retention:
          $ref: '#/components/schemas/CompactRetentionPolicy'
        priority:
          type: integer
        assurance:
          type: string
          enum: [low, substantial, high]
        verified:
          type: boolean
        contributorDetail:
          type: string
        sdPolicy:
          type: string

    AttributeProvisionGroup:
      type: object
      required: [contributorId, phase]
      description: |
        Compact provisioning group carrying one provenance pair plus attributes and connector
        fields for any OID4VCI lifecycle phase.
      properties:
        contributorId:
          type: string
          description: Opaque contributor id for records created from this group.
        phase:
          type: string
          description: Pipeline phase string attached to records created from this group.
        timestamp:
          type: string
          format: date-time
        contributorDetail:
          type: string
        retention:
          $ref: '#/components/schemas/CompactRetentionPolicy'
        semanticAttributeSets:
          type: array
          items:
            $ref: '#/components/schemas/SemanticSetEntry'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/RawAttributeItem'
        connectorFields:
          $ref: '#/components/schemas/ConnectorFields'

    ContributeAttributesCompactRequestBody:
      type: object
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/AttributeProvisionGroup'

    CreateOfferRequestBody:
      type: object
      required: [issuerId]
      properties:
        issuerId:
          type: string
        credentialConfigurationIds:
          type: array
          items:
            type: string
        preAuthorizedCodeGrant:
          type: boolean
          default: false
        authorizationCodeGrant:
          type: boolean
          default: false
        txCodeRequired:
          type: boolean
          default: false
        offerTtlSeconds:
          type: integer
          format: int64
          default: 600
        boundUsageToken:
          type: string
        postIssuanceHookAllowList:
          type: array
          items:
            type: string
        callback:
          $ref: '#/components/schemas/IssuanceSessionCallbackConfig'
        state:
          type: string
          description: Caller-controlled opaque correlation state. The issuer stores but never interprets this value.
        scheme:
          type: string
        uriLifecycle:
          type: string
          enum: [SINGLE_USE, REUSABLE_FRESH_PER_FETCH]
        preSeededGroups:
          type: array
          items:
            $ref: '#/components/schemas/AttributeProvisionGroup'

    IssuanceSessionCallbackConfig:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
        statuses:
          type: array
          description: Issuance states that trigger the callback. An empty array selects every state.
          items:
            type: string
            enum: [OFFER_CREATED, OFFER_RECEIVED, TOKEN_REQUESTED, CREDENTIAL_REQUESTED, CREDENTIAL_ISSUED, DEFERRED, COMPLETED, EXPIRED, FAILED]
        includeIssuanceData:
          type: boolean
          default: false

    # ---------------------------------------------------------------------------
    # Pipeline request bodies.
    # ---------------------------------------------------------------------------

    InitPipelineSessionRequestBody:
      description: |
        Allocates a new issuance pipeline session for a registered pipeline configuration,
        optionally seeded with attributes and connector fields known up front. No phase runs here; the
        caller drives phases afterwards via the contribute endpoint.
      type: object
      required: [pipeline_configuration]
      properties:
        pipeline_configuration:
          $ref: '#/components/schemas/PipelineConfiguration'
        correlation_id:
          type: string
          description: External correlation handle. The server generates one when absent.
        initial_attributes:
          type: array
          items:
            $ref: '#/components/schemas/AttributeRecord'
        initial_connector_fields:
          $ref: '#/components/schemas/ConnectorFields'
        ttl_seconds:
          type: integer
          format: int64
          description: Session lifetime. A configured default applies when absent.

    InitPipelineSessionResult:
      description: The allocated session identifier and the resolved correlation handle.
      type: object
      required: [sessionId, correlationId]
      properties:
        sessionId:
          type: string
        correlationId:
          type: string
          description: The correlation handle. Generated by the server when the caller did not supply one.

    ContributeAttributesRequestBody:
      description: |
        Compact contribution payload. Each group carries one contributor/phase provenance pair,
        optional semantic-set values, raw attributes, and connector fields.
      type: object
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/AttributeProvisionGroup'

    ContributeViaCallbackRequestBody:
      description: |
        Compact callback contribution payload. It has the same shape as direct contribution and is
        fed into the pipeline as a deferred contribution.
      type: object
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/AttributeProvisionGroup'

    ContributeAttributesResult:
      description: The session state after the contributing phase ran.
      type: object
      required: [sessionId, status, completedPhases]
      properties:
        sessionId:
          type: string
        status:
          $ref: '#/components/schemas/IssuancePipelineStatus'
        completedPhases:
          type: array
          description: Phases completed for the session, including this one.
          items:
            type: string

    ApprovePipelineSessionRequestBody:
      description: |
        Applies an approval-gate decision to a session awaiting approval. The approver identity is
        resolved from the authenticated context and is never supplied here.
      type: object
      required: [decision]
      properties:
        decision:
          $ref: '#/components/schemas/ApprovalDecision'
        reason:
          type: string
          description: Human-readable reason. Required on `REJECT`, optional on `APPROVE`.
        evidence:
          $ref: '#/components/schemas/AttributeEvidence'

    ApprovePipelineSessionResult:
      description: The session correlation id and its new lifecycle status after the decision.
      type: object
      required: [correlationId, status]
      properties:
        correlationId:
          type: string
        status:
          $ref: '#/components/schemas/IssuancePipelineStatus'

    ApprovalDecision:
      description: Whether the approver grants or denies issuance for the pipeline session.
      type: string
      enum: [APPROVE, REJECT]

    RecordPipelineContributorFailureRequestBody:
      description: |
        Marks a single connector contributor's contribution as failed. Recorded on the session so a
        later completeness evaluation can treat an unsatisfied required contributor as a hard miss
        rather than waiting indefinitely.
      type: object
      required: [contributor_id]
      properties:
        contributor_id:
          type: string
          description: The opaque contributor identifier whose contribution failed.
        reason:
          type: string
          description: Optional human-readable reason recorded with the failure marker.

    RecordPipelineContributorFailureResult:
      description: The session correlation id and the contributor id that was marked as failed.
      type: object
      required: [correlationId, contributorId]
      properties:
        correlationId:
          type: string
        contributorId:
          type: string

    EvaluateAttributeCompletenessResult:
      description: |
        One completeness verdict per credential-claims binding in the session's pipeline
        configuration.
      type: object
      required: [verdicts]
      properties:
        verdicts:
          type: array
          items:
            $ref: '#/components/schemas/BindingCompletenessVerdict'

    BindingCompletenessVerdict:
      description: The completeness verdict for one credential-claims binding.
      type: object
      required: [bindingId, complete]
      properties:
        bindingId:
          type: string
          description: The credential-claims binding this verdict is for.
        complete:
          type: boolean
          description: True when every mandatory attribute path is present in the bag.
        missingRequiredPaths:
          type: array
          description: Mandatory attribute paths still missing from the bag. Empty when complete.
          items:
            type: string
        deferralRecommended:
          type: boolean
          default: false
          description: |
            True when the binding is incomplete and its deferral policy is enabled, meaning the
            issuer should defer rather than fail.
        awaitingApproval:
          type: boolean
          default: false
          description: |
            True when the binding requires approval and the session has not yet been approved.
            Even a complete binding must defer while this is true.

    GetSessionAttributesResult:
      description: |
        The attributes accumulated in a session bag, plus the names of connector fields stored on
        the session. Connector field values are sensitive and are never returned over this API.
      type: object
      required: [attributes, connectorFieldNames]
      properties:
        attributes:
          type: object
          description: |
            Effective attribute values from the session bag, keyed by attribute path. Only records
            whose value is plain attribute data are included; blob, key, and evidence references
            are omitted.
          additionalProperties:
            description: Any JSON value (string, number, boolean, object, array, null).
        connectorFieldNames:
          type: array
          description: |
            Names of connector fields currently present on the session. Values are omitted.
          items:
            type: string

    IssuancePipelineStatus:
      description: |
        Lifecycle status of an issuance pipeline session.
      type: string
      enum:
        - CREATED
        - PHASE_EXECUTING
        - PHASE_COMPLETED
        - AWAITING_DEFERRED
        - AWAITING_APPROVAL
        - READY
        - COMPLETED
        - FAILED
        - EXPIRED

    SdJwtVcTypeMetadata:
      description: |
        SD-JWT VC type metadata document using the draft-ietf-oauth-sd-jwt-vc-11 shape
        referenced by OID4VCI 1.0 Final. OID4VCI issuer metadata has its own display and claim
        objects; do not copy OID4VCI-only fields such as `locale`, `mandatory`, or
        `background_image` into this VCT document.
      type: object
      required: [vct]
      properties:
        vct:
          type: string
          description: Verifiable Credential Type identifier.
          example: https://issuer.example.com/public/schema/vct/EmployeeBadge
        name:
          type: string
          nullable: true
          example: Employee Badge
        description:
          type: string
          nullable: true
          example: Corporate employee credential
        extends:
          type: string
          nullable: true
        extends#integrity:
          type: string
          nullable: true
        display:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SdJwtVcDisplayInformation'
        claims:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SdJwtVcClaimInformation'
        schema:
          type: object
          nullable: true
          additionalProperties: true
        schema_uri:
          type: string
          nullable: true
        schema_uri#integrity:
          type: string
          nullable: true

    SdJwtVcDisplayInformation:
      description: Localized SD-JWT VC type display entry.
      type: object
      required: [lang, name]
      properties:
        lang:
          type: string
          description: BCP-47 language tag.
          example: en-US
        name:
          type: string
          example: Employee Badge
        description:
          type: string
          nullable: true
          example: Corporate employee credential
        rendering:
          $ref: '#/components/schemas/SdJwtVcRenderingMetadata'

    SdJwtVcRenderingMetadata:
      description: SD-JWT VC rendering metadata.
      type: object
      properties:
        simple:
          $ref: '#/components/schemas/SdJwtVcSimpleRenderingMethod'

    SdJwtVcSimpleRenderingMethod:
      description: |
        SD-JWT VC draft-11 simple rendering method. Supports logo and colors; background images
        belong to OID4VCI issuer metadata display objects, not this VCT object.
      type: object
      properties:
        logo:
          $ref: '#/components/schemas/SdJwtVcLogoMetadata'
        background_color:
          type: string
          nullable: true
          example: '#003087'
        text_color:
          type: string
          nullable: true
          example: '#FFFFFF'

    SdJwtVcLogoMetadata:
      description: Logo metadata for SD-JWT VC rendering.
      type: object
      required: [uri]
      properties:
        uri:
          type: string
          example: /public/assets/design/logo.png
        uri#integrity:
          type: string
          nullable: true
        alt_text:
          type: string
          nullable: true
          example: Badge logo

    SdJwtVcClaimInformation:
      description: |
        SD-JWT VC type claim metadata. The `mandatory` property is intentionally absent because
        it is an OID4VCI issuer metadata claim property, not an SD-JWT VC draft-11 VCT property.
      type: object
      required: [path]
      properties:
        path:
          type: array
          description: Claim path segments. A null segment denotes any array element.
          items:
            nullable: true
            oneOf:
              - type: string
              - type: integer
                minimum: 0
          example: [employment, department, name]
        display:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SdJwtVcClaimDisplayMetadata'
        sd:
          $ref: '#/components/schemas/SdJwtVcClaimSdMetadata'
        svg_id:
          type: string
          nullable: true

    SdJwtVcClaimDisplayMetadata:
      description: Localized SD-JWT VC type claim display entry.
      type: object
      required: [lang, label]
      properties:
        lang:
          type: string
          description: BCP-47 language tag.
          example: en-US
        label:
          type: string
          example: Department
        description:
          type: string
          nullable: true
          example: Business unit

    SdJwtVcClaimSdMetadata:
      description: Selective disclosure metadata for an SD-JWT VC type claim.
      type: string
      enum: [always, allowed, never]

    Error:
      description: Error envelope returned on a failed request.
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Stable error code.
        message:
          type: string
          description: Human-readable error description.