gremiumhub/api/legalconsenthub.yml

openapi: "3.0.3"
info:
  title: legalconsenthub
  version: 0.1.0
  description: A platform for digital applications, approvals and discussions.
  contact:
    name: Denis Lugowski
    email: denis.lugowski@gmail.com

servers:
  - url: http://localhost:8080

security:
  - bearerAuth: []

paths:
  ####### Application Forms #######
  /application-forms:
    get:
      summary: Get all ApplicationForms
      operationId: getAllApplicationForms
      tags:
        - application-form
      parameters:
        - in: query
          name: organizationId
          schema:
            type: string
          description: Filter application forms by organization ID
      responses:
        "200":
          description: Paged list of application forms
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedApplicationFormDto"
        "500":
          description: Internal server error
    post:
      summary: Create a new ApplicationForm
      operationId: createApplicationForm
      tags:
        - application-form
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationFormDto"
      responses:
        "201":
          description: Successfully created application form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /test-data/application-form:
    post:
      summary: Creates a test application form based on seeded data
      operationId: createTestDataApplicationForm
      tags:
        - test-data
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: The organization ID to create the test form in
      responses:
        "201":
          description: Successfully created test application form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /application-forms/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get a specific ApplicationForm
      operationId: getApplicationFormById
      tags:
        - application-form
      responses:
        "200":
          description: Get application form by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    put:
      summary: Updates a ApplicationForm
      operationId: updateApplicationForm
      tags:
        - application-form
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationFormDto"
      responses:
        "200":
          description: Successfully updated application form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a ApplicationForm
      operationId: deleteApplicationForm
      tags:
        - application-form
      responses:
        "204":
          description: Application Form successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/versions/{versionNumber}/pdf:
    get:
      summary: Returns the application form version rendered as PDF
      operationId: getApplicationFormVersionPdf
      tags:
        - application-form-version
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: versionNumber
          in: path
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Application form version as PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/submit:
    post:
      summary: Submit an application form
      operationId: submitApplicationForm
      tags:
        - application-form
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Application form successfully submitted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{applicationFormId}/subsections/{subsectionId}/form-elements:
    post:
      summary: Add a new form element to a specific subsection
      operationId: addFormElementToSubSection
      tags:
        - application-form
      parameters:
        - name: applicationFormId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the application form
        - name: subsectionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the form element subsection
        - name: position
          in: query
          required: true
          schema:
            type: integer
          description: The position to insert the form element
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FormElementDto"
      responses:
        "201":
          description: Form element successfully added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/versions:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get all versions of an application form
      operationId: getApplicationFormVersions
      tags:
        - application-form-version
      responses:
        "200":
          description: List of versions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApplicationFormVersionListItemDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/versions/{versionNumber}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: versionNumber
        in: path
        required: true
        schema:
          type: integer
    get:
      summary: Get specific version with full snapshot
      operationId: getApplicationFormVersion
      tags:
        - application-form-version
      responses:
        "200":
          description: Version details with snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormVersionDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{id}/versions/{versionNumber}/restore:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: versionNumber
        in: path
        required: true
        schema:
          type: integer
    post:
      summary: Restore a specific version
      operationId: restoreApplicationFormVersion
      tags:
        - application-form-version
      responses:
        "200":
          description: Restored application form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Application Form Templates #######
  /application-form-templates:
    get:
      summary: Get all ApplicationFormTemplates
      operationId: getAllApplicationFormTemplates
      tags:
        - application-form-template
      responses:
        "200":
          description: Paged list of application form templates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedApplicationFormDto"
        "500":
          description: Internal server error
    post:
      summary: Create a new ApplicationFormTemplate
      operationId: createApplicationFormTemplate
      tags:
        - application-form-template
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationFormDto"
      responses:
        "201":
          description: Successfully created application form template
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-form-templates/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get a specific ApplicationFormTemplate
      operationId: getApplicationFormTemplateById
      tags:
        - application-form-template
      responses:
        "200":
          description: Get application form template by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    put:
      summary: Updates a ApplicationFormTemplate
      operationId: updateApplicationFormTemplate
      tags:
        - application-form-template
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationFormDto"
      responses:
        "200":
          description: Successfully updated application form template
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a ApplicationFormTemplate
      operationId: deleteApplicationFormTemplate
      tags:
        - application-form-template
      responses:
        "204":
          description: Application Form Template successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Users #######
  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Get a specific user
      operationId: getUserById
      tags:
        - user
      responses:
        "200":
          description: Get user by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /users/{id}/email-preferences:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    put:
      summary: Update user email preferences
      operationId: updateUserEmailPreferences
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEmailPreferencesDto"
      responses:
        "200":
          description: Email preferences updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Comments #######
  /comments/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    put:
      summary: Update a comment
      operationId: updateComment
      tags:
        - comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentDto"
      responses:
        "200":
          description: Successfully updated comment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a comment
      operationId: deleteComment
      tags:
        - comment
      responses:
        "204":
          description: Comment successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{applicationFormId}/comments:
    parameters:
      - name: applicationFormId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get comments for specific application form
      operationId: getCommentsByApplicationFormId
      tags:
        - comment
      parameters:
        - in: query
          name: formElementId
          required: false
          schema:
            type: string
            format: uuid
          description: If provided, only comments for this form element are returned.
        - in: query
          name: cursorCreatedAt
          required: false
          schema:
            type: string
            format: date-time
          description: Cursor for pagination (createdAt of the last received comment). When omitted, returns the first page.
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 1
            maximum: 50
          description: Number of comments to return.
      responses:
        "200":
          description: Get comments for application form ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CursorPagedCommentDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{applicationFormId}/comments/counts:
    parameters:
      - name: applicationFormId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get comment counts grouped by form element for an application form
      operationId: getGroupedCommentCountByApplicationFromId
      tags:
        - comment
      responses:
        "200":
          description: Map of formElementId to comment count
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationFormCommentCountsDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /application-forms/{applicationFormId}/form-elements/{formElementId}/comments:
    parameters:
      - name: applicationFormId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: formElementId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      summary: Create a new comment for a form element
      operationId: createComment
      tags:
        - comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCommentDto"
      responses:
        "201":
          description: Successfully created comment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Roles #######
  /roles:
    get:
      summary: Get all roles
      operationId: getAllRoles
      tags:
        - role
      responses:
        "200":
          description: List of roles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RoleDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    post:
      summary: Create a new role
      operationId: createRole
      tags:
        - role
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRoleDto"
      responses:
        "201":
          description: Successfully created role
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  /roles/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get a specific role
      operationId: getRoleById
      tags:
        - role
      responses:
        "200":
          description: Get role by ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"
    delete:
      summary: Delete a role
      operationId: deleteRole
      tags:
        - role
      responses:
        "204":
          description: Role successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
        "503":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServiceUnavailable"

  ####### Notifications #######
  /notifications:
    get:
      summary: Get notifications for the current user
      operationId: getNotifications
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to get notifications for
        - in: query
          name: page
          schema:
            type: integer
            default: 0
          description: Page number
        - in: query
          name: size
          schema:
            type: integer
            default: 20
          description: Page size
      responses:
        "200":
          description: Paged list of notifications
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedNotificationDto"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
    post:
      summary: Create a new notification
      operationId: createNotification
      tags:
        - notification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateNotificationDto"
      responses:
        "201":
          description: Successfully created notification
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
    delete:
      summary: Clear all notifications for the current user
      operationId: clearAllNotifications
      tags:
        - notification
      responses:
        "204":
          description: All notifications cleared
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/unread:
    get:
      summary: Get unread notifications for the current user
      operationId: getUnreadNotifications
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to get unread notifications for
      responses:
        "200":
          description: List of unread notifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotificationDto"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "403":
          description: User is not authorized to access this organization
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/unread/count:
    get:
      summary: Get count of unread notifications for a user (public endpoint)
      operationId: getUnreadNotificationCount
      tags:
        - notification
      parameters:
        - in: query
          name: userId
          required: true
          schema:
            type: string
          description: Keycloak user ID to get notification count for
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to get notification count for
      responses:
        "200":
          description: Count of unread notifications
          content:
            application/json:
              schema:
                type: integer
                format: int64
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/mark-all-read:
    put:
      summary: Mark all notifications as read for the current user
      operationId: markAllNotificationsAsRead
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID to mark notifications as read for
      responses:
        "204":
          description: All notifications marked as read
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "403":
          description: User is not authorized to access this organization
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      summary: Delete a specific notification
      operationId: deleteNotification
      tags:
        - notification
      responses:
        "204":
          description: Notification successfully deleted
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "403":
          description: User is not authorized to delete this notification
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /notifications/{id}/mark-read:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    put:
      summary: Mark a specific notification as read
      operationId: markNotificationAsRead
      tags:
        - notification
      parameters:
        - in: query
          name: organizationId
          required: true
          schema:
            type: string
          description: Organization ID for authorization
      responses:
        "200":
          description: Notification marked as read
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationDto"
        "404":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/NotFound"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "403":
          description: User is not authorized to access this organization
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  ####### Files #######
  /files:
    post:
      summary: Upload a new file for a form element
      operationId: uploadFile
      tags:
        - file
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/UploadFileRequestDto"
      responses:
        "201":
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadedFileDto"
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "413":
          description: File too large (exceeds 10MB limit)
        "415":
          description: Unsupported file type
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /files/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get file metadata by ID
      operationId: getFileById
      tags:
        - file
      responses:
        "200":
          description: File metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadedFileDto"
        "404":
          description: File not found
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
    delete:
      summary: Delete a file
      operationId: deleteFile
      tags:
        - file
      responses:
        "204":
          description: File successfully deleted
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          description: File not found
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /files/{id}/content:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Download file content
      operationId: downloadFileContent
      tags:
        - file
      parameters:
        - name: inline
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: If true, return file with inline disposition for browser viewing
      responses:
        "200":
          description: File binary content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              description: Attachment filename
              schema:
                type: string
            Content-Type:
              description: File MIME type
              schema:
                type: string
        "404":
          description: File not found
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  ####### Contact #######
  /contact:
    post:
      summary: Send a contact message
      operationId: sendContactMessage
      tags:
        - contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactMessageDto"
      responses:
        "204":
          description: Contact message sent successfully
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

  /application-forms/{applicationFormId}/files:
    parameters:
      - name: applicationFormId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The application form ID
    get:
      summary: Get all files for an application form
      operationId: getFilesByApplicationForm
      tags:
        - file
      parameters:
        - name: formElementReference
          in: query
          required: false
          schema:
            type: string
          description: Filter by form element reference key
      responses:
        "200":
          description: List of files for the application form
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UploadedFileDto"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          description: Application form not found
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"
    post:
      summary: Associate files with an application form
      operationId: associateFilesWithApplicationForm
      tags:
        - file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fileIds
              properties:
                fileIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: List of file IDs to associate with this application form
      responses:
        "204":
          description: Files successfully associated
        "400":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/BadRequest"
        "401":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/Unauthorized"
        "404":
          description: Application form or file not found
        "500":
          $ref: "https://api.swaggerhub.com/domains/smartbear-public/ProblemDetails/1.0.0#/components/responses/ServerError"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ####### ApplicationFormDto #######
    ApplicationFormDto:
      type: object
      required:
        - name
        - formElementSections
        - isTemplate
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        formElementSections:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSectionDto"
        isTemplate:
          type: boolean
          default: false
        organizationId:
          type: string
          nullable: true
        createdBy:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/UserDto"
        lastModifiedBy:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/UserDto"
        createdAt:
          type: string
          format: date-time
          nullable: true
        modifiedAt:
          type: string
          format: date-time
          nullable: true
        status:
          allOf:
            - $ref: "#/components/schemas/ApplicationFormStatus"
          nullable: true
        commentCount:
          type: integer
          format: int64
          nullable: true
          readOnly: true
          description: Total number of comments associated with this application form.
        fileIds:
          type: array
          items:
            type: string
            format: uuid
          nullable: true
          writeOnly: true
          description: Temporary file IDs to associate atomically on creation (write-only, ignored on read)

    PagedApplicationFormDto:
      type: object
      allOf:
        - $ref: "#/components/schemas/Page"
      required:
        - content
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/ApplicationFormDto"

    ApplicationFormSnapshotDto:
      type: object
      required:
        - name
        - status
        - organizationId
        - sections
      properties:
        name:
          type: string
        status:
          $ref: "#/components/schemas/ApplicationFormStatus"
        organizationId:
          type: string
        sections:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSectionSnapshotDto"

    ####### ApplicationFormVersion #######
    ApplicationFormVersionDto:
      type: object
      required:
        - id
        - applicationFormId
        - versionNumber
        - name
        - status
        - organizationId
        - snapshot
        - createdBy
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        applicationFormId:
          type: string
          format: uuid
        versionNumber:
          type: integer
        name:
          type: string
        status:
          $ref: "#/components/schemas/ApplicationFormStatus"
        organizationId:
          type: string
        snapshot:
          $ref: "#/components/schemas/ApplicationFormSnapshotDto"
        createdBy:
          $ref: "#/components/schemas/UserDto"
        createdAt:
          type: string
          format: date-time

    ApplicationFormVersionListItemDto:
      type: object
      required:
        - id
        - applicationFormId
        - versionNumber
        - name
        - status
        - organizationId
        - createdBy
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        applicationFormId:
          type: string
          format: uuid
        versionNumber:
          type: integer
        name:
          type: string
        status:
          $ref: "#/components/schemas/ApplicationFormStatus"
        organizationId:
          type: string
        createdBy:
          $ref: "#/components/schemas/UserDto"
        createdAt:
          type: string
          format: date-time

    ####### Form #######
    FormElementSectionDto:
      type: object
      required:
        - title
        - formElementSubSections
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        title:
          type: string
        shortTitle:
          type: string
        description:
          type: string
        formElementSubSections:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSubSectionDto"
        applicationFormId:
          type: string
          format: uuid
          nullable: true
        isTemplate:
          type: boolean
          default: false
          description: If true, this section is a template for spawning
        templateReference:
          type: string
          description: Unique reference key for this template section
        titleTemplate:
          type: string
          description: Title template with placeholder (e.g., "Modul{{triggerValue}}")
        spawnedFromElementReference:
          type: string
          description: Reference of the form element that triggered this section

    FormElementSectionSnapshotDto:
      type: object
      required:
        - title
        - subsections
      properties:
        title:
          type: string
        shortTitle:
          type: string
        description:
          type: string
        subsections:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSubSectionSnapshotDto"
        isTemplate:
          type: boolean
          default: false
        templateReference:
          type: string
        titleTemplate:
          type: string
        spawnedFromElementReference:
          type: string

    FormElementSubSectionDto:
      type: object
      required:
        - title
        - formElements
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        title:
          type: string
        subtitle:
          type: string
        formElements:
          type: array
          items:
            $ref: "#/components/schemas/FormElementDto"
        formElementSectionId:
          type: string
          format: uuid
          nullable: true

    FormElementSubSectionSnapshotDto:
      type: object
      required:
        - title
        - elements
      properties:
        title:
          type: string
        subtitle:
          type: string
        elements:
          type: array
          items:
            $ref: "#/components/schemas/FormElementSnapshotDto"

    FormElementDto:
      type: object
      required:
        - options
        - type
      properties:
        id:
          type: string
          format: uuid
          nullable: true
        reference:
          type: string
          description: Unique reference key for this form element (e.g., "art_der_massnahme")
        title:
          type: string
        description:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/FormOptionDto"
        type:
          $ref: "#/components/schemas/FormElementType"
        formElementSubSectionId:
          type: string
          format: uuid
          nullable: true
        visibilityConditions:
          nullable: true
          description: Recursive visibility condition tree (AND/OR groups with leaf conditions)
          allOf:
            - $ref: "#/components/schemas/VisibilityConditionGroup"
        sectionSpawnTriggers:
          type: array
          items:
            $ref: "#/components/schemas/SectionSpawnTriggerDto"
          description: List of triggers that can spawn template sections when conditions are met
        isClonable:
          type: boolean
          default: false
          description: If true, user can add more instances of this element
        tableRowPreset:
          $ref: "#/components/schemas/TableRowPresetDto"

    TableRowPresetDto:
      type: object
      description: Configuration for automatically creating table rows based on source table data
      properties:
        sourceTableReference:
          type: string
          description: Reference to source table element to pull rows from
        filterCondition:
          $ref: "#/components/schemas/TableColumnFilterDto"
        columnMappings:
          type: array
          items:
            $ref: "#/components/schemas/TableColumnMappingDto"
        canAddRows:
          type: boolean
          default: true
          description: If true, users can manually add or remove rows. If false, rows are fully controlled by the source table.

    TableColumnMappingDto:
      type: object
      description: Mapping between source and target columns for row presets
      properties:
        sourceColumnIndex:
          type: integer
          description: Index of source column (0-based)
        targetColumnIndex:
          type: integer
          description: Index of target column (0-based)

    FormElementSnapshotDto:
      type: object
      required:
        - type
        - options
      properties:
        reference:
          type: string
        title:
          type: string
        description:
          type: string
        type:
          $ref: "#/components/schemas/FormElementType"
        options:
          type: array
          items:
            $ref: "#/components/schemas/FormOptionDto"
        visibilityConditions:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/VisibilityConditionGroup"
        sectionSpawnTriggers:
          type: array
          items:
            $ref: "#/components/schemas/SectionSpawnTriggerDto"
        isClonable:
          type: boolean
          default: false
        tableRowPreset:
          $ref: "#/components/schemas/TableRowPresetDto"

    FormOptionDto:
      type: object
      required:
        - value
        - label
        - processingPurpose
        - employeeDataCategory
      properties:
        value:
          type: string
        label:
          type: string
        processingPurpose:
          $ref: "#/components/schemas/ProcessingPurpose"
        employeeDataCategory:
          $ref: "#/components/schemas/EmployeeDataCategory"
        columnConfig:
          $ref: "#/components/schemas/TableColumnConfigDto"
        visibilityConditions:
          $ref: "#/components/schemas/VisibilityConditionGroup"

    TableColumnConfigDto:
      type: object
      description: Configuration for table column cross-references
      properties:
        sourceTableReference:
          type: string
          description: Reference to source table element to get values from
        sourceColumnIndex:
          type: integer
          description: Index of source column to reference (0-based)
        filterCondition:
          $ref: "#/components/schemas/TableColumnFilterDto"
        rowConstraint:
          $ref: "#/components/schemas/TableRowConstraintDto"
        isReadOnly:
          type: boolean
          default: false
          description: If true, column values cannot be edited by user
        isMultipleAllowed:
          type: boolean
          default: false
          description: If true, allows selecting multiple values in this column
        isCheckbox:
          type: boolean
          default: false
          description: If true, renders a checkbox instead of text input

    TableRowConstraintDto:
      type: object
      description: Configuration for row-based value constraints from another table
      properties:
        constraintTableReference:
          type: string
          description: Reference to the constraint table that defines allowed value mappings
        constraintKeyColumnIndex:
          type: integer
          description: Column index in constraint table that matches the key (e.g., Rollen-ID)
        constraintValueColumnIndex:
          type: integer
          description: Column index in constraint table with allowed values (e.g., Permission-ID)
        currentRowKeyColumnIndex:
          type: integer
          description: Column index in current table row to use as the lookup key

    TableColumnFilterDto:
      type: object
      description: Filter condition for constraining available values
      properties:
        sourceColumnIndex:
          type: integer
          description: Index of source column to check for filter condition
        expectedValue:
          type: string
          description: Expected value to match in the source column
        operator:
          default: EQUALS
          allOf:
            - $ref: "#/components/schemas/VisibilityConditionOperator"

    FormElementType:
      type: string
      enum:
        - SELECT
        - CHECKBOX
        - RADIOBUTTON
        - TEXTFIELD
        - TEXTAREA
        - SWITCH
        - RICH_TEXT
        - DATE
        - TABLE
        - FILE_UPLOAD

    VisibilityConditionNode:
      type: object
      description: A visibility condition node - either a leaf (single condition) or a group (AND/OR of conditions). Use nodeType to determine which properties are relevant.
      properties:
        nodeType:
          type: string
          enum: [LEAF, GROUP]
          default: LEAF
          description: Type discriminator - LEAF for single condition, GROUP for AND/OR of conditions
        # Leaf properties (used when nodeType=LEAF)
        formElementConditionType:
          $ref: "#/components/schemas/VisibilityConditionType"
        sourceFormElementReference:
          type: string
          nullable: true
          description: "[LEAF] Reference key of the source form element to check"
        formElementExpectedValue:
          type: string
          nullable: true
          description: "[LEAF] Expected value to compare against the source element's value"
        formElementOperator:
          $ref: "#/components/schemas/VisibilityConditionOperator"
        # Group properties (used when nodeType=GROUP)
        groupOperator:
          type: string
          enum: [AND, OR]
          nullable: true
          description: "[GROUP] Logical operator to combine conditions"
        conditions:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/VisibilityConditionNode"
          description: "[GROUP] List of child conditions"

    VisibilityConditionGroup:
      type: object
      description: Root-level visibility condition group containing child conditions
      properties:
        operator:
          type: string
          enum: [AND, OR]
          nullable: true
          description: Logical operator to combine conditions
        conditions:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/VisibilityConditionNode"
          description: List of child conditions (can be leaves or nested groups)

    VisibilityConditionType:
      type: string
      enum:
        - SHOW
        - HIDE

    VisibilityConditionOperator:
      type: string
      enum:
        - EQUALS
        - NOT_EQUALS
        - IS_EMPTY
        - IS_NOT_EMPTY
        - CONTAINS
        - NOT_CONTAINS

    SectionSpawnTriggerDto:
      type: object
      required:
        - templateReference
        - sectionSpawnConditionType
        - sectionSpawnOperator
      properties:
        templateReference:
          type: string
          description: Reference key of the section template to spawn
        sectionSpawnConditionType:
          $ref: "#/components/schemas/VisibilityConditionType"
        sectionSpawnExpectedValue:
          type: string
          description: Expected value to trigger spawning
        sectionSpawnOperator:
          $ref: "#/components/schemas/VisibilityConditionOperator"

    ####### UserDto #######
    UserDto:
      type: object
      required:
        - keycloakId
        - name
        - organizationId
      properties:
        keycloakId:
          type: string
        name:
          type: string
        organizationId:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        emailOnFormCreated:
          type: boolean
          default: true
        emailOnFormSubmitted:
          type: boolean
          default: true
        emailOnFormUpdated:
          type: boolean
          default: true
          description: Whether to receive email when someone else updates a form the user created
        emailOnCommentAdded:
          type: boolean
          default: true
          description: Whether to receive email when someone comments on a form the user created

    UpdateEmailPreferencesDto:
      type: object
      properties:
        email:
          type: string
          nullable: true
        emailOnFormCreated:
          type: boolean
        emailOnFormSubmitted:
          type: boolean
        emailOnFormUpdated:
          type: boolean
          description: Whether to receive email when someone else updates a form the user created
        emailOnCommentAdded:
          type: boolean
          description: Whether to receive email when someone comments on a form the user created

    UserStatus:
      type: string
      enum:
        - INVITED
        - ACTIVE
        - BLOCKED
        - SUSPENDED_SUBSCRIPTION

    UserRole:
      type: string
      description: "User's role in the organization"
      enum:
        - owner
        - admin
        - employer
        - works_council_member
        - employee

    ####### CommentDto #######
    CommentDto:
      type: object
      required:
        - id
        - message
        - applicationFormId
        - formElementId
        - createdAt
        - modifiedAt
        - createdBy
      properties:
        id:
          type: string
          format: uuid
        message:
          type: string
        applicationFormId:
          type: string
          format: uuid
        formElementId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
        createdBy:
          $ref: "#/components/schemas/UserDto"

    CreateCommentDto:
      type: object
      required:
        - message
      properties:
        message:
          type: string

    CursorPagedCommentDto:
      type: object
      required:
        - content
        - hasMore
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/CommentDto"
        nextCursorCreatedAt:
          type: string
          format: date-time
          nullable: true
          description: Cursor to fetch the next page (createdAt of the last item in this page). Null when no more pages.
        hasMore:
          type: boolean
          description: Whether more comments exist after this page.

    ApplicationFormCommentCountsDto:
      type: object
      required:
        - counts
      properties:
        counts:
          type: object
          additionalProperties:
            type: integer
            format: int64
          description: Keys are formElementId (UUID), values are comment counts.

    ####### RoleDto #######
    RoleDto:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string

    CreateRoleDto:
      type: object
      required:
        - name
      properties:
        name:
          type: string

    ####### Notification #######
    NotificationDto:
      type: object
      required:
        - id
        - title
        - message
        - clickTarget
        - isRead
        - type
        - createdAt
        - organizationId
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        message:
          type: string
        clickTarget:
          type: string
        isRead:
          type: boolean
        recipient:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/UserDto"
        targetRoles:
          type: string
          description: Comma-separated list of target roles (only for role-based notifications)
          nullable: true
        type:
          $ref: "#/components/schemas/NotificationType"
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time

    CreateNotificationDto:
      type: object
      required:
        - title
        - message
        - clickTarget
        - type
        - organizationId
      properties:
        title:
          type: string
        message:
          type: string
        clickTarget:
          type: string
        recipientId:
          type: string
          description: Keycloak ID of the recipient user. If not provided, notification will be role-based or organization-wide.
          nullable: true
        targetRoles:
          type: array
          items:
            type: string
          description: List of roles to send notification to. If both recipientId and targetRoles are null, notification will be sent to all organization members.
          nullable: true
        excludedUserId:
          type: string
          description: Keycloak ID of user to exclude from receiving this notification (e.g., the action performer).
          nullable: true
        type:
          $ref: "#/components/schemas/NotificationType"
        organizationId:
          type: string
          description: The organization ID for this notification

    PagedNotificationDto:
      type: object
      allOf:
        - $ref: "#/components/schemas/Page"
      required:
        - content
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/NotificationDto"

    NotificationType:
      type: string
      enum:
        - INFO
        - WARNING
        - ERROR

    ####### Contact DTOs #######
    ContactMessageDto:
      type: object
      required:
        - subject
        - message
      properties:
        subject:
          type: string
          minLength: 1
          description: Subject of the contact message
        message:
          type: string
          minLength: 1
          description: HTML body of the contact message

    ####### File Upload DTOs #######
    UploadedFileDto:
      type: object
      required:
        - id
        - filename
        - originalFilename
        - size
        - mimeType
        - formElementReference
        - uploadedAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the uploaded file
        filename:
          type: string
          description: Unique filename stored on disk (UUID-based)
        originalFilename:
          type: string
          description: Original filename provided by the user
        size:
          type: integer
          format: int64
          description: File size in bytes
        mimeType:
          type: string
          description: MIME type (e.g., application/pdf, image/jpeg)
        organizationId:
          type: string
          nullable: true
          description: Organization context (null for global forms)
        applicationFormId:
          type: string
          format: uuid
          nullable: true
          description: The application form this file belongs to (null for temporary uploads)
        formElementReference:
          type: string
          description: Reference key of the form element (e.g., grundrechte_folgenabschaetzung)
        uploadedAt:
          type: string
          format: date-time
          description: Timestamp when the file was uploaded
        uploadedBy:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/UserDto"
          description: User who uploaded the file

    UploadFileRequestDto:
      type: object
      required:
        - file
        - formElementReference
      properties:
        file:
          type: string
          format: binary
          description: The file to upload
        organizationId:
          type: string
          nullable: true
          description: Organization context (null for global forms)
        applicationFormId:
          type: string
          format: uuid
          nullable: true
          description: The application form this file belongs to (null for temporary uploads before form is saved)
        formElementReference:
          type: string
          description: Reference key of the form element

    ####### Miscellaneous #######
    ProcessingPurpose:
      type: string
      enum:
        - SYSTEM_OPERATION
        - BUSINESS_PROCESS
        - DATA_ANALYSIS
        - NONE

    EmployeeDataCategory:
      type: string
      enum:
        - NON_CRITICAL
        - REVIEW_REQUIRED
        - SENSITIVE
        - NONE

    ComplianceStatus:
      type: string
      enum:
        - NON_CRITICAL
        - WARNING
        - CRITICAL

    ApplicationFormStatus:
      type: string
      enum:
        - DRAFT
        - SUBMITTED
        - APPROVED
        - REJECTED
        - SIGNED

    ####### Supporting components #######
    Page:
      type: object
      required:
        - number
        - size
        - numberOfElements
        - last
        - totalPages
        - first
        - totalElements
        - empty
      properties:
        number:
          type: integer
          format: int32
          example: 0
        size:
          type: integer
          format: int32
          example: 100
        numberOfElements:
          type: integer
          format: int32
          example: 0
        last:
          type: boolean
          example: true
        totalPages:
          type: integer
          format: int32
          example: 0
        first:
          type: boolean
          example: true
        totalElements:
          type: integer
          format: int64
          example: 0
        empty:
          type: boolean
          example: true