forms-openapi.yml

openapi: 3.0.3
info:
  title: Forms API
  version: 0.1.0
  description: |
    Manage form definitions and form sessions. Definitions cover authoring, lifecycle, and
    resolution. Sessions cover runtime state: field values, validation, navigation,
    step-action lifecycle, and submission.

    ## Concurrency
    Mutating session endpoints support optimistic concurrency via `If-Match` carrying the session
    [revision]. A mismatch returns `412 Precondition Failed` with code `OPTIMISTIC_LOCK_CONFLICT`.
    Successful responses carry the new revision back via the `ETag` response header (RFC 7232
    strong validator), which clients use as the next request's `If-Match`.

    ## Idempotency
    Mutating session endpoints accept `Idempotency-Key`. The platform replays the original result
    when the same key is reused; reusing a key with a different request body returns `409` with code
    `IDEMPOTENCY_KEY_CONFLICT`.
servers:
  - url: http://localhost:8080/api/v1
    description: Local development.

security:
  - bearer: []

tags:
  - name: Forms
    description: Form definitions, sessions, and step actions.
paths:
  /forms:
    post:
      tags: [Forms]
      summary: Create a form definition
      operationId: createForm
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFormDefinitionInput'
      responses:
        '201':
          description: Form definition created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormDefinition'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/Error'
    get:
      tags: [Forms]
      summary: List form definitions
      operationId: listForms
      description: |
        Returns a page of form definitions matching the optional filter. Pagination accepts both
        `limit`/`offset` and OpenAPI-style `page`/`size`; the parser normalises and clamps `limit`
        to `[1, 100]` (default `20`). Default sort is `createdAt DESC`.
      parameters:
        - name: nameContains
          in: query
          description: Case-insensitive substring match against the form name.
          schema:
            type: string
        - name: status
          in: query
          description: Filter by lifecycle status.
          schema:
            $ref: '#/components/schemas/FormStatus'
        - name: kind
          in: query
          description: Filter by form kind.
          schema:
            $ref: '#/components/schemas/FormKind'
        - name: attributeSetId
          in: query
          description: Filter to forms bound to the given semantic attribute set.
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          description: Page of form definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormDefinitionPageResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/Error'

  /forms/{formId}:
    parameters:
      - $ref: '#/components/parameters/FormId'
    get:
      tags: [Forms]
      summary: Get one form definition
      operationId: getForm
      responses:
        '200':
          description: Form definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Error'
    put:
      tags: [Forms]
      summary: Update a form definition
      operationId: updateForm
      description: Null fields in the input are left unchanged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFormDefinitionInput'
      responses:
        '200':
          description: Updated form definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormDefinition'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Error'
    delete:
      tags: [Forms]
      summary: Soft-delete a form definition
      operationId: deleteForm
      responses:
        '204':
          description: Form definition soft-deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Error'

  /forms/{formId}/resolve:
    parameters:
      - $ref: '#/components/parameters/FormId'
    post:
      tags: [Forms]
      summary: Resolve a form definition
      operationId: resolveForm
      description: |
        Returns the form's runtime tree resolved for the given locale, principal, and roles.
        Steps, sections, and fields are filtered by access policy and locale-keyed labels are
        collapsed to the requested locale.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveFormInput'
      responses:
        '200':
          description: Resolved form runtime tree.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedForm'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Error'

  /forms/{formId}/sessions:
    parameters:
      - $ref: '#/components/parameters/FormId'
    post:
      tags: [Forms]
      summary: Create a form session
      operationId: createFormSession
      description: |
        Creates a new runtime session bound to the form version identified by `formId`. The
        session inherits the resolved form tree for the supplied locale/principal/roles and
        starts at `currentStepIndex = 0`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFormSessionInput'
      responses:
        '201':
          description: Form session created.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      tags: [Forms]
      summary: Get the full session
      operationId: getFormSession
      responses:
        '200':
          description: Form session.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/snapshot:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      tags: [Forms]
      summary: Get the session snapshot
      operationId: getFormSessionSnapshot
      description: |
        Returns the client-oriented snapshot: state, progress, allowed commands, and revision.
        Snapshots omit raw field values, fetch the full session for those.
      responses:
        '200':
          description: Session snapshot.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSessionSnapshot'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/events:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      tags: [Forms]
      summary: List session events
      operationId: listFormSessionEvents
      description: |
        Returns appended session events in monotonically increasing `sequence` order. Use
        `afterSequence` to tail events past a known cursor; `limit` is clamped to `[1, 1000]`.
      parameters:
        - name: afterSequence
          in: query
          description: Return events strictly after this `sequence` value.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: limit
          in: query
          description: Maximum number of events to return. Defaults to `100`.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
      responses:
        '200':
          description: Session events list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSessionEventListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/values:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    put:
      tags: [Forms]
      summary: Update session field values
      operationId: updateFormSessionValues
      description: |
        Applies the supplied field-value map to the session and returns the resulting mutation
        with a per-field diff. Field paths must exist in the session's current `resolvedForm`;
        HIDDEN-by-policy fields are absent from the resolved tree and are rejected.
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFieldValuesInput'
      responses:
        '200':
          description: Mutation applied.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSessionMutationResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/steps/{stepIndex}/navigate:
    parameters:
      - $ref: '#/components/parameters/SessionId'
      - $ref: '#/components/parameters/StepIndex'
    post:
      tags: [Forms]
      summary: Navigate to a step
      operationId: navigateFormSessionStep
      description: |
        Navigates the session to the step at `stepIndex`. Forward navigation is gated on the
        target step's required actions being satisfied; backward navigation is unconditional
        within mutable session states.
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Navigation applied.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/steps/{stepIndex}/validate:
    parameters:
      - $ref: '#/components/parameters/SessionId'
      - $ref: '#/components/parameters/StepIndex'
    post:
      tags: [Forms]
      summary: Validate every field within a step
      operationId: validateFormSessionStep
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Step validated. Returns a map from field path to validation error messages (empty when the step is valid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepValidationErrors'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/fields/validate:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags: [Forms]
      summary: Validate a single field
      operationId: validateFormSessionField
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateFieldInput'
      responses:
        '200':
          description: Field validated. Returns the list of validation error messages (empty when the field is valid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldValidationErrors'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/submit:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags: [Forms]
      summary: Submit a form session
      operationId: submitFormSession
      description: |
        Validates all steps, applies final values, and transitions the session to `SUBMITTED`.
        Rejected when the session status forbids submission (see `FormSessionStatus.canSubmit`).
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitFormInput'
      responses:
        '200':
          description: Session submitted.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/cancel:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags: [Forms]
      summary: Cancel a form session
      operationId: cancelFormSession
      description: Transitions the session to `CANCELLED`.
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: Session cancelled.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/fields/invalidate:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags: [Forms]
      summary: Mark a field as needing re-validation
      operationId: invalidateFormSessionField
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvalidateFieldInput'
      responses:
        '200':
          description: Field invalidated.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/fields/remotevalidation:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags: [Forms]
      summary: Force a remote validation result on a field
      operationId: forceFormSessionFieldValidation
      description: |
        Empty `errors` marks the field as remotely valid; non-empty marks it remotely invalid
        and stamps the session phase as `FAILED`.
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForceFieldValidationInput'
      responses:
        '200':
          description: Forced validation applied.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/fields/remotevalidation/clear:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags: [Forms]
      summary: Clear forced remote validation on a field
      operationId: clearFormSessionFieldForcedValidation
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClearForcedFieldValidationInput'
      responses:
        '200':
          description: Forced validation cleared.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/servererrors:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags: [Forms]
      summary: Apply server-side field errors in bulk
      operationId: applyFormSessionServerErrors
      description: |
        Stamps the session phase as `FAILED`. The next accepted user update to a targeted field
        clears its remote errors via the existing field lifecycle.
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyServerFieldErrorsInput'
      responses:
        '200':
          description: Server errors applied.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/steps/{stepId}/actions/{actionId}/start:
    parameters:
      - $ref: '#/components/parameters/SessionId'
      - $ref: '#/components/parameters/StepId'
      - $ref: '#/components/parameters/ActionId'
    post:
      tags: [Forms]
      summary: Start a step action
      operationId: startFormStepAction
      description: |
        Transitions a step action from `PENDING` -> `IN_PROGRESS` and returns the prompt the
        client must fulfill (presentation request, evidence upload target, signature challenge,
        artifact handle, or `None` for synchronous actions).
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Step action started; prompt returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepActionPrompt'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/steps/{stepId}/actions/{actionId}/complete:
    parameters:
      - $ref: '#/components/parameters/SessionId'
      - $ref: '#/components/parameters/StepId'
      - $ref: '#/components/parameters/ActionId'
    post:
      tags: [Forms]
      summary: Complete a step action
      operationId: completeFormStepAction
      description: The `result` variant must match the declared `StepAction` variant on the resolved form.
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteStepActionInput'
      responses:
        '200':
          description: Step action completed.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

  /forms/sessions/{sessionId}/steps/{stepId}/actions/{actionId}/cancel:
    parameters:
      - $ref: '#/components/parameters/SessionId'
      - $ref: '#/components/parameters/StepId'
      - $ref: '#/components/parameters/ActionId'
    post:
      tags: [Forms]
      summary: Cancel a step action
      operationId: cancelFormStepAction
      description: Terminal state with optional reason recorded for audit.
      parameters:
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelStepActionInput'
      responses:
        '200':
          description: Step action cancelled.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSession'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/Error'

components:
  securitySchemes:
    bearer:
      $ref: './common-components.yml#/components/securitySchemes/bearer'
  parameters:
    IfMatch:
      $ref: './forms-components.yml#/components/parameters/IfMatch'
    IdempotencyKey:
      $ref: './forms-components.yml#/components/parameters/IdempotencyKey'
    FormId:
      $ref: './forms-components.yml#/components/parameters/FormId'
    SessionId:
      $ref: './forms-components.yml#/components/parameters/SessionId'
    StepId:
      $ref: './forms-components.yml#/components/parameters/StepId'
    StepIndex:
      $ref: './forms-components.yml#/components/parameters/StepIndex'
    ActionId:
      $ref: './forms-components.yml#/components/parameters/ActionId'
    Limit:
      $ref: './forms-components.yml#/components/parameters/Limit'
    Offset:
      $ref: './forms-components.yml#/components/parameters/Offset'
    Sort:
      $ref: './forms-components.yml#/components/parameters/Sort'
    SortDirection:
      $ref: './forms-components.yml#/components/parameters/SortDirection'
  headers:
    ETag:
      description: |
        Strong entity-tag (RFC 7232) carrying the resource's current [revision]. Clients echo
        this back unchanged as the `If-Match` request header on the next mutating call to opt
        into optimistic concurrency.
      schema:
        type: string
      example: '"42"'

  responses:
    NotFound:
      description: The requested entity was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: |
        Idempotency or policy-gate conflict. The `code` field distinguishes
        `IDEMPOTENCY_KEY_CONFLICT` and `POLICY_GATE_REJECTED`. (Optimistic-lock failures are
        surfaced as `412 Precondition Failed`; see [PreconditionFailed].)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PreconditionFailed:
      description: |
        Optimistic-concurrency precondition failed. Returned when the `If-Match` request header
        does not match the resource's current [revision]. The `code` field is
        `OPTIMISTIC_LOCK_CONFLICT`. Clients typically re-fetch the resource to pick up the latest
        revision before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Error:
      description: An unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    PaginationMeta:
      type: object
      description: Pagination metadata returned alongside paged collections.
      required: [limit, offset, total, hasMore]
      properties:
        limit:
          type: integer
          minimum: 0
        offset:
          type: integer
          minimum: 0
        total:
          type: integer
          format: int64
          minimum: 0
        hasMore:
          type: boolean

    FormDefinitionPageResponse:
      type: object
      description: Paged list of form definitions.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FormDefinition'
        pagination:
          $ref: '#/components/schemas/PaginationMeta'

    FormSessionEventListResponse:
      type: object
      description: Wire envelope for `GET /forms/sessions/{sessionId}/events`.
      required: [data]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FormSessionEvent'

    ApiError:
      type: object
      description: Error body content.
      required: [code, message]
      properties:
        code:
          type: string
          description: Stable, machine-readable error category.
          example: NOT_FOUND
        message:
          type: string
        details:
          type: object
          additionalProperties:
            type: string
          description: Optional field-level error detail (key -> message).

    ErrorResponse:
      type: object
      description: Envelope wrapping an [ApiError].
      required: [error]
      properties:
        error:
          $ref: '#/components/schemas/ApiError'

    FormStatus:
      $ref: './forms-components.yml#/components/schemas/FormStatus'
    FormKind:
      $ref: './forms-components.yml#/components/schemas/FormKind'
    FormSessionStatus:
      $ref: './forms-components.yml#/components/schemas/FormSessionStatus'
    FormSessionPhase:
      $ref: './forms-components.yml#/components/schemas/FormSessionPhase'
    StepActionStatus:
      $ref: './forms-components.yml#/components/schemas/StepActionStatus'
    FormDefinition:
      $ref: './forms-components.yml#/components/schemas/FormDefinition'
    FormStepDefinition:
      $ref: './forms-components.yml#/components/schemas/FormStepDefinition'
    FormSectionDefinition:
      $ref: './forms-components.yml#/components/schemas/FormSectionDefinition'
    FormFieldDefinition:
      $ref: './forms-components.yml#/components/schemas/FormFieldDefinition'
    CreateFormDefinitionInput:
      type: object
      description: Input for creating a new [FormDefinition].
      required: [name, version, kind, attributeSetId, steps]
      properties:
        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/CreateFormStepInput'
        policyResourceKey:
          type: string
          nullable: true
        credentialBindings:
          type: array
          items:
            $ref: '#/components/schemas/FormCredentialBinding'

    CreateFormStepInput:
      type: object
      description: Input for a step within [CreateFormDefinitionInput].
      required: [name, labels, sortOrder, sections, actions]
      properties:
        name:
          type: string
        labels:
          type: object
          description: Locale-keyed label map (BCP-47 locale -> display string).
          additionalProperties:
            type: string
        descriptions:
          type: object
          nullable: true
          additionalProperties:
            type: string
        sortOrder:
          type: integer
        sections:
          type: array
          items:
            $ref: '#/components/schemas/CreateFormSectionInput'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/StepAction'
        policyResourceKey:
          type: string
          nullable: true

    CreateFormSectionInput:
      type: object
      description: Input for a section within [CreateFormStepInput].
      required: [name, labels, sortOrder, fields]
      properties:
        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/CreateFormFieldInput'

    CreateFormFieldInput:
      type: object
      description: Input for a field within [CreateFormSectionInput].
      required: [attributePath, sortOrder]
      properties:
        attributePath:
          $ref: '#/components/schemas/AttributePath'
        sortOrder:
          type: integer
        validationRules:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationRule'
        defaultValue:
          allOf:
            - $ref: '#/components/schemas/FieldValue'
          type: object
          nullable: true
        placeholders:
          type: object
          nullable: true
          additionalProperties:
            type: string
        visibilityCondition:
          allOf:
            - $ref: '#/components/schemas/FieldCondition'
          type: object
          nullable: true
        qualificationCondition:
          allOf:
            - $ref: '#/components/schemas/FieldCondition'
          type: object
          nullable: true
        disqualificationBehavior:
          $ref: '#/components/schemas/DisqualificationBehavior'
        readOnly:
          type: boolean
          default: false
        widgetHintOverride:
          allOf:
            - $ref: '#/components/schemas/AttributeWidgetHint'
          type: string
          nullable: true
        mandatoryOverride:
          $ref: '#/components/schemas/MandatoryOverride'
        policyResourceKey:
          type: string
          nullable: true

    UpdateFormDefinitionInput:
      type: object
      description: Input for updating a [FormDefinition]. Null fields are left unchanged.
      properties:
        name:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        status:
          allOf:
            - $ref: '#/components/schemas/FormStatus'
          type: string
          nullable: true
        steps:
          type: array
          nullable: true
          description: When supplied, replaces the entire step list. Use `null` to leave existing steps unchanged.
          items:
            $ref: '#/components/schemas/CreateFormStepInput'
        policyResourceKey:
          type: string
          nullable: true
        credentialBindings:
          type: array
          nullable: true
          description: When supplied, replaces the entire credential-binding list. Use `null` to leave existing bindings unchanged.
          items:
            $ref: '#/components/schemas/FormCredentialBinding'

    ResolveFormInput:
      type: object
      description: Input for resolving a [FormDefinition] for a specific locale, principal, and roles.
      properties:
        preferredLocale:
          type: string
          description: Preferred locale (BCP-47, e.g. `en`, `nl-NL`). Used to collapse locale-keyed labels.
        principalId:
          type: string
          nullable: true
          description: Principal subject for access-policy evaluation. Opaque string, NOT a UUID.
        roleIds:
          type: array
          items:
            type: string
          description: Role identifiers carried by the principal.

    ResolvedForm:
      $ref: './forms-components.yml#/components/schemas/ResolvedForm'
    ResolvedFormStep:
      $ref: './forms-components.yml#/components/schemas/ResolvedFormStep'
    ResolvedFormSection:
      $ref: './forms-components.yml#/components/schemas/ResolvedFormSection'
    ResolvedFormField:
      $ref: './forms-components.yml#/components/schemas/ResolvedFormField'
    FieldValue:
      $ref: './forms-components.yml#/components/schemas/FieldValue'
    FieldValueAbsent:
      $ref: './forms-components.yml#/components/schemas/FieldValueAbsent'
    FieldValueText:
      $ref: './forms-components.yml#/components/schemas/FieldValueText'
    FieldValueNumber:
      $ref: './forms-components.yml#/components/schemas/FieldValueNumber'
    FieldValueBool:
      $ref: './forms-components.yml#/components/schemas/FieldValueBool'
    FieldValueDate:
      $ref: './forms-components.yml#/components/schemas/FieldValueDate'
    FieldValueDateTime:
      $ref: './forms-components.yml#/components/schemas/FieldValueDateTime'
    FieldValueCode:
      $ref: './forms-components.yml#/components/schemas/FieldValueCode'
    FieldValueMulti:
      $ref: './forms-components.yml#/components/schemas/FieldValueMulti'
    FieldValueEvidenceRef:
      $ref: './forms-components.yml#/components/schemas/FieldValueEvidenceRef'
    FieldValueCredentialRef:
      $ref: './forms-components.yml#/components/schemas/FieldValueCredentialRef'
    FieldValueArtifactRef:
      $ref: './forms-components.yml#/components/schemas/FieldValueArtifactRef'
    FieldValidationError:
      $ref: './forms-components.yml#/components/schemas/FieldValidationError'
    FieldTargetedServerError:
      $ref: './forms-components.yml#/components/schemas/FieldTargetedServerError'
    StepActionResult:
      $ref: './forms-components.yml#/components/schemas/StepActionResult'
    StepActionResultCredentialReceived:
      $ref: './forms-components.yml#/components/schemas/StepActionResultCredentialReceived'
    StepActionResultEvidenceAttached:
      $ref: './forms-components.yml#/components/schemas/StepActionResultEvidenceAttached'
    StepActionResultSignatureOrSealApplied:
      $ref: './forms-components.yml#/components/schemas/StepActionResultSignatureOrSealApplied'
    StepActionResultPolicyEvaluated:
      $ref: './forms-components.yml#/components/schemas/StepActionResultPolicyEvaluated'
    StepActionResultArtifactProduced:
      $ref: './forms-components.yml#/components/schemas/StepActionResultArtifactProduced'
    StepActionPrompt:
      $ref: './forms-components.yml#/components/schemas/StepActionPrompt'
    StepActionPromptNone:
      $ref: './forms-components.yml#/components/schemas/StepActionPromptNone'
    StepActionPromptPresentationRequest:
      $ref: './forms-components.yml#/components/schemas/StepActionPromptPresentationRequest'
    StepActionPromptEvidenceUpload:
      $ref: './forms-components.yml#/components/schemas/StepActionPromptEvidenceUpload'
    StepActionPromptSignatureChallenge:
      $ref: './forms-components.yml#/components/schemas/StepActionPromptSignatureChallenge'
    StepActionPromptArtifactHandle:
      $ref: './forms-components.yml#/components/schemas/StepActionPromptArtifactHandle'
    SubmitFormInput:
      type: object
      description: |
        Input for submitting a form session. Carries the final, typed field values keyed by
        their attribute path.
      required: [fieldValues]
      properties:
        fieldValues:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldValue'

    ValidateFieldInput:
      type: object
      description: |
        Input for `validateField`. `value` is a typed [FieldValue], callers pass the
        `Absent` variant for "no value supplied" (there is no nullable variant).
      required: [fieldPath, value]
      properties:
        fieldPath:
          type: string
        value:
          $ref: '#/components/schemas/FieldValue'

    StepValidationErrors:
      $ref: './forms-components.yml#/components/schemas/StepValidationErrors'
    FieldValidationErrors:
      $ref: './forms-components.yml#/components/schemas/FieldValidationErrors'
    FormSession:
      $ref: './forms-components.yml#/components/schemas/FormSession'
    FormSessionPhaseState:
      $ref: './forms-components.yml#/components/schemas/FormSessionPhaseState'
    FormSessionProgress:
      $ref: './forms-components.yml#/components/schemas/FormSessionProgress'
    FormStepProgress:
      $ref: './forms-components.yml#/components/schemas/FormStepProgress'
    FormSessionFieldSnapshot:
      $ref: './forms-components.yml#/components/schemas/FormSessionFieldSnapshot'
    FormSessionCommandCapability:
      $ref: './forms-components.yml#/components/schemas/FormSessionCommandCapability'
    FormSessionSnapshot:
      $ref: './forms-components.yml#/components/schemas/FormSessionSnapshot'
    FormSessionEventType:
      $ref: './forms-components.yml#/components/schemas/FormSessionEventType'
    FormSessionEvent:
      $ref: './forms-components.yml#/components/schemas/FormSessionEvent'
    FormSessionDiff:
      $ref: './forms-components.yml#/components/schemas/FormSessionDiff'
    FormSessionMutationResult:
      $ref: './forms-components.yml#/components/schemas/FormSessionMutationResult'
    CreateFormSessionInput:
      type: object
      description: |
        Request body for `POST /forms/{formId}/sessions`. The form-definition identifier is
        supplied by the URL path; only per-session preferences appear in the body.
      properties:
        preferredLocale:
          type: string
          description: BCP-47 locale (e.g. `en`, `nl-NL`). Used to collapse locale-keyed labels in the resolved form.
          default: en
        principalId:
          type: string
          nullable: true
          description: Principal subject for access-policy evaluation. Opaque string, NOT a UUID.
        roleIds:
          type: array
          items:
            type: string

    UpdateFieldValuesInput:
      type: object
      description: Request body for `PUT /forms/sessions/{sessionId}/values`.
      required: [fieldValues]
      properties:
        fieldValues:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldValue'

    CompleteStepActionInput:
      type: object
      description: |
        Request body for
        `POST /forms/sessions/{sessionId}/steps/{stepId}/actions/{actionId}/complete`. The
        `result` variant must match the declared `StepAction` variant on the resolved form.
      required: [result]
      properties:
        result:
          $ref: '#/components/schemas/StepActionResult'

    CancelStepActionInput:
      type: object
      description: |
        Request body for
        `POST /forms/sessions/{sessionId}/steps/{stepId}/actions/{actionId}/cancel`.
      properties:
        reason:
          type: string
          nullable: true

    InvalidateFieldInput:
      type: object
      description: Request body for `POST /forms/sessions/{sessionId}/fields/invalidate`.
      required: [fieldPath]
      properties:
        fieldPath:
          type: string

    ClearForcedFieldValidationInput:
      type: object
      description: |
        Request body for `POST /forms/sessions/{sessionId}/fields/remotevalidation/clear`.
      required: [fieldPath]
      properties:
        fieldPath:
          type: string

    ForceFieldValidationInput:
      type: object
      description: |
        Request body for `POST /forms/sessions/{sessionId}/fields/remotevalidation`. Empty
        `errors` marks the field as remotely valid; non-empty marks it remotely invalid.
      required: [fieldPath, errors]
      properties:
        fieldPath:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldValidationError'

    ApplyServerFieldErrorsInput:
      type: object
      description: Request body for `POST /forms/sessions/{sessionId}/servererrors`.
      required: [fieldErrors]
      properties:
        reasons:
          type: array
          items:
            type: string
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldTargetedServerError'

    CredentialClaimPath:
      $ref: './forms-components.yml#/components/schemas/CredentialClaimPath'
    FormAttributeMapping:
      $ref: './forms-components.yml#/components/schemas/FormAttributeMapping'
    FormCredentialBinding:
      $ref: './forms-components.yml#/components/schemas/FormCredentialBinding'
    FormCredentialBindingInput:
      $ref: './forms-components.yml#/components/schemas/FormCredentialBindingInput'
    FormCredentialBindingOutput:
      $ref: './forms-components.yml#/components/schemas/FormCredentialBindingOutput'
    PresentedCredentialClaim:
      $ref: './forms-components.yml#/components/schemas/PresentedCredentialClaim'
    PresentedCredentialClaims:
      $ref: './forms-components.yml#/components/schemas/PresentedCredentialClaims'
    CredentialClaimProvenance:
      $ref: './forms-components.yml#/components/schemas/CredentialClaimProvenance'
    FieldValueProvenanceSource:
      $ref: './forms-components.yml#/components/schemas/FieldValueProvenanceSource'
    FieldValueProvenance:
      $ref: './forms-components.yml#/components/schemas/FieldValueProvenance'
    FieldLockReason:
      $ref: './forms-components.yml#/components/schemas/FieldLockReason'
    # -------------------------------------------------------------------------
    # Domain enums and scalar types
    # -------------------------------------------------------------------------

    AttributePath:
      $ref: './forms-components.yml#/components/schemas/AttributePath'
    AttributeValueKind:
      $ref: './forms-components.yml#/components/schemas/AttributeValueKind'
    AttributeWidgetHint:
      $ref: './forms-components.yml#/components/schemas/AttributeWidgetHint'
    AttributeCardinality:
      $ref: './forms-components.yml#/components/schemas/AttributeCardinality'
    FieldAccessMode:
      $ref: './forms-components.yml#/components/schemas/FieldAccessMode'
    MandatoryOverride:
      $ref: './forms-components.yml#/components/schemas/MandatoryOverride'
    DisqualificationBehavior:
      $ref: './forms-components.yml#/components/schemas/DisqualificationBehavior'
    ArtifactKind:
      $ref: './forms-components.yml#/components/schemas/ArtifactKind'
    AssuranceLevel:
      $ref: './forms-components.yml#/components/schemas/AssuranceLevel'
    SignatureOrSealKind:
      $ref: './forms-components.yml#/components/schemas/SignatureOrSealKind'
    PolicyDecision:
      $ref: './forms-components.yml#/components/schemas/PolicyDecision'
    FieldValidationSource:
      $ref: './forms-components.yml#/components/schemas/FieldValidationSource'
    FormSessionOperation:
      $ref: './forms-components.yml#/components/schemas/FormSessionOperation'
    # -------------------------------------------------------------------------
    # Runtime state
    # -------------------------------------------------------------------------

    FieldRuntimeState:
      $ref: './forms-components.yml#/components/schemas/FieldRuntimeState'
    FieldValidationState:
      $ref: './forms-components.yml#/components/schemas/FieldValidationState'
    FieldUpdateSource:
      $ref: './forms-components.yml#/components/schemas/FieldUpdateSource'
    StepActionState:
      $ref: './forms-components.yml#/components/schemas/StepActionState'
    # -------------------------------------------------------------------------
    # Field validation rules (tagged union)
    # -------------------------------------------------------------------------

    FieldValidationRule:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRule'
    FieldValidationRuleRequired:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRuleRequired'
    FieldValidationRuleMinLength:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRuleMinLength'
    FieldValidationRuleMaxLength:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRuleMaxLength'
    FieldValidationRulePattern:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRulePattern'
    FieldValidationRuleRange:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRuleRange'
    FieldValidationRuleEmail:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRuleEmail'
    FieldValidationRuleUri:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRuleUri'
    FieldValidationRuleCustom:
      $ref: './forms-components.yml#/components/schemas/FieldValidationRuleCustom'
    # -------------------------------------------------------------------------
    # Field conditions (tagged union)
    # -------------------------------------------------------------------------

    FieldCondition:
      $ref: './forms-components.yml#/components/schemas/FieldCondition'
    FieldConditionEquals:
      $ref: './forms-components.yml#/components/schemas/FieldConditionEquals'
    FieldConditionNotEmpty:
      $ref: './forms-components.yml#/components/schemas/FieldConditionNotEmpty'
    FieldConditionContains:
      $ref: './forms-components.yml#/components/schemas/FieldConditionContains'
    FieldConditionGreaterThan:
      $ref: './forms-components.yml#/components/schemas/FieldConditionGreaterThan'
    FieldConditionLessThan:
      $ref: './forms-components.yml#/components/schemas/FieldConditionLessThan'
    FieldConditionAnd:
      $ref: './forms-components.yml#/components/schemas/FieldConditionAnd'
    FieldConditionOr:
      $ref: './forms-components.yml#/components/schemas/FieldConditionOr'
    FieldConditionNot:
      $ref: './forms-components.yml#/components/schemas/FieldConditionNot'
    # -------------------------------------------------------------------------
    # Step actions (tagged union)
    # -------------------------------------------------------------------------

    StepAction:
      $ref: './forms-components.yml#/components/schemas/StepAction'
    StepActionRequestCredential:
      $ref: './forms-components.yml#/components/schemas/StepActionRequestCredential'
    StepActionRequireEvidence:
      $ref: './forms-components.yml#/components/schemas/StepActionRequireEvidence'
    StepActionRequireSignatureOrSeal:
      $ref: './forms-components.yml#/components/schemas/StepActionRequireSignatureOrSeal'
    StepActionPolicyGate:
      $ref: './forms-components.yml#/components/schemas/StepActionPolicyGate'
    StepActionProduceArtifact:
      $ref: './forms-components.yml#/components/schemas/StepActionProduceArtifact'
    StepActionSideEffect:
      $ref: './forms-components.yml#/components/schemas/StepActionSideEffect'
    StepActionSideEffectApplyReceivedCredentialClaims:
      $ref: './forms-components.yml#/components/schemas/StepActionSideEffectApplyReceivedCredentialClaims'
    StepActionSideEffectWriteCredentialReference:
      $ref: './forms-components.yml#/components/schemas/StepActionSideEffectWriteCredentialReference'
    StepActionSideEffectWriteEvidenceReference:
      $ref: './forms-components.yml#/components/schemas/StepActionSideEffectWriteEvidenceReference'
    StepActionSideEffectWriteArtifactReference:
      $ref: './forms-components.yml#/components/schemas/StepActionSideEffectWriteArtifactReference'
    StepActionSideEffectWriteSignatureLocator:
      $ref: './forms-components.yml#/components/schemas/StepActionSideEffectWriteSignatureLocator'
    StepActionSideEffectWritePolicyDecision:
      $ref: './forms-components.yml#/components/schemas/StepActionSideEffectWritePolicyDecision'