forms-components.yml

openapi: 3.0.4
info:
  title: Forms API Components
  version: 0.1.0
  description: Entity schemas, enums, and path/query/header parameters for the Forms REST Server API.
paths: {}
components:
  parameters:
    TenantId:
      name: X-Tenant-ID
      in: header
      required: true
      description: Tenant scope header. Required on every request.
      schema:
        type: string
        format: uuid
    IfMatch:
      name: If-Match
      in: header
      required: false
      description: |
        Optimistic-concurrency token carrying the expected session [revision] as a strong
        validator (RFC 7232). Mismatch returns `412 Precondition Failed` with code
        `OPTIMISTIC_LOCK_CONFLICT`. Successful mutating responses echo the new revision back via
        the `ETag` response header.
      schema:
        type: string
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        Caller-supplied idempotency key. Replaying the same key replays the original result;
        reusing the key with a different request body returns `409` with code
        `IDEMPOTENCY_KEY_CONFLICT`.
      schema:
        type: string
    FormId:
      name: formId
      in: path
      required: true
      description: Identifier of the form definition.
      schema:
        type: string
        format: uuid
    SessionId:
      name: sessionId
      in: path
      required: true
      description: Identifier of the form session.
      schema:
        type: string
        format: uuid
    StepId:
      name: stepId
      in: path
      required: true
      description: Identifier of the step that owns the action.
      schema:
        type: string
        format: uuid
    StepIndex:
      name: stepIndex
      in: path
      required: true
      description: Zero-based step index within the resolved form.
      schema:
        type: integer
        minimum: 0
    ActionId:
      name: actionId
      in: path
      required: true
      description: Identifier of the step action.
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      description: Maximum number of items to return. Clamped to `[1, 100]`. Defaults to `20`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Offset:
      name: offset
      in: query
      description: Number of items to skip. Mutually exclusive with `page`/`size` style.
      schema:
        type: integer
        minimum: 0
        default: 0
    Sort:
      name: sort
      in: query
      description: Field name to sort by. Defaults to `createdAt`.
      schema:
        type: string
        default: createdAt
    SortDirection:
      name: sortDirection
      in: query
      description: Sort direction.
      schema:
        type: string
        enum: [ASC, DESC]
        default: DESC

  schemas:
    FormStatus:
      type: string
      description: Lifecycle status of a [FormDefinition].
      enum: [DRAFT, PUBLISHED]

    FormKind:
      type: string
      description: The purpose or mode of a [FormDefinition].
      enum:
        - STANDALONE
        - CREDENTIAL_VERIFICATION
        - CREDENTIAL_ISSUANCE
        - CREDENTIAL_REVIEW
        - PROCEDURE

    FormSessionStatus:
      type: string
      description: Lifecycle status of a [FormSession]. Terminal states are `SUBMITTED` and `CANCELLED`.
      enum:
        - IN_PROGRESS
        - COMPLETED
        - SUBMITTED
        - CANCELLED

    FormSessionPhase:
      type: string
      description: Operational phase of a [FormSession]. Independent of [FormSessionStatus].
      enum:
        - CAPTURING
        - VALIDATING_FIELD
        - VALIDATING_STEP
        - NAVIGATING
        - RUNNING_STEP_ACTION
        - APPLYING_ACTION_EFFECTS
        - SUBMITTING
        - SUBMITTED
        - FAILED
        - CANCELLED

    StepActionStatus:
      type: string
      description: Lifecycle status of a single step action within a session.
      enum: [PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED]

    FormDefinition:
      type: object
      description: |
        A versioned form definition. References a [SemanticAttributeSet] via `attributeSetId`
        and adds form-specific concerns: steps, sections, field overrides, conditions,
        validation rules, and step actions.
      required:
        - id
        - tenantId
        - definitionKey
        - name
        - version
        - kind
        - attributeSetId
        - steps
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for this specific form version.
        tenantId:
          type: string
        definitionKey:
          type: string
          format: uuid
          description: Stable logical identifier shared across all versions of the same form.
        previousId:
          type: string
          format: uuid
          nullable: true
          description: The `id` of the immediately prior version, or null on v1.
        name:
          type: string
        version:
          type: string
        description:
          type: string
          nullable: true
        kind:
          $ref: '#/components/schemas/FormKind'
        attributeSetId:
          type: string
          format: uuid
        steps:
          type: array
          items:
            $ref: '#/components/schemas/FormStepDefinition'
        status:
          $ref: '#/components/schemas/FormStatus'
        policyResourceKey:
          type: string
          nullable: true
        credentialBindings:
          type: array
          items:
            $ref: '#/components/schemas/FormCredentialBinding'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        createdById:
          type: string
          nullable: true
          description: Principal subject (OIDC sub, DID, service-account name, ...) that created the record. Opaque string, NOT a UUID.
        updatedById:
          type: string
          nullable: true
        approvedById:
          type: string
          nullable: true
        approvedAt:
          type: string
          format: date-time
          nullable: true
        deletedAt:
          type: string
          format: date-time
          nullable: true

    FormStepDefinition:
      type: object
      description: |
        A step within a [FormDefinition]. Carries an ordered list of [FormSectionDefinition]s
        plus optional step-level access policy and step actions.
      required: [id, formId, name, labels, sortOrder, sections, actions]
      properties:
        id:
          type: string
          format: uuid
        formId:
          type: string
          format: uuid
        name:
          type: string
        labels:
          type: object
          description: Locale-keyed label map (BCP-47 locale -> display string).
          additionalProperties:
            type: string
        descriptions:
          type: object
          nullable: true
          description: Locale-keyed description map (BCP-47 locale -> display string).
          additionalProperties:
            type: string
        sortOrder:
          type: integer
        sections:
          type: array
          items:
            $ref: '#/components/schemas/FormSectionDefinition'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/StepAction'
        policyResourceKey:
          type: string
          nullable: true

    FormSectionDefinition:
      type: object
      description: A section grouping related fields within a [FormStepDefinition].
      required: [id, stepId, name, labels, sortOrder, fields]
      properties:
        id:
          type: string
          format: uuid
        stepId:
          type: string
          format: uuid
        name:
          type: string
        labels:
          type: object
          additionalProperties:
            type: string
        descriptions:
          type: object
          nullable: true
          additionalProperties:
            type: string
        sortOrder:
          type: integer
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FormFieldDefinition'

    FormFieldDefinition:
      type: object
      description: |
        A field reference within a [FormSectionDefinition]. References a canonical attribute
        by path and carries authoring-time overrides (widget hint, mandatory flag, default
        value, read-only, conditions).
      required: [id, sectionId, attributePath, sortOrder, validationRules]
      properties:
        id:
          type: string
          format: uuid
        sectionId:
          type: string
          format: uuid
        attributePath:
          $ref: '#/components/schemas/AttributePath'
        sortOrder:
          type: integer
        validationRules:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationRule'
        defaultValue:
          allOf:
            - $ref: '#/components/schemas/FieldValue'
          nullable: true
        placeholders:
          type: object
          nullable: true
          additionalProperties:
            type: string
        visibilityCondition:
          allOf:
            - $ref: '#/components/schemas/FieldCondition'
          nullable: true
        qualificationCondition:
          allOf:
            - $ref: '#/components/schemas/FieldCondition'
          nullable: true
        disqualificationBehavior:
          $ref: '#/components/schemas/DisqualificationBehavior'
        readOnly:
          type: boolean
          default: false
        widgetHintOverride:
          allOf:
            - $ref: '#/components/schemas/AttributeWidgetHint'
          nullable: true
        mandatoryOverride:
          $ref: '#/components/schemas/MandatoryOverride'
        policyResourceKey:
          type: string
          nullable: true

    ResolvedForm:
      type: object
      description: |
        Runtime tree of a resolved form: steps/sections/fields filtered by access policy with
        labels collapsed to the requested locale. Hidden fields, hidden steps, and
        unauthorized actions are omitted from this tree by construction, they never reach
        the client.
      required: [id, formDefinitionId, name, kind, locale, steps]
      properties:
        id:
          type: string
          format: uuid
        formDefinitionId:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        kind:
          $ref: '#/components/schemas/FormKind'
        locale:
          type: string
          description: BCP-47 locale the form's labels were collapsed to during resolution.
        steps:
          type: array
          items:
            $ref: '#/components/schemas/ResolvedFormStep'
        credentialBindings:
          type: array
          description: |
            INPUT credential bindings carried into the runtime so the step-action start/complete
            commands can resolve them from `session.resolvedForm` alone.
          items:
            $ref: '#/components/schemas/FormCredentialBinding'

    ResolvedFormStep:
      type: object
      description: |
        A step within a [ResolvedForm]. Sections and actions hidden by policy are omitted
        from this tree by construction.
      required: [id, name, label, sortOrder, sections, actions]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        label:
          type: string
        description:
          type: string
          nullable: true
        sortOrder:
          type: integer
        sections:
          type: array
          items:
            $ref: '#/components/schemas/ResolvedFormSection'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/StepAction'

    ResolvedFormSection:
      type: object
      description: A section within a [ResolvedFormStep]. Hidden fields are omitted by construction.
      required: [id, name, label, sortOrder, fields]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        label:
          type: string
        description:
          type: string
          nullable: true
        sortOrder:
          type: integer
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ResolvedFormField'

    ResolvedFormField:
      type: object
      description: |
        A field within a [ResolvedFormSection]. Carries the merged semantic-attribute /
        form-override / policy view of the field as seen by the renderer. Labels are
        already collapsed to the requested locale.
      required:
        - id
        - attributePath
        - label
        - valueKind
        - widgetHint
        - mandatory
        - cardinality
        - validationRules
        - accessMode
        - disqualificationBehavior
        - sortOrder
      properties:
        id:
          type: string
          format: uuid
        attributePath:
          $ref: '#/components/schemas/AttributePath'
        label:
          type: string
        description:
          type: string
          nullable: true
        valueKind:
          $ref: '#/components/schemas/AttributeValueKind'
        widgetHint:
          $ref: '#/components/schemas/AttributeWidgetHint'
        mandatory:
          type: boolean
        cardinality:
          $ref: '#/components/schemas/AttributeCardinality'
        formatHint:
          type: string
          nullable: true
        entryCodes:
          type: array
          items:
            type: string
        entryCodeLabels:
          type: object
          nullable: true
          additionalProperties:
            type: string
        unit:
          type: string
          nullable: true
        placeholder:
          type: string
          nullable: true
        defaultValue:
          allOf:
            - $ref: '#/components/schemas/FieldValue'
          nullable: true
        validationRules:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationRule'
        accessMode:
          $ref: '#/components/schemas/FieldAccessMode'
        visibilityCondition:
          allOf:
            - $ref: '#/components/schemas/FieldCondition'
          nullable: true
        qualificationCondition:
          allOf:
            - $ref: '#/components/schemas/FieldCondition'
          nullable: true
        disqualificationBehavior:
          $ref: '#/components/schemas/DisqualificationBehavior'
        sortOrder:
          type: integer

    FieldValue:
      description: |
        Tagged-variant field value. Each variant carries the typed payload for one
        [AttributeValueKind] / cardinality / reference shape. The variant is identified by a
        `type` discriminator on the wire.
      oneOf:
        - $ref: '#/components/schemas/FieldValueAbsent'
        - $ref: '#/components/schemas/FieldValueText'
        - $ref: '#/components/schemas/FieldValueNumber'
        - $ref: '#/components/schemas/FieldValueBool'
        - $ref: '#/components/schemas/FieldValueDate'
        - $ref: '#/components/schemas/FieldValueDateTime'
        - $ref: '#/components/schemas/FieldValueCode'
        - $ref: '#/components/schemas/FieldValueMulti'
        - $ref: '#/components/schemas/FieldValueEvidenceRef'
        - $ref: '#/components/schemas/FieldValueCredentialRef'
        - $ref: '#/components/schemas/FieldValueArtifactRef'
      discriminator:
        propertyName: type
        mapping:
          Absent: '#/components/schemas/FieldValueAbsent'
          Text: '#/components/schemas/FieldValueText'
          Number: '#/components/schemas/FieldValueNumber'
          Bool: '#/components/schemas/FieldValueBool'
          Date: '#/components/schemas/FieldValueDate'
          DateTime: '#/components/schemas/FieldValueDateTime'
          Code: '#/components/schemas/FieldValueCode'
          Multi: '#/components/schemas/FieldValueMulti'
          EvidenceRef: '#/components/schemas/FieldValueEvidenceRef'
          CredentialRef: '#/components/schemas/FieldValueCredentialRef'
          ArtifactRef: '#/components/schemas/FieldValueArtifactRef'

    FieldValueAbsent:
      type: object
      description: Sentinel for an unset field. No value has been supplied.
      required: [type]
      properties:
        type:
          type: string
          enum: [Absent]

    FieldValueText:
      type: object
      description: A plain text value (maps to STRING / PICKLIST / free-form text inputs).
      required: [type, value]
      properties:
        type:
          type: string
          enum: [Text]
        value:
          type: string

    FieldValueNumber:
      type: object
      description: A numeric value.
      required: [type, value]
      properties:
        type:
          type: string
          enum: [Number]
        value:
          type: number
          format: double

    FieldValueBool:
      type: object
      description: A boolean value.
      required: [type, value]
      properties:
        type:
          type: string
          enum: [Bool]
        value:
          type: boolean

    FieldValueDate:
      type: object
      description: A date without time component (ISO-8601 `YYYY-MM-DD`).
      required: [type, value]
      properties:
        type:
          type: string
          enum: [Date]
        value:
          type: string
          format: date

    FieldValueDateTime:
      type: object
      description: An instant in time (ISO-8601 timestamp with offset).
      required: [type, value]
      properties:
        type:
          type: string
          enum: [DateTime]
        value:
          type: string
          format: date-time

    FieldValueCode:
      type: object
      description: A coded value drawn from a controlled vocabulary (entry code / SKOS concept).
      required: [type, code]
      properties:
        type:
          type: string
          enum: [Code]
        code:
          type: string
        scheme:
          type: string
          nullable: true

    FieldValueMulti:
      type: object
      description: Multiple values for a LIST-cardinality attribute. Element order is preserved.
      required: [type, values]
      properties:
        type:
          type: string
          enum: [Multi]
        values:
          type: array
          items:
            $ref: '#/components/schemas/FieldValue'

    FieldValueEvidenceRef:
      type: object
      description: |
        A reference to an evidence attachment. The payload itself is stored out-of-band; only
        the reference flows through the session.
      required: [type, evidenceId, mediaType]
      properties:
        type:
          type: string
          enum: [EvidenceRef]
        evidenceId:
          type: string
          format: uuid
        mediaType:
          type: string
          description: IANA media type of the referenced artifact (e.g. `application/pdf`).

    FieldValueCredentialRef:
      type: object
      description: A reference to a credential presented by the subject.
      required: [type, credentialId, format]
      properties:
        type:
          type: string
          enum: [CredentialRef]
        credentialId:
          type: string
        format:
          type: string
          description: Wire format (e.g. `jwt_vc_json`, `mso_mdoc`, `dc+sd-jwt`).

    FieldValueArtifactRef:
      type: object
      description: A reference to an artifact produced by a `ProduceArtifact` step action.
      required: [type, artifactId, kind]
      properties:
        type:
          type: string
          enum: [ArtifactRef]
        artifactId:
          type: string
          format: uuid
        kind:
          $ref: '#/components/schemas/ArtifactKind'

    FieldValidationError:
      type: object
      description: A single validation error against a field.
      required: [code, message, source]
      properties:
        code:
          type: string
        message:
          type: string
        source:
          $ref: '#/components/schemas/FieldValidationSource'
        details:
          type: object
          additionalProperties:
            type: string

    FieldTargetedServerError:
      type: object
      description: A server-side error targeted at a specific field path.
      required: [fieldPath, errors]
      properties:
        fieldPath:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationError'

    StepActionResult:
      description: |
        Tagged-variant result produced by a completed step action. The variant tag must match
        the declared `StepAction` variant on the resolved form. The variant is identified by a
        `type` discriminator on the wire.
      oneOf:
        - $ref: '#/components/schemas/StepActionResultCredentialReceived'
        - $ref: '#/components/schemas/StepActionResultEvidenceAttached'
        - $ref: '#/components/schemas/StepActionResultSignatureOrSealApplied'
        - $ref: '#/components/schemas/StepActionResultPolicyEvaluated'
        - $ref: '#/components/schemas/StepActionResultArtifactProduced'
      discriminator:
        propertyName: type
        mapping:
          CredentialReceived: '#/components/schemas/StepActionResultCredentialReceived'
          EvidenceAttached: '#/components/schemas/StepActionResultEvidenceAttached'
          SignatureOrSealApplied: '#/components/schemas/StepActionResultSignatureOrSealApplied'
          PolicyEvaluated: '#/components/schemas/StepActionResultPolicyEvaluated'
          ArtifactProduced: '#/components/schemas/StepActionResultArtifactProduced'

    StepActionResultCredentialReceived:
      type: object
      description: Outcome of a `RequestCredential` action, a credential presentation was received.
      required: [type, credentialRef]
      properties:
        type:
          type: string
          enum: [CredentialReceived]
        credentialRef:
          $ref: '#/components/schemas/FieldValue'
        receivedClaims:
          type: object
          nullable: true
          additionalProperties:
            $ref: '#/components/schemas/FieldValue'
        presentedCredential:
          allOf:
            - $ref: '#/components/schemas/PresentedCredentialClaims'
          nullable: true
          description: |
            Raw presented credential payload. When non-null the credential bridge projects
            claims onto form attributes and fills `receivedClaims` / `receivedClaimProvenance`.
        receivedClaimProvenance:
          type: object
          description: |
            Per-attribute provenance keyed by the form attribute path that received the
            value. Used by the side-effect engine to lock written fields with
            CREDENTIAL_PRESENTATION.
          additionalProperties:
            $ref: '#/components/schemas/CredentialClaimProvenance'

    StepActionResultEvidenceAttached:
      type: object
      description: Outcome of a `RequireEvidence` action, an evidence attachment was accepted.
      required: [type, evidenceRef]
      properties:
        type:
          type: string
          enum: [EvidenceAttached]
        evidenceRef:
          $ref: '#/components/schemas/FieldValue'
        description:
          type: string
          nullable: true

    StepActionResultSignatureOrSealApplied:
      type: object
      description: Outcome of a `RequireSignatureOrSeal` action, a signature or seal was produced.
      required: [type, kind, assuranceLevel, signatureLocator]
      properties:
        type:
          type: string
          enum: [SignatureOrSealApplied]
        kind:
          $ref: '#/components/schemas/SignatureOrSealKind'
        assuranceLevel:
          $ref: '#/components/schemas/AssuranceLevel'
        signerSubject:
          type: string
          nullable: true
        signatureLocator:
          type: string

    StepActionResultPolicyEvaluated:
      type: object
      description: Outcome of a `PolicyGate` action, the policy engine returned a decision.
      required: [type, decision]
      properties:
        type:
          type: string
          enum: [PolicyEvaluated]
        decision:
          $ref: '#/components/schemas/PolicyDecision'
        reason:
          type: string
          nullable: true

    StepActionResultArtifactProduced:
      type: object
      description: Outcome of a `ProduceArtifact` action, an artifact was produced and is retrievable by reference.
      required: [type, artifactRef]
      properties:
        type:
          type: string
          enum: [ArtifactProduced]
        artifactRef:
          $ref: '#/components/schemas/FieldValue'

    StepActionPrompt:
      description: |
        Tagged-variant prompt returned when starting a step action. Variants: `None`,
        `PresentationRequest`, `EvidenceUpload`, `SignatureChallenge`, `ArtifactHandle`. The
        variant is identified by a `type` discriminator on the wire.
      oneOf:
        - $ref: '#/components/schemas/StepActionPromptNone'
        - $ref: '#/components/schemas/StepActionPromptPresentationRequest'
        - $ref: '#/components/schemas/StepActionPromptEvidenceUpload'
        - $ref: '#/components/schemas/StepActionPromptSignatureChallenge'
        - $ref: '#/components/schemas/StepActionPromptArtifactHandle'
      discriminator:
        propertyName: type
        mapping:
          None: '#/components/schemas/StepActionPromptNone'
          PresentationRequest: '#/components/schemas/StepActionPromptPresentationRequest'
          EvidenceUpload: '#/components/schemas/StepActionPromptEvidenceUpload'
          SignatureChallenge: '#/components/schemas/StepActionPromptSignatureChallenge'
          ArtifactHandle: '#/components/schemas/StepActionPromptArtifactHandle'

    StepActionPromptNone:
      type: object
      description: No client-facing prompt, the action ran synchronously or awaits server-side orchestration.
      required: [type]
      properties:
        type:
          type: string
          enum: [None]

    StepActionPromptPresentationRequest:
      type: object
      description: A verifiable-presentation request URI the wallet consumes.
      required: [type, requestUri]
      properties:
        type:
          type: string
          enum: [PresentationRequest]
        requestUri:
          type: string
        nonce:
          type: string
          nullable: true

    StepActionPromptEvidenceUpload:
      type: object
      description: Where and how to upload an evidence attachment.
      required: [type, uploadUri]
      properties:
        type:
          type: string
          enum: [EvidenceUpload]
        uploadUri:
          type: string
        acceptedMediaTypes:
          type: array
          items:
            type: string

    StepActionPromptSignatureChallenge:
      type: object
      description: The challenge / document-to-sign reference for a signature/seal step action.
      required: [type, challenge]
      properties:
        type:
          type: string
          enum: [SignatureChallenge]
        challenge:
          type: string
        hashAlgorithm:
          type: string
          nullable: true

    StepActionPromptArtifactHandle:
      type: object
      description: Where the produced artifact can be retrieved once ready.
      required: [type, locator]
      properties:
        type:
          type: string
          enum: [ArtifactHandle]
        locator:
          type: string

    StepValidationErrors:
      type: object
      description: |
        Map from field path to the list of validation error messages produced by `validateStep`.
        Empty map when the step is valid.
      additionalProperties:
        type: array
        items:
          type: string

    FieldValidationErrors:
      type: array
      description: |
        Validation error messages produced by `validateField`. Empty array when the field is
        valid.
      items:
        type: string

    FormSession:
      type: object
      description: |
        Runtime form session for the headless engine. Tracks the user's progress through a
        [ResolvedForm] including current step, field values, validation errors, per-field
        runtime states, per-action lifecycle states, operational phase, and progress.
      required:
        - id
        - tenantId
        - formDefinitionId
        - resolvedForm
        - currentStepIndex
        - fieldValues
        - fieldErrors
        - fieldRuntimeStates
        - stepActionStates
        - phaseState
        - progress
        - status
        - createdAt
        - updatedAt
        - revision
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
        actorPrincipalId:
          type: string
          nullable: true
          description: |
            Opaque principal subject of the actor that created the session. Frozen at
            session creation; downstream step-action and policy evaluation use this rather
            than the current request execution context. Never parsed as a UUID.
        actorRoles:
          type: array
          items:
            type: string
          description: Role identifiers carried by the creating actor at session creation. Frozen for the session's lifetime.
        formDefinitionId:
          type: string
          format: uuid
        resolvedForm:
          $ref: '#/components/schemas/ResolvedForm'
        currentStepIndex:
          type: integer
          minimum: 0
        fieldValues:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldValue'
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        fieldRuntimeStates:
          type: object
          description: Per-field runtime state keyed by attribute path.
          additionalProperties:
            $ref: '#/components/schemas/FieldRuntimeState'
        stepActionStates:
          type: object
          description: Per-step-action execution state keyed by action id (UUID string).
          additionalProperties:
            $ref: '#/components/schemas/StepActionState'
        phaseState:
          $ref: '#/components/schemas/FormSessionPhaseState'
        progress:
          $ref: '#/components/schemas/FormSessionProgress'
        status:
          $ref: '#/components/schemas/FormSessionStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        revision:
          type: integer
          format: int64
          minimum: 0

    FormSessionPhaseState:
      type: object
      description: |
        Operational phase, last operation, and recoverable failure snapshot. Independent of
        session status: a session can have `status = IN_PROGRESS` while `phase = FAILED`,
        representing a recoverable validation failure that the next accepted user update clears.
      required: [phase]
      properties:
        phase:
          $ref: '#/components/schemas/FormSessionPhase'
        operation:
          allOf:
            - $ref: '#/components/schemas/FormSessionOperation'
          nullable: true
        activeStepIndex:
          type: integer
          nullable: true
        activeActionId:
          type: string
          format: uuid
          nullable: true
        reasons:
          type: array
          items:
            type: string
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FieldValidationError'
        startedAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true

    FormSessionProgress:
      type: object
      description: Snapshot of step/field/action progress, recomputed after every session mutation.
      properties:
        currentStepIndex:
          type: integer
          default: 0
        currentStepNumber:
          type: integer
          default: 1
        totalSteps:
          type: integer
          default: 0
        isFirstStep:
          type: boolean
          default: true
        isLastStep:
          type: boolean
          default: true
        completedStepCount:
          type: integer
          default: 0
        currentStep:
          $ref: '#/components/schemas/FormStepProgress'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/FormStepProgress'
        totalFields:
          type: integer
          default: 0
        qualifiedFields:
          type: integer
          default: 0
        visibleFields:
          type: integer
          default: 0
        requiredFields:
          type: integer
          default: 0
        completedRequiredFields:
          type: integer
          default: 0
        validFields:
          type: integer
          default: 0
        invalidFields:
          type: integer
          default: 0
        dirtyFields:
          type: integer
          default: 0
        totalRequiredActions:
          type: integer
          default: 0
        completedRequiredActions:
          type: integer
          default: 0
        overallCompletionRatio:
          type: number
          format: double
          default: 0
        complete:
          type: boolean
          default: false

    FormStepProgress:
      type: object
      description: Per-step progress within a [FormSessionProgress].
      properties:
        stepIndex:
          type: integer
          default: 0
        stepNumber:
          type: integer
          default: 1
        totalFields:
          type: integer
          default: 0
        qualifiedFields:
          type: integer
          default: 0
        visibleFields:
          type: integer
          default: 0
        requiredFields:
          type: integer
          default: 0
        completedRequiredFields:
          type: integer
          default: 0
        validFields:
          type: integer
          default: 0
        invalidFields:
          type: integer
          default: 0
        unspecifiedFields:
          type: integer
          default: 0
        dirtyFields:
          type: integer
          default: 0
        requiredActions:
          type: integer
          default: 0
        completedRequiredActions:
          type: integer
          default: 0
        completionRatio:
          type: number
          format: double
          default: 0
        complete:
          type: boolean
          default: false

    FormSessionFieldSnapshot:
      type: object
      description: Per-field client snapshot (path, value, runtime state, errors).
      required: [path, value, runtimeState]
      properties:
        path:
          type: string
        value:
          $ref: '#/components/schemas/FieldValue'
        runtimeState:
          $ref: '#/components/schemas/FieldRuntimeState'
        errors:
          type: array
          items:
            type: string

    FormSessionCommandCapability:
      type: string
      description: A command the client is currently allowed to invoke on this session.

    FormSessionSnapshot:
      type: object
      description: |
        Client-oriented snapshot of a [FormSession]. Carries state, progress, allowed commands,
        and revision. Snapshots omit raw field values, fetch the full session for those.
      required:
        - sessionId
        - tenantId
        - formDefinitionId
        - status
        - phaseState
        - currentStepIndex
        - progress
        - fields
        - allowedCommands
        - revision
        - updatedAt
      properties:
        sessionId:
          type: string
          format: uuid
        tenantId:
          type: string
        formDefinitionId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/FormSessionStatus'
        phaseState:
          $ref: '#/components/schemas/FormSessionPhaseState'
        currentStepIndex:
          type: integer
          minimum: 0
        currentStepId:
          type: string
          format: uuid
          nullable: true
        progress:
          $ref: '#/components/schemas/FormSessionProgress'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FormSessionFieldSnapshot'
        allowedCommands:
          type: array
          items:
            $ref: '#/components/schemas/FormSessionCommandCapability'
        revision:
          type: integer
          format: int64
          minimum: 0
        updatedAt:
          type: string
          format: date-time

    FormSessionEventType:
      type: string
      description: Type of an appended session event.

    FormSessionEvent:
      type: object
      description: Append-only session event. Metadata carries identifiers and counts only, never field values, claims, signatures, or evidence payloads.
      required: [id, tenantId, sessionId, sequence, type, metadata, occurredAt]
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
        sessionId:
          type: string
          format: uuid
        sequence:
          type: integer
          format: int64
          minimum: 0
        type:
          $ref: '#/components/schemas/FormSessionEventType'
        actorId:
          type: string
          nullable: true
          description: Principal subject that triggered the event. Opaque string, NOT a UUID.
        metadata:
          type: object
          additionalProperties:
            type: string
        occurredAt:
          type: string
          format: date-time

    FormSessionDiff:
      type: object
      description: Per-mutation diff between a session's prior and post revisions.
      required:
        - beforeRevision
        - afterRevision
        - changedFieldPaths
        - changedRuntimeStatePaths
        - changedErrorPaths
        - progressChanged
        - phaseChanged
        - statusChanged
      properties:
        beforeRevision:
          type: integer
          format: int64
          minimum: 0
        afterRevision:
          type: integer
          format: int64
          minimum: 0
        changedFieldPaths:
          type: array
          items:
            type: string
        changedRuntimeStatePaths:
          type: array
          items:
            type: string
        changedErrorPaths:
          type: array
          items:
            type: string
        progressChanged:
          type: boolean
        phaseChanged:
          type: boolean
        statusChanged:
          type: boolean

    FormSessionMutationResult:
      type: object
      description: Returned by mutating session commands that compute a per-field diff (e.g. `updateFieldValues`).
      required: [session, snapshot, diff]
      properties:
        session:
          $ref: '#/components/schemas/FormSession'
        snapshot:
          $ref: '#/components/schemas/FormSessionSnapshot'
        diff:
          $ref: '#/components/schemas/FormSessionDiff'

    CredentialClaimPath:
      type: object
      description: |
        Path of a single claim inside a presented or issued credential. Stored as an
        explicit list of segments so namespace-style claim keys (e.g. mDL `org.iso.18013.5.1`)
        round-trip without ambiguity. Do NOT serialize as a dot-separated string.
      required: [segments]
      properties:
        segments:
          type: array
          minItems: 1
          items:
            type: string

    FormAttributeMapping:
      type: object
      description: |
        Direction-agnostic mapping between a form attribute path and a credential claim path.
      required: [attributePath, claimPath]
      properties:
        attributePath:
          type: string
          description: The form attribute path this mapping references.
        claimPath:
          $ref: '#/components/schemas/CredentialClaimPath'
        semanticTermUris:
          type: array
          uniqueItems: true
          items:
            type: string
        required:
          type: boolean
          default: false
        priority:
          type: integer
          default: 0

    FormCredentialBinding:
      oneOf:
        - $ref: '#/components/schemas/FormCredentialBindingInput'
        - $ref: '#/components/schemas/FormCredentialBindingOutput'
      discriminator:
        propertyName: type
        mapping:
          INPUT: '#/components/schemas/FormCredentialBindingInput'
          OUTPUT: '#/components/schemas/FormCredentialBindingOutput'

    FormCredentialBindingOutput:
      type: object
      description: |
        Output-credential binding. A `ProduceArtifact(CREDENTIAL)` step action selects the
        OUTPUT binding by `bindingId` to map current session values onto a credential subject
        and trigger issuance. `credentialConfigurationId` and `outputVocabularyId` are required.
      required: [type, id, credentialType, credentialConfigurationId, outputVocabularyId, mappings]
      properties:
        type:
          type: string
          enum: [OUTPUT]
        id:
          type: string
        credentialType:
          type: string
        credentialConfigurationId:
          type: string
        outputVocabularyId:
          type: string
          format: uuid
        issuerId:
          type: string
          nullable: true
        credentialFormat:
          type: string
          nullable: true
        acceptedVocabularyIds:
          type: array
          uniqueItems: true
          items:
            type: string
            format: uuid
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/FormAttributeMapping'

    PresentedCredentialClaim:
      type: object
      description: One claim extracted from a presented credential, ready for mapping.
      required: [path, value]
      properties:
        path:
          $ref: '#/components/schemas/CredentialClaimPath'
        value:
          $ref: '#/components/schemas/FieldValue'
        semanticTermUris:
          type: array
          uniqueItems: true
          items:
            type: string

    PresentedCredentialClaims:
      type: object
      description: Set of claims extracted from a single presented credential.
      required: [credentialType, credentialFormat, claims]
      properties:
        bindingId:
          type: string
          nullable: true
        credentialType:
          type: string
        credentialFormat:
          type: string
        vocabularyId:
          type: string
          format: uuid
          nullable: true
        claims:
          type: array
          items:
            $ref: '#/components/schemas/PresentedCredentialClaim'

    CredentialClaimProvenance:
      type: object
      description: |
        Provenance metadata attached to a form attribute value when it came from a verified
        credential presentation.
      required: [bindingId, credentialType, credentialFormat, credentialId, claimPath]
      properties:
        bindingId:
          type: string
        credentialType:
          type: string
        credentialFormat:
          type: string
        credentialId:
          type: string
        claimPath:
          $ref: '#/components/schemas/CredentialClaimPath'
        semanticTermUris:
          type: array
          uniqueItems: true
          items:
            type: string

    FieldValueProvenanceSource:
      type: string
      description: The originating source of a field value.
      enum: [DEFAULT, USER, ACTION_SIDE_EFFECT, CREDENTIAL_PRESENTATION, SYSTEM]

    FieldValueProvenance:
      type: object
      description: Provenance information attached to a runtime field value.
      required: [source]
      properties:
        source:
          $ref: '#/components/schemas/FieldValueProvenanceSource'
        credential:
          allOf:
            - $ref: '#/components/schemas/CredentialClaimProvenance'
          nullable: true

    FieldLockReason:
      type: string
      description: |
        Reason a field is locked at runtime. Locked fields reject user writes; only the
        action that originally locked the field (or a server-side write authorized by
        policy) may modify the value.
      enum: [CREDENTIAL_PRESENTATION, SERVER_POLICY]

    AttributePath:
      type: string
      description: |
        Stringified attribute path (segments joined by `.`). E.g. `person.firstName` or
        `address.street`. Treat as opaque on the wire; the semantic-attributes layer parses
        and validates the segment structure.

    AttributeValueKind:
      type: string
      description: |
        The fundamental data type of a semantic attribute's value. Maps to OCA capture
        base attribute types.
      enum:
        - STRING
        - NUMBER
        - BOOLEAN
        - BINARY
        - DATE_TIME
        - DATE
        - TIME
        - REFERENCE
        - ARRAY
        - UNKNOWN

    AttributeWidgetHint:
      type: string
      description: The renderer-facing widget hint for an attribute.
      enum:
        - TEXT_INPUT
        - TEXT_AREA
        - PICKLIST
        - CHECKBOX
        - RADIO_GROUP
        - DATE_PICKER
        - TIME_PICKER
        - DATE_TIME_PICKER
        - FILE_UPLOAD
        - SIGNATURE
        - HIDDEN

    AttributeCardinality:
      type: string
      description: Whether an attribute holds a single value or multiple values.
      enum:
        - SINGLE
        - MULTIPLE

    FieldAccessMode:
      type: string
      description: |
        Runtime field access mode of a field present in a [ResolvedForm]. Two-valued on
        the wire, fields hidden by policy are omitted from the resolved tree entirely.
      enum:
        - EDITABLE
        - READ_ONLY

    MandatoryOverride:
      type: string
      description: |
        Per-form override of a canonical attribute's `mandatory` flag. `INHERIT` falls
        through to the canonical attribute value; `MANDATORY` / `OPTIONAL` force the
        outcome for this form only.
      enum:
        - INHERIT
        - MANDATORY
        - OPTIONAL

    DisqualificationBehavior:
      type: string
      description: |
        How the engine treats a field whose qualification condition fails. `HIDE_*`
        removes the field from the visible tree; `DISABLE_*` leaves it visible but
        read-only.
      enum:
        - HIDE_KEEP_VALUE
        - HIDE_RESET_TO_DEFAULT
        - HIDE_CLEAR_VALUE
        - DISABLE_KEEP_VALUE
        - DISABLE_RESET_TO_DEFAULT
        - DISABLE_CLEAR_VALUE

    ArtifactKind:
      type: string
      description: Kind of artifact a `ProduceArtifact` step action mints.
      enum:
        - CREDENTIAL
        - PDF
        - EVIDENCE
        - DOSSIER
        - AUDIT_RECORD

    AssuranceLevel:
      type: string
      description: eIDAS-style assurance level for a signature or seal.
      enum:
        - SIMPLE
        - ADVANCED
        - QUALIFIED

    SignatureOrSealKind:
      type: string
      description: Whether a signature/seal step produces a personal signature or an organisational seal.
      enum:
        - SIGNATURE
        - SEAL

    PolicyDecision:
      type: string
      description: Outcome of evaluating a synchronous policy gate.
      enum:
        - ALLOW
        - DENY
        - NOT_APPLICABLE

    FieldValidationSource:
      type: string
      description: Source of a validation error (local UI checks vs server-issued).
      enum:
        - LOCAL
        - REMOTE

    FormSessionOperation:
      type: string
      description: The session-mutating operation that last updated the phase state.
      enum:
        - CREATE_SESSION
        - GET_SESSION
        - UPDATE_FIELD_VALUES
        - VALIDATE_FIELD
        - VALIDATE_STEP
        - NAVIGATE_TO_STEP
        - START_STEP_ACTION
        - COMPLETE_STEP_ACTION
        - CANCEL_STEP_ACTION
        - SUBMIT_FORM
        - CANCEL_SESSION
        - APPLY_SERVER_FIELD_ERRORS
        - APPLY_ACTION_EFFECTS

    FieldRuntimeState:
      type: object
      description: |
        Runtime state of a single form field within a session. Carried alongside the
        field's value map; tracks qualification, visibility, validation state, and
        per-source errors.
      required: [path, qualified, visible, disabled]
      properties:
        path:
          type: string
        qualified:
          type: boolean
        visible:
          type: boolean
        disabled:
          type: boolean
        touched:
          type: boolean
          default: false
        dirty:
          type: boolean
          default: false
        invalidated:
          type: boolean
          default: false
        localValidationState:
          $ref: '#/components/schemas/FieldValidationState'
        remoteValidationState:
          $ref: '#/components/schemas/FieldValidationState'
        localErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationError'
        remoteErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationError'
        lastUpdatedBy:
          $ref: '#/components/schemas/FieldUpdateSource'
        locked:
          type: boolean
          default: false
          description: |
            When true the field rejects user writes regardless of [FieldAccessMode]. Set by
            the credential-prefill side effect and by server-policy lock decisions.
        lockReason:
          allOf:
            - $ref: '#/components/schemas/FieldLockReason'
          nullable: true
        valueProvenance:
          allOf:
            - $ref: '#/components/schemas/FieldValueProvenance'
          nullable: true

    FieldValidationState:
      type: string
      description: Validation state of a single field.
      enum:
        - UNSPECIFIED
        - VALIDATING
        - VALID
        - INVALID

    FieldUpdateSource:
      type: string
      description: Operation that last mutated a [FieldRuntimeState].
      enum:
        - INITIAL
        - USER
        - INVALIDATION
        - REMOTE_VALIDATION
        - STEP_VALIDATION
        - SUBMIT_VALIDATION
        - ACTION_SIDE_EFFECT
        - SYSTEM_DISQUALIFICATION
        - CREDENTIAL_PRESENTATION

    StepActionState:
      type: object
      description: |
        Per-action session state, keyed by step-action id in
        [FormSession.stepActionStates]. Carries the lifecycle status, the produced result
        when completed, timing, and any error message from a failed attempt.
      required: [actionId, status]
      properties:
        actionId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/StepActionStatus'
        result:
          allOf:
            - $ref: '#/components/schemas/StepActionResult'
          nullable: true
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        errorMessage:
          type: string
          nullable: true

    FieldValidationRule:
      description: |
        Tagged-variant declarative validation rule attached to a field. Each variant
        describes a constraint compiled by the validation engine at runtime.
      oneOf:
        - $ref: '#/components/schemas/FieldValidationRuleRequired'
        - $ref: '#/components/schemas/FieldValidationRuleMinLength'
        - $ref: '#/components/schemas/FieldValidationRuleMaxLength'
        - $ref: '#/components/schemas/FieldValidationRulePattern'
        - $ref: '#/components/schemas/FieldValidationRuleRange'
        - $ref: '#/components/schemas/FieldValidationRuleEmail'
        - $ref: '#/components/schemas/FieldValidationRuleUri'
        - $ref: '#/components/schemas/FieldValidationRuleCustom'
      discriminator:
        propertyName: type
        mapping:
          Required: '#/components/schemas/FieldValidationRuleRequired'
          MinLength: '#/components/schemas/FieldValidationRuleMinLength'
          MaxLength: '#/components/schemas/FieldValidationRuleMaxLength'
          Pattern: '#/components/schemas/FieldValidationRulePattern'
          Range: '#/components/schemas/FieldValidationRuleRange'
          Email: '#/components/schemas/FieldValidationRuleEmail'
          Uri: '#/components/schemas/FieldValidationRuleUri'
          Custom: '#/components/schemas/FieldValidationRuleCustom'

    FieldValidationRuleRequired:
      type: object
      description: The field must have a non-empty value.
      required: [type]
      properties:
        type:
          type: string
          enum: [Required]
        message:
          type: string
          nullable: true

    FieldValidationRuleMinLength:
      type: object
      description: The field value must have at least `min` characters.
      required: [type, min]
      properties:
        type:
          type: string
          enum: [MinLength]
        min:
          type: integer
        message:
          type: string
          nullable: true

    FieldValidationRuleMaxLength:
      type: object
      description: The field value must have at most `max` characters.
      required: [type, max]
      properties:
        type:
          type: string
          enum: [MaxLength]
        max:
          type: integer
        message:
          type: string
          nullable: true

    FieldValidationRulePattern:
      type: object
      description: The field value must match the given `regex` pattern.
      required: [type, regex]
      properties:
        type:
          type: string
          enum: [Pattern]
        regex:
          type: string
        message:
          type: string
          nullable: true

    FieldValidationRuleRange:
      type: object
      description: The numeric field value must be within the specified `min`..`max` range.
      required: [type]
      properties:
        type:
          type: string
          enum: [Range]
        min:
          type: number
          format: double
          nullable: true
        max:
          type: number
          format: double
          nullable: true
        message:
          type: string
          nullable: true

    FieldValidationRuleEmail:
      type: object
      description: The field value must be a valid email address.
      required: [type]
      properties:
        type:
          type: string
          enum: [Email]
        message:
          type: string
          nullable: true

    FieldValidationRuleUri:
      type: object
      description: The field value must be a valid URI.
      required: [type]
      properties:
        type:
          type: string
          enum: [Uri]
        message:
          type: string
          nullable: true

    FieldValidationRuleCustom:
      type: object
      description: A custom validation rule identified by `validatorId` with optional parameters.
      required: [type, validatorId]
      properties:
        type:
          type: string
          enum: [Custom]
        validatorId:
          type: string
        params:
          type: object
          nullable: true
          additionalProperties:
            type: string
        message:
          type: string
          nullable: true

    FieldCondition:
      description: |
        Tagged-variant boolean expression over field values. Evaluated by the condition
        evaluator against current session values. Comparison variants carry typed
        [FieldValue] operands.
      oneOf:
        - $ref: '#/components/schemas/FieldConditionEquals'
        - $ref: '#/components/schemas/FieldConditionNotEmpty'
        - $ref: '#/components/schemas/FieldConditionContains'
        - $ref: '#/components/schemas/FieldConditionGreaterThan'
        - $ref: '#/components/schemas/FieldConditionLessThan'
        - $ref: '#/components/schemas/FieldConditionAnd'
        - $ref: '#/components/schemas/FieldConditionOr'
        - $ref: '#/components/schemas/FieldConditionNot'
      discriminator:
        propertyName: type
        mapping:
          Equals: '#/components/schemas/FieldConditionEquals'
          NotEmpty: '#/components/schemas/FieldConditionNotEmpty'
          Contains: '#/components/schemas/FieldConditionContains'
          GreaterThan: '#/components/schemas/FieldConditionGreaterThan'
          LessThan: '#/components/schemas/FieldConditionLessThan'
          And: '#/components/schemas/FieldConditionAnd'
          Or: '#/components/schemas/FieldConditionOr'
          Not: '#/components/schemas/FieldConditionNot'

    FieldConditionEquals:
      type: object
      description: True when the field at `fieldPath` has a value equal to `value`.
      required: [type, fieldPath, value]
      properties:
        type:
          type: string
          enum: [Equals]
        fieldPath:
          $ref: '#/components/schemas/AttributePath'
        value:
          $ref: '#/components/schemas/FieldValue'

    FieldConditionNotEmpty:
      type: object
      description: True when the field at `fieldPath` has any value other than `Absent`.
      required: [type, fieldPath]
      properties:
        type:
          type: string
          enum: [NotEmpty]
        fieldPath:
          $ref: '#/components/schemas/AttributePath'

    FieldConditionContains:
      type: object
      description: True when the field at `fieldPath` contains `value`.
      required: [type, fieldPath, value]
      properties:
        type:
          type: string
          enum: [Contains]
        fieldPath:
          $ref: '#/components/schemas/AttributePath'
        value:
          $ref: '#/components/schemas/FieldValue'

    FieldConditionGreaterThan:
      type: object
      description: True when the numeric/temporal value at `fieldPath` is strictly greater than `value`.
      required: [type, fieldPath, value]
      properties:
        type:
          type: string
          enum: [GreaterThan]
        fieldPath:
          $ref: '#/components/schemas/AttributePath'
        value:
          $ref: '#/components/schemas/FieldValue'

    FieldConditionLessThan:
      type: object
      description: True when the numeric/temporal value at `fieldPath` is strictly less than `value`.
      required: [type, fieldPath, value]
      properties:
        type:
          type: string
          enum: [LessThan]
        fieldPath:
          $ref: '#/components/schemas/AttributePath'
        value:
          $ref: '#/components/schemas/FieldValue'

    FieldConditionAnd:
      type: object
      description: True when all `conditions` evaluate to true.
      required: [type, conditions]
      properties:
        type:
          type: string
          enum: [And]
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/FieldCondition'

    FieldConditionOr:
      type: object
      description: True when at least one of `conditions` evaluates to true.
      required: [type, conditions]
      properties:
        type:
          type: string
          enum: [Or]
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/FieldCondition'

    FieldConditionNot:
      type: object
      description: True when `condition` evaluates to false.
      required: [type, condition]
      properties:
        type:
          type: string
          enum: [Not]
        condition:
          $ref: '#/components/schemas/FieldCondition'

    StepAction:
      description: |
        Tagged union of step-action variants. Each variant carries the configuration the
        runtime needs to launch the action and (where asynchronous) await its result.
      oneOf:
        - $ref: '#/components/schemas/StepActionRequestCredential'
        - $ref: '#/components/schemas/StepActionRequireEvidence'
        - $ref: '#/components/schemas/StepActionRequireSignatureOrSeal'
        - $ref: '#/components/schemas/StepActionPolicyGate'
        - $ref: '#/components/schemas/StepActionProduceArtifact'
      discriminator:
        propertyName: type
        mapping:
          RequestCredential: '#/components/schemas/StepActionRequestCredential'
          RequireEvidence: '#/components/schemas/StepActionRequireEvidence'
          RequireSignatureOrSeal: '#/components/schemas/StepActionRequireSignatureOrSeal'
          PolicyGate: '#/components/schemas/StepActionPolicyGate'
          ProduceArtifact: '#/components/schemas/StepActionProduceArtifact'

    StepActionRequestCredential:
      type: object
      description: Requests a credential presentation from the subject's wallet.
      required: [type, id, credentialType]
      properties:
        type:
          type: string
          enum: [RequestCredential]
        id:
          type: string
          format: uuid
        required:
          type: boolean
          default: true
        credentialType:
          type: string
        bindingId:
          type: string
          nullable: true
        sideEffects:
          type: array
          default: []
          description: Declarative effects applied to the form session when this action completes.
          items:
            $ref: '#/components/schemas/StepActionSideEffect'

    StepActionRequireEvidence:
      type: object
      description: Requires the subject to attach evidence (e.g. document upload).
      required: [type, id, evidenceType]
      properties:
        type:
          type: string
          enum: [RequireEvidence]
        id:
          type: string
          format: uuid
        required:
          type: boolean
          default: true
        evidenceType:
          type: string
        description:
          type: string
          nullable: true
        sideEffects:
          type: array
          default: []
          description: Declarative effects applied to the form session when this action completes.
          items:
            $ref: '#/components/schemas/StepActionSideEffect'

    StepActionRequireSignatureOrSeal:
      type: object
      description: Requires a signature or seal at the specified assurance level.
      required: [type, id, kind, assuranceLevel]
      properties:
        type:
          type: string
          enum: [RequireSignatureOrSeal]
        id:
          type: string
          format: uuid
        required:
          type: boolean
          default: true
        kind:
          $ref: '#/components/schemas/SignatureOrSealKind'
        assuranceLevel:
          $ref: '#/components/schemas/AssuranceLevel'
        sideEffects:
          type: array
          default: []
          description: Declarative effects applied to the form session when this action completes.
          items:
            $ref: '#/components/schemas/StepActionSideEffect'

    StepActionPolicyGate:
      type: object
      description: Synchronous policy evaluation gate.
      required: [type, id, policyId]
      properties:
        type:
          type: string
          enum: [PolicyGate]
        id:
          type: string
          format: uuid
        required:
          type: boolean
          default: true
        policyId:
          type: string
        description:
          type: string
          nullable: true
        sideEffects:
          type: array
          default: []
          description: Declarative effects applied to the form session when this action completes.
          items:
            $ref: '#/components/schemas/StepActionSideEffect'

    StepActionProduceArtifact:
      type: object
      description: Produces a governed artifact (credential, PDF, evidence record, dossier, audit record).
      required: [type, id, artifactKind]
      properties:
        type:
          type: string
          enum: [ProduceArtifact]
        id:
          type: string
          format: uuid
        required:
          type: boolean
          default: true
        artifactKind:
          $ref: '#/components/schemas/ArtifactKind'
        templateId:
          type: string
          nullable: true
        bindingId:
          type: string
          nullable: true
          description: |
            Selects the OUTPUT credential binding when `artifactKind = CREDENTIAL`. Required
            for credential artifacts; must be null for other artifact kinds until a
            non-credential binding feature is designed.
        sideEffects:
          type: array
          default: []
          description: Declarative effects applied to the form session when this action completes.
          items:
            $ref: '#/components/schemas/StepActionSideEffect'

    StepActionSideEffect:
      description: |
        Tagged union of declarative side effects attached to a [StepAction]. When the action
        completes with a matching result, the side-effect engine writes the projected payload
        into the form session's field-value map.
      oneOf:
        - $ref: '#/components/schemas/StepActionSideEffectApplyReceivedCredentialClaims'
        - $ref: '#/components/schemas/StepActionSideEffectWriteCredentialReference'
        - $ref: '#/components/schemas/StepActionSideEffectWriteEvidenceReference'
        - $ref: '#/components/schemas/StepActionSideEffectWriteArtifactReference'
        - $ref: '#/components/schemas/StepActionSideEffectWriteSignatureLocator'
        - $ref: '#/components/schemas/StepActionSideEffectWritePolicyDecision'
      discriminator:
        propertyName: type
        mapping:
          ApplyReceivedCredentialClaims: '#/components/schemas/StepActionSideEffectApplyReceivedCredentialClaims'
          WriteCredentialReference: '#/components/schemas/StepActionSideEffectWriteCredentialReference'
          WriteEvidenceReference: '#/components/schemas/StepActionSideEffectWriteEvidenceReference'
          WriteArtifactReference: '#/components/schemas/StepActionSideEffectWriteArtifactReference'
          WriteSignatureLocator: '#/components/schemas/StepActionSideEffectWriteSignatureLocator'
          WritePolicyDecision: '#/components/schemas/StepActionSideEffectWritePolicyDecision'

    StepActionSideEffectApplyReceivedCredentialClaims:
      type: object
      description: |
        Project selected received credential claims into the form session field-value map.
        Each target path must appear in the received claims map; missing keys are rejected
        only when `requireAllTargets` is true.
      required: [type, targetFieldPaths]
      properties:
        type:
          type: string
          enum: [ApplyReceivedCredentialClaims]
        targetFieldPaths:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AttributePath'
        requireAllTargets:
          type: boolean
          default: false

    StepActionSideEffectWriteCredentialReference:
      type: object
      description: Write the produced credential reference into the target field.
      required: [type, targetFieldPath]
      properties:
        type:
          type: string
          enum: [WriteCredentialReference]
        targetFieldPath:
          $ref: '#/components/schemas/AttributePath'

    StepActionSideEffectWriteEvidenceReference:
      type: object
      description: Write the produced evidence reference into the target field.
      required: [type, targetFieldPath]
      properties:
        type:
          type: string
          enum: [WriteEvidenceReference]
        targetFieldPath:
          $ref: '#/components/schemas/AttributePath'

    StepActionSideEffectWriteArtifactReference:
      type: object
      description: Write the produced artifact reference into the target field.
      required: [type, targetFieldPath]
      properties:
        type:
          type: string
          enum: [WriteArtifactReference]
        targetFieldPath:
          $ref: '#/components/schemas/AttributePath'

    StepActionSideEffectWriteSignatureLocator:
      type: object
      description: Write the signature or seal locator string into the target field.
      required: [type, targetFieldPath]
      properties:
        type:
          type: string
          enum: [WriteSignatureLocator]
        targetFieldPath:
          $ref: '#/components/schemas/AttributePath'

    StepActionSideEffectWritePolicyDecision:
      type: object
      description: Write the policy decision name into the target field.
      required: [type, targetFieldPath]
      properties:
        type:
          type: string
          enum: [WritePolicyDecision]
        targetFieldPath:
          $ref: '#/components/schemas/AttributePath'
    FormCredentialBindingInput:
      type: object
      description: |
        Presented-credential binding. Multiple INPUT bindings on the same form may target the
        same form attribute from different credential types, the runtime picks the binding
        matching the actually presented credential.
      required: [type, id, credentialType, mappings]
      properties:
        type:
          type: string
          enum: [INPUT]
        id:
          type: string
        credentialType:
          type: string
        credentialFormat:
          type: string
          nullable: true
        acceptedVocabularyIds:
          type: array
          uniqueItems: true
          items:
            type: string
            format: uuid
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/FormAttributeMapping'