openapi: 3.0.0
info:
  title: ITCorpo API
  version: 2.0.0
  description: >
    API for managing IT corporation resources.

    For full documentation, please visit [the readme](https://github.com/ducin-public/itcorpo-api).

servers:
  - url: http://localhost:3000
    description: Local development server
  - url: https://api.itcorpo.com
    description: Production server

tags:
  - name: Auth
    description: Authentication operations
  - name: Benefits
    description: Benefit subscriptions, services and charges
  - name: Departments
    description: Departments management
  - name: Employees
    description: Employees management
  - name: Expenses
    description: Financial operations
  - name: Geo
    description: Geographical data
  - name: Offices
    description: Offices management
  - name: Projects
    description: Projects management
  - name: Pagination
    description: Fetched collection results are paginated
  - name: Search
    description: Fetched collection results allow specifying detailed search criteria

paths:
  /auth:
    post:
      summary: Issue a new JWT authentication token
      operationId: issueAuthToken
      tags:
        - Auth
      responses:
        '200':
          description: Successfully generated JWT token
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                properties:
                  token:
                    type: string
                    description: JWT token signed with server's secret
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /health:
    get:
      summary: Health Check
      operationId: HealthCheck
      tags:
        - System
      description: Endpoint to check the health of the API
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '500':
          description: API is not healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Server is unhealthy or temporarily unavailable.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/HealthStatus'
                  - $ref: '#/components/schemas/ErrorResponse'

  /license:
    get:
      summary: Get license information
      operationId: getLicense
      description: Returns the license text for the API
      tags:
        - System
      responses:
        '200':
          description: License text retrieved successfully
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: >
            Invalid Content-Type requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access to license file forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: License file not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /benefits/services:
    get:
      summary: List all available benefit services
      operationId: getBenefitServices
      tags:
        - Benefits
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BenefitService'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /benefits:
    get:
      summary: List all benefits subscriptions
      operationId: getBenefitSubscriptions
      tags:
        - Benefits
        - Pagination
        - Search
      parameters:
        - $ref: '#/components/parameters/BenefitServiceName'
        - $ref: '#/components/parameters/BenefitCategories'
        - $ref: '#/components/parameters/BenefitEmployeeId'
        - $ref: '#/components/parameters/BenefitFeeFrom'
        - $ref: '#/components/parameters/BenefitFeeTo'
        - $ref: '#/components/parameters/BenefitStatus'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Successful operation
          headers:
            X-Total-Count:
              $ref: '#/components/headers/XTotalCount'
            X-Total-Pages:
              $ref: '#/components/headers/XTotalPages'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BenefitSubscription'
        '400':
          description: >
            Invalid benefit subscriptions search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    post:
      summary: Create a new benefit
      operationId: createBenefit
      tags:
        - Benefits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenefitSubscriptionInput'
      responses:
        '201':
          description: Benefit created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitSubscription'
        '400':
          description: >
            Invalid benefit subscription input request body
            @see {@link BenefitSubscriptionInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Benefit already exists for this employee and service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /benefits/count:
    get:
      summary: Get total number of benefits
      operationId: getBenefitsCount
      tags:
        - Benefits
        - Search
      parameters:
        - $ref: '#/components/parameters/BenefitServiceName'
        - $ref: '#/components/parameters/BenefitCategories'
        - $ref: '#/components/parameters/BenefitEmployeeId'
        - $ref: '#/components/parameters/BenefitFeeFrom'
        - $ref: '#/components/parameters/BenefitFeeTo'
        - $ref: '#/components/parameters/BenefitStatus'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: integer
                example: 42
        '400':
          description: >
            Invalid benefit subscriptions search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /benefits/{benefitId}:
    get:
      summary: Get benefit by ID
      operationId: getBenefitSubscriptionById
      tags:
        - Benefits
      parameters:
        - name: benefitId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          links:
            GetCharges:
              $ref: '#/components/links/BenefitSubscriptionChargesLink'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitSubscription'
        '404':
          description: Benefit not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    
    put:
      summary: Update benefit
      operationId: updateBenefit
      tags:
        - Benefits
      parameters:
        - name: benefitId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenefitSubscriptionInput'
      responses:
        '200':
          description: Benefit updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitSubscription'
        '400':
          description: >
            Invalid benefit subscription input request body
            @see {@link BenefitSubscriptionInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Benefit not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    patch:
      summary: Cancel or renew benefit subscription
      operationId: updateBenefitSubscriptionStatus
      tags:
        - Benefits
      parameters:
        - name: benefitId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - operation
              properties:
                operation:
                  type: string
                  enum: ["CANCEL", "RENEW"]
      responses:
        '200':
          description: Benefit subscription status updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitSubscription'
        '400':
          description: >
            Invalid benefit subscription status update
            @see {@link BenefitSubscriptionInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Benefit subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /benefits/{benefitId}/charges:
    get:
      summary: List all benefit charges for a specific subscription
      operationId: getBenefitSubscriptionCharges
      tags:
        - Benefits
        - Pagination
      parameters:
        - name: benefitId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/BenefitProviderServiceCode'
        - $ref: '#/components/parameters/BenefitChargeStatus'
        - $ref: '#/components/parameters/BenefitBillingPeriodFrom'
        - $ref: '#/components/parameters/BenefitBillingPeriodTo'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Successful operation
          links:
            GetSubscription:
              $ref: '#/components/links/BenefitSubscriptionFromChargesLink'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BenefitCharge'
        '400':
          description: 
            Invalid benefit charges search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Benefit subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /benefits/charges:
    get:
      summary: List all benefit charges
      operationId: getBenefitCharges
      tags:
        - Benefits
        - Pagination
        - Search
      parameters:
        - $ref: '#/components/parameters/BenefitSubscriptionId'
        - $ref: '#/components/parameters/BenefitEmployeeId'
        - $ref: '#/components/parameters/BenefitProviderServiceCode'
        - $ref: '#/components/parameters/BenefitChargeStatus'
        - $ref: '#/components/parameters/BenefitBillingPeriodFrom'
        - $ref: '#/components/parameters/BenefitBillingPeriodTo'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Successful operation
          headers:
            X-Total-Count:
              $ref: '#/components/headers/XTotalCount'
            X-Total-Pages:
              $ref: '#/components/headers/XTotalPages'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BenefitCharge'
        '400':
          description: >
            Invalid benefit charges search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /departments:
    get:
      summary: List all departments
      operationId: getDepartments
      tags:
        - Departments
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Department'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    post:
      summary: Create a new department
      operationId: createDepartment
      tags:
        - Departments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepartmentInput'
      responses:
        '201':
          description: Department created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Department'
        '400':
          description: >
            Invalid department input request body
            @see {@link DepartmentInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Department with this name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /departments/count:
    get:
      summary: Get total number of departments
      operationId: getDepartmentsCount
      tags:
        - Departments
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: integer
                example: 8
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /departments/{departmentId}:
    get:
      summary: Get department by ID
      operationId: getDepartmentById
      tags:
        - Departments
      parameters:
        - name: departmentId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful operation
          links:
            GetEmployees:
              $ref: '#/components/links/DepartmentEmployeesLink'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Department'
        '404':
          description: Department not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    
    put:
      summary: Update department
      operationId: updateDepartment
      tags:
        - Departments
      parameters:
        - name: departmentId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepartmentInput'
      responses:
        '200':
          description: Department updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Department'
        '400':
          description: >
            Invalid department input request body
            @see {@link DepartmentInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Department not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    delete:
      summary: Delete department
      operationId: deleteDepartment
      tags:
        - Departments
      parameters:
        - name: departmentId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Department deleted successfully
        '404':
          description: Department not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Cannot delete department that has employees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /employees:
    get:
      summary: List all employees
      operationId: getEmployees
      tags:
        - Employees
        - Pagination
        - Search
      parameters:
        - $ref: '#/components/parameters/EmployeeGroup'
        - $ref: '#/components/parameters/EmployeeName'
        - $ref: '#/components/parameters/EmployeeDepartmentId'
        - $ref: '#/components/parameters/EmployeeSkills'
        - $ref: '#/components/parameters/EmployeeSkillsFiltering'
        - $ref: '#/components/parameters/EmployeeSalaryFrom'
        - $ref: '#/components/parameters/EmployeeSalaryTo'
        - $ref: '#/components/parameters/Nationality'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Employee'
        '400':
          description: >
            Invalid employees search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    post:
      summary: Create a new employee
      operationId: createEmployee
      tags:
        - Employees
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeInput'
      responses:
        '201':
          description: Employee created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          description: >
            Invalid employee input request body
            @see {@link EmployeeInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Employee with this email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid data state (e.g. department doesn't exist, office not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /employees/search-feed:
    get:
      summary: Get search feed for employees
      operationId: getEmployeesSearchFeed
      tags:
        - Employees
        - Search
      parameters:
        - $ref: '#/components/parameters/EmployeeName'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeSearchFeed'
        '400':
          description: >
            Invalid employees search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /employees/count:
    get:
      summary: Get total number of employees
      operationId: getEmployeesCount
      tags:
        - Employees
        - Search
      parameters:
        - $ref: '#/components/parameters/EmployeeGroup'
        - $ref: '#/components/parameters/EmployeeName'
        - $ref: '#/components/parameters/EmployeeDepartmentId'
        - $ref: '#/components/parameters/EmployeeSkills'
        - $ref: '#/components/parameters/EmployeeSkillsFiltering'
        - $ref: '#/components/parameters/EmployeeSalaryFrom'
        - $ref: '#/components/parameters/EmployeeSalaryTo'
      responses:
        '200':
          description: Successful operation
          headers:
            X-Total-Count:
              $ref: '#/components/headers/XTotalCount'
            X-Total-Pages:
              $ref: '#/components/headers/XTotalPages'
          content:
            application/json:
              schema:
                type: integer
                example: 1250
        '400':
          description: >
            Invalid employees search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /employees/{employeeId}:
    get:
      summary: Get employee by ID
      operationId: getEmployeeById
      tags:
        - Employees
      parameters:
        - name: employeeId
          in: path
          required: true
          example: 91720
          schema:
            type: integer
      responses:
        '200':
          description: Successful operation
          links:
            GetDepartment:
              $ref: '#/components/links/EmployeeDepartmentLink'
            GetProjects:
              $ref: '#/components/links/EmployeeProjectsLink'
            GetOffice:
              $ref: '#/components/links/EmployeeOfficeLink'
            GetBenefits:
              $ref: '#/components/links/EmployeeBenefitsLink'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '404':
          description: Employee not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    
    put:
      summary: Update employee
      operationId: updateEmployee
      tags:
        - Employees
      parameters:
        - name: employeeId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeInput'
      responses:
        '200':
          description: Employee updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          description: >
            Invalid employee input request body
            @see {@link EmployeeInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Employee not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Email already taken by another employee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid data state (e.g. department doesn't exist, office not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    delete:
      summary: Delete employee
      operationId: deleteEmployee
      tags:
        - Employees
      parameters:
        - name: employeeId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Employee deleted successfully
        '404':
          description: Employee not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Cannot delete employee that is assigned to active projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /employees/{employeeId}/projects:
    get:
      summary: Get projects which employee is assigned to
      operationId: getEmployeeProjects
      description: >
        Returns a list of projects that the employee is assigned to.
      tags:
        - Employees
      parameters:
        - name: employeeId
          in: path
          required: true
          example: 91720
          schema:
            type: integer
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - employee
                  - projects
                properties:
                  employee:
                    type: object
                    required:
                      - id
                      - name
                      - position
                      - department
                    properties:
                      id:
                        type: number
                        example: 91720
                      name:
                        type: string
                        example: "John Doe"
                      position:
                        type: string
                        example: "Software Developer"
                      department:
                        type: string
                        example: "Marketing"
                      imgURL:
                        type: string
                        example: "https://placekitten.com/200/200"
                  projects:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectEmployeeInvolvement'
                  
        '404':
          description: Employee not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /expenses:
    get:
      summary: List all expenses
      operationId: getExpenses
      tags:
        - Expenses
        - Pagination
        - Search
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Successful operation
          headers:
            X-Total-Count:
              $ref: '#/components/headers/XTotalCount'
            X-Total-Pages:
              $ref: '#/components/headers/XTotalPages'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Expense'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    post:
      summary: Create a new expense
      operationId: createExpense
      tags:
        - Expenses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpenseInput'
      responses:
        '201':
          description: Expense created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
        '400':
          description: >
            Invalid expense input request body
            @see {@link ExpenseInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Expense with this ID already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid account numbers or scheduling date in the past
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /expenses/count:
    get:
      summary: Get total number of expenses
      operationId: getExpensesCount
      tags:
        - Expenses
        - Search
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: integer
                example: 523
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /expenses/{expenseId}:
    get:
      summary: Get expense by ID
      operationId: getExpenseById
      tags:
        - Expenses
      parameters:
        - name: expenseId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
        '404':
          description: Expense not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    
    put:
      summary: Update expense
      operationId: updateExpense
      tags:
        - Expenses
      parameters:
        - name: expenseId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpenseInput'
      responses:
        '200':
          description: Expense updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Expense'
        '400':
          description: >
            Invalid expense input request body
            @see {@link ExpenseInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Expense not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Cannot modify expense that has been processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid account numbers or scheduling date in the past
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    delete:
      summary: Delete expense
      operationId: deleteExpense
      tags:
        - Expenses
      parameters:
        - name: expenseId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Expense deleted successfully
        '404':
          description: Expense not found
        '409':
          description: Cannot delete expense that has been processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /geo:
    get:
      summary: Get geographical data
      description: Returns a dictionary of country codes and country names
      tags:
        - Geo
      operationId: getGeo
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Geo'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /offices/amenities:
    get:
      summary: Retrieve list of possible office amenities
      description: Returns an array of office amenity objects that can be assigned to offices
      operationId: getOfficeAmenities
      tags:
        - Offices
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OfficeAmenity'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /offices/amenities/count:
    get:
      summary: Get total number of office amenities
      operationId: getOfficeAmenitiesCount
      tags:
        - Offices
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: integer
                example: 15
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /offices:
    get:
      summary: List all offices
      operationId: getOffices
      tags:
        - Offices
        - Search
      parameters:
        - $ref: '#/components/parameters/OfficePhrase'
        - $ref: '#/components/parameters/OfficeCountries'
        - $ref: '#/components/parameters/OfficeAmenities'
        - $ref: '#/components/parameters/OfficeAmenitiesFiltering'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Office'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    post:
      summary: Create a new office
      operationId: createOffice
      tags:
        - Offices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfficeInput'
      responses:
        '201':
          description: Office created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Office'
        '400':
          description: >
            Invalid office input request body
            @see {@link OfficeInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Office with this code already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid office configuration (e.g. invalid country code, unknown amenity)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /offices/count:
    get:
      summary: Get total number of offices
      operationId: getOfficesCount
      tags:
        - Offices
        - Search
      parameters:
        - $ref: '#/components/parameters/OfficePhrase'
        - $ref: '#/components/parameters/OfficeCountries'
        - $ref: '#/components/parameters/OfficeAmenities'
        - $ref: '#/components/parameters/OfficeAmenitiesFiltering'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: integer
                example: 25
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /offices/{officeCode}:
    get:
      summary: Get office by office code
      operationId: getOfficeByCode
      tags:
        - Offices
      parameters:
        - name: officeCode
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          links:
            GetAmenities:
              $ref: '#/components/links/OfficeAmenitiesLink'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Office'
        '404':
          description: Office not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    
    put:
      summary: Update office
      operationId: updateOffice
      tags:
        - Offices
      parameters:
        - name: officeCode
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfficeInput'
      responses:
        '200':
          description: Office updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Office'
        '400':
          description: >
            Invalid office input request body
            @see {@link OfficeInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Office not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Office code already taken by another office
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid office configuration (e.g. invalid country code, unknown amenity)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    delete:
      summary: Delete office
      operationId: deleteOffice
      tags:
        - Offices
      parameters:
        - name: officeCode
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Office deleted successfully
        '404':
          description: Office not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Cannot delete office that has assigned employees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /projects:
    get:
      summary: List all projects
      operationId: getProjects
      tags:
        - Projects
        - Pagination
        - Search
      parameters:
        - $ref: '#/components/parameters/ProjectName'
        - $ref: '#/components/parameters/ProjectStatus'
        - $ref: '#/components/parameters/ProjectTeamMembers'
        - $ref: '#/components/parameters/ProjectTeamMembersFiltering'
        - $ref: '#/components/parameters/ProjectBudgetFrom'
        - $ref: '#/components/parameters/ProjectBudgetTo'
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/ProjectSortBy'
        - $ref: '#/components/parameters/SortOrder'
      responses:
        '200':
          description: Successful operation
          headers:
            X-Total-Count:
              $ref: '#/components/headers/XTotalCount'
            X-Total-Pages:
              $ref: '#/components/headers/XTotalPages'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '400':
          description: Invalid projects search criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    post:
      summary: Create a new project
      operationId: createProject
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: >
            Invalid project input request body
            @see {@link ProjectInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Project with this name already exists in given time period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid data state (e.g. manager not found, team members don't exist, invalid date range)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /projects/count:
    get:
      summary: Get total number of projects
      operationId: getProjectsCount
      tags:
        - Projects
        - Search
      parameters:
        - $ref: '#/components/parameters/ProjectName'
        - $ref: '#/components/parameters/ProjectStatus'
        - $ref: '#/components/parameters/ProjectTeamMembers'
        - $ref: '#/components/parameters/ProjectTeamMembersFiltering'
        - $ref: '#/components/parameters/ProjectBudgetFrom'
        - $ref: '#/components/parameters/ProjectBudgetTo'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: integer
                example: 156
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /projects/{projectId}:
    get:
      summary: Get project by ID
      operationId: getProjectById
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          example: "579ef28f-c539-41ff-abe2-e4f6b1c1afed"
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          links:
            GetTeam:
              $ref: '#/components/links/ProjectTeamLink'
            GetManager:
              $ref: '#/components/links/ProjectManagerLink'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    
    put:
      summary: Update project
      operationId: updateProject
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
      responses:
        '200':
          description: Project updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: >
            Invalid project input request body
            @see {@link ProjectInput}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Project name already taken by another project in given time period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid data state (e.g. manager not found, team members don't exist, invalid date range)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    delete:
      summary: Delete project
      operationId: deleteProject
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Project deleted successfully
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Cannot delete project that is in ACTIVE status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /projects/{projectId}/team:
    get:
      summary: Get project team (employees assigned to the project)
      operationId: getProjectTeam
      description: >
        Returns a list of employees that are assigned to the project.
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          example: "579ef28f-c539-41ff-abe2-e4f6b1c1afed"
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          links:
            GetProject:
              $ref: '#/components/links/ProjectFromTeamLink'
            GetTeamMember:
              $ref: '#/components/links/ProjectTeamMemberLink'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectWithTeam'
        '404':
          description: Employee not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

components:
  links:

    BenefitSubscriptionChargesLink:
      operationId: getBenefitSubscriptionCharges
      parameters:
        benefitId: $response.body#/id
      description: Get the list of charges for this benefit subscription

    BenefitSubscriptionByIdLink:
      operationId: getBenefitSubscriptionById
      parameters:
        benefitId: $response.body#/subscriptionId
      description: Get the benefit subscription associated with the charge

    BenefitChargeEmployeeLink:
      operationId: getEmployeeById
      parameters:
        employeeId: $response.body#/employeeId
      description: Get the employee associated with the charge (for array responses use $response.body#/0/employeeId)

    BenefitSubscriptionFromChargesLink:
      operationId: getBenefitSubscriptionById
      parameters:
        benefitId: $request.path.benefitId
      description: Get the benefit subscription (context from path)

    DepartmentEmployeesLink:
      operationId: getEmployees
      parameters:
        departmentId: $response.body#/id
      description: Get employees of this department

    EmployeeProjectsLink:
      operationId: getEmployeeProjects
      parameters:
        employeeId: $response.body#/id
      description: Get projects the employee is assigned to

    EmployeeDepartmentLink:
      operationId: getDepartmentById
      parameters:
        departmentId: $response.body#/departmentId
      description: Get details of the employee's department

    EmployeeOfficeLink:
      operationId: getOfficeByCode
      parameters:
        officeCode: $response.body#/officeCode
      description: Get the office assigned to the employee

    EmployeeBenefitsLink:
      operationId: getBenefitSubscriptions
      parameters:
        employeeId: $response.body#/id
      description: Get the employee's benefit subscriptions

    OfficeAmenitiesLink:
      operationId: getOfficeAmenities
      description: Get the list of office amenity definitions

    ProjectTeamLink:
      operationId: getProjectTeam
      parameters:
        projectId: $response.body#/id
      description: Get the project team

    ProjectManagerLink:
      operationId: getEmployeeById
      parameters:
        employeeId: $response.body#/manager
      description: Get the project manager

    ProjectTeamMemberLink:
      operationId: getEmployeeById
      parameters:
        employeeId: $response.body#/team/0/employeeId
      description: Get details of the first team member (team[0])

    ProjectFromTeamLink:
      operationId: getProjectById
      parameters:
        projectId: $response.body#/id
      description: Get project details

  responses:
    NotAuthorized:
      description: The requester is unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: The service is temporarily unavailable. Maybe there is maintenance?
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    Money:
      type: number
      description: Monetary value in EUR

    DateString:
      type: string
      format: date-time
      description: ISO 8601 date-time string
    
    Duration:
      type: object
      required:
        - years
        - months
        - days
      properties:
        years:
          type: integer
        months:
          type: integer
        days:
          type: integer
    
    Email:
      type: string
      format: email
      description: Email address string
    
    Phone:
      type: string
      description: Phone number string

    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: An application-level error code (**not** HTTP status code)
        message:
          type: string
          description: Text description of the error that has occurred
        errorGUID:
          type: string
          description: unique identifier of the error
      required:
        - message

    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum: ["HEALTHY", "DEGRADED", "UNHEALTHY"]
          example: "HEALTHY"
        message:
          type: string
          example: "All systems operational"
      additionalProperties:
        type: string

    BenefitCategory:
      type: string
      enum:
        - "HEALTHCARE"
        - "SPORT_WELLNESS"
        - "LUNCH_FOOD"
        - "CULTURE_RECREATION"
      example: "HEALTHCARE"

    BenefitService:
      type: object
      required:
        - code
        - name
        - category
        - provider
        - description
        - availableCountries
      properties:
        code:
          type: string
        name:
          type: string
          description: Display name of the service
          example: "Medicover Healthcare Premium"
        category:
          $ref: '#/components/schemas/BenefitCategory'
        provider:
          type: object
          required:
            - name
            - website
            - contactEmail
            - supportPhone
          properties:
            name: 
              type: string
              example: "Medicover"
            website:
              type: string
              format: uri
              example: "https://medicover.com"
            contactEmail:
              $ref: '#/components/schemas/Email'
            supportPhone:
              $ref: '#/components/schemas/Phone'
            description:
              type: string
        description:
          type: string
          example: "Premium healthcare package including dental and specialist care"
        availableCountries:
          type: array
          items:
            type: string
          example: ["PL", "DE", "NL"]
        details:
          type: string
          description: Combined features and limitations in a formatted text
          example: "Features:\n- Dental care\n- 24/7 hotline\n- Mobile app\n\nLimitations:\n- 14 days waiting period\n- Excludes pre-existing conditions"
        cancellationPolicy:
          type: string
          example: "1 month notice required"

    BenefitSubscription:
      type: object
      required:
        - id
        - beneficiary
        - category
        - country
        - city
        - service
        - monthlyFee
        - subscribedAtDate
      properties:
        id:
          type: string
        service:
          type: object
          required:
            - name
            - provider
          properties:
            name:
              type: string
            provider:
              type: string
        beneficiary:
          type: object
          required:
            - name
            - email
          properties:
            name:
              type: string
            email:
              type: string
              format: email
        category:
          $ref: '#/components/schemas/BenefitCategory'
        country:
          type: string
        city:
          type: string
        monthlyFee:
          $ref: '#/components/schemas/Money'
        subscribedAtDate:
          type: string
          format: date
        cancelledAtDate:
          type: string
          format: date
      example:
        id: "60965cfccf2844a6"
        beneficiary:
          name: "Eva Koster"
          email: "evko@softix.nl"
        city: "Utrecht"
        country: "Netherlands"
        service:
          name: "MultiSport Active Plus"
          provider: "Benefit Systems"
        monthlyFee: 250
        subscribedAtDate: "2016-01-01"
        cancelledAtDate: "2016-05-31"
    
    BenefitSubscriptionInput:
      type: object
      required:
        - beneficiary
        - country
        - city
        - service
        - monthlyFee
        - subscribedAtDate
      properties:
        beneficiary:
          type: object
          required:
            - name
            - email
          properties:
            name:
              type: string
            email:
              type: string
              format: email
        country:
          type: string
        city:
          type: string
        service:
          type: string
        monthlyFee:
          $ref: '#/components/schemas/Money'
        subscribedAtDate:
          type: string
          format: date
        cancelledAtDate:
          type: string
          format: date

    BenefitSubscriptionSearchStatus:
      type: string
      enum: ["ALL", "ACTIVE", "CANCELLED"]
      description: Status filter for benefit subscriptions
      example: "ACTIVE"

    BenefitChargeStatus:
      type: string
      description: Payment status of a benefit charge
      enum:
        - "PENDING"
        - "PAID"
        - "OVERDUE"
        - "CANCELLED"
        - "REFUNDED"

    BenefitCharge:
      type: object
      required:
        - id
        - employeeId
        - subscriptionId
        - providerServiceCode
        - billingPeriodStart
        - billingPeriodEnd
        - amount
        - status
      properties:
        id:
          type: string
          format: uuid
        employeeId:
          type: integer
        subscriptionId:
          type: string
        providerServiceCode:
          type: string
        billingPeriodStart:
          type: string
          format: date
        billingPeriodEnd:
          type: string
          format: date
        amount:
          $ref: '#/components/schemas/Money'
        status:
          $ref: '#/components/schemas/BenefitChargeStatus'

    Department:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string
      example:
        id: 1
        name: "Management"

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

    Nationality:
      type: string
      description: >
        Nationality of employee as an
        ISO 3166-1 alpha-2 country code
      enum:
        - "US"
        - "UK"
        - "FR"
        - "DE"
        - "NL"
        - "PL"
        - "IT"
        - "ES"
        - "IN"
      example: "US"

    ContractType:
      type: string
      description: Type of employment contract
      enum:
        - "CONTRACT"
        - "PERMANENT"
      example: "PERMANENT"

    Skill:
      type: string
      description: Employee skill name
      example: "JavaScript"

    Employee:
      type: object
      required:
        - id
        - nationality
        - department
        - keycardId
        - account
        - office
        - officeCode
        - name
        - position
        - email
        - skills
        - bio
        - employment
        - personalInfo
      properties:
        id:
          type: integer
          example: 91720
        nationality:
          $ref: '#/components/schemas/Nationality'
        department:
          type: string
          description: Department display name
        departmentId:
          type: integer
          description: Department ID for linking to getDepartmentById (enables EmployeeDepartmentLink)
        keycardId:
          type: string
        office:
          type: string
        officeCode:
          type: string
        name:
          type: string
        position:
          type: string
        account:
          type: string
        email:
          $ref: '#/components/schemas/Email'
        employment:
          type: object
          required:
            - contractType
            - currentSalary
            - startDate
            - employedFor
          properties:
            contractType:
              $ref: '#/components/schemas/ContractType'
            currentSalary:
              $ref: '#/components/schemas/Money'
            startDate:
              $ref: "#/components/schemas/DateString"
            endDate:
              $ref: "#/components/schemas/DateString"
            employedFor:
              $ref: "#/components/schemas/Duration"
        personalInfo:
          type: object
          required:
            - age
            - phone
            - email
            - address
          properties:
            age:
              type: integer
              minimum: 0
            phone:
              $ref: '#/components/schemas/Phone'
            email:
              $ref: '#/components/schemas/Email'
            address:
              type: object
              required:
                - street
                - city
                - country
              properties:
                street:
                  type: string
                city:
                  type: string
                country:
                  type: string
        skills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        bio:
          type: string
        imgURL:
          type: string
      example:
        id: 1234
        nationality: "DE"
        department: "Marketing"
        departmentId: 1
        officeCode: "de-berlin"
        keycardId: "KC-9876"
        account: "DE89 3704 0044 0532 0130 00"
        name: "Hans Schmidt"
        position: "Senior Developer"
        email: "hans.schmidt@itcorpo.com"
        skills: ["JavaScript", "TypeScript", "React"]
        bio: "Experienced developer with focus on frontend technologies"
        imgURL: "hans-schmidt-profile.jpg"
        employment:
          contractType: "PERMANENT"
          currentSalary: 75000
          startDate: "2020-01-15"
          endDate: "2025-01-14"
          employedFor:
            years: 5
            months: 0
            days: 0
        personalInfo:
          age: 35
          phone: "+49 123 456789"
          email: "hans.schmidt@gmail.com"
          dateOfBirth: "1988-05-20T00:00:00.000Z"
          address:
            street: "Alexanderplatz 1"
            city: "Berlin"
            country: "Germany"

    EmployeeSearchFeed:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          example: 91720
        name:
          type: string
      example:
        id: 1234
        name: "Hans Schmidt"

    EmployeeInput:
      type: object
      required:
        - nationality
        - departmentId
        - keycardId
        - account
        - officeCode
        - firstName
        - lastName
        - position
        - email
        - skills
        - bio
        - employment
        - personalInfo
      properties:
        nationality:
          $ref: '#/components/schemas/Nationality'
        departmentId:
          type: number
        keycardId:
          type: string
        account:
          type: string
        officeCode:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        position:
          type: string
        email:
          $ref: '#/components/schemas/Email'
        employment:
          type: object
          required:
            - contractType
            - currentSalary
            - startDate
          properties:
            contractType:
              $ref: '#/components/schemas/ContractType'
            currentSalary:
              $ref: '#/components/schemas/Money'
            startDate:
              $ref: "#/components/schemas/DateString"
            endDate:
              $ref: "#/components/schemas/DateString"
        personalInfo:
          type: object
          required:
            - phone
            - email
            - dateOfBirth
            - address
          properties:
            phone:
              $ref: '#/components/schemas/Phone'
            email:
              $ref: '#/components/schemas/Email'
            dateOfBirth:
              $ref: '#/components/schemas/DateString'
            address:
              type: object
              required:
                - street
                - city
                - country
              properties:
                street:
                  type: string
                city:
                  type: string
                country:
                  type: string
        skills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        bio:
          type: string
        imgURL:
          type: string

    Expense:
      type: object
      required:
        - id
        - amount
        - title
        - payerAccount
        - beneficiaryAccount
        - beneficiaryAddress
        - scheduledAt
      properties:
        id:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
        title:
          type: string
        payerAccount:
          type: string
        beneficiaryAccount:
          type: string
        beneficiaryAddress:
          type: string
        scheduledAt:
          type: string
          format: date-time
      example:
        id: "f1c436a7-d9f5-4214-9be1-79766750b53b"
        amount: 10927
        title: "salary"
        payerAccount: "DE89 3704 0044 0532 0130 00"
        beneficiaryAccount: "PL61 1090 1014 0000 0712 1981 2874"
        beneficiaryAddress: "445 Mount Eden Road, Mount Eden, Auckland"
        scheduledAt: "2017-02-17T22:01:36.530Z"

    ExpenseInput:
      type: object
      required:
        - amount
        - title
        - payerAccount
        - beneficiaryAccount
        - beneficiaryAddress
        - scheduledAt
      properties:
        amount:
          $ref: '#/components/schemas/Money'
        title:
          type: string
        payerAccount:
          type: string
        beneficiaryAccount:
          type: string
        beneficiaryAddress:
          type: string
        scheduledAt:
          type: string
          format: date-time

    Geo:
      type: object
      additionalProperties:
        type: string
      example:
        "US": "United States"
        "UK": "United Kingdom"
        "DE": "Germany"

    Coordinates:
      type: object
      required:
        - latitude
        - longitude
      properties:
        latitude:
          type: number
        longitude:
          type: number
      example:
        latitude: 52.5200
        longitude: 13.4050

    OfficeAmenity:
      type: object
      required:
        - code
        - name
      properties:
        code:
          type: string
          description: Unique code identifier of the amenity
        name:
          type: string
          description: Display name of the amenity
      example:
        code: "parking"
        name: "PARKING"

    Office:
      type: object
      required:
        - code
        - country
        - city
        - address
        - capacity
        - estateOwner
        - amenities
        - monthlyRental
      properties:
        code:
          type: string
        country:
          type: string
        city:
          type: string
        address:
          type: string
        capacity:
          type: integer
          minimum: 1
        monthlyRental:
          $ref: '#/components/schemas/Money'
        estateOwner:
          type: object
          required:
            - name
            - phone
            - account
          properties:
            name:
              type: string
            phone:
              type: string
            account:
              type: string
        amenities:
          type: array
          items:
            type: string
        imgURL:
          type: string
      example:
        country: "Netherlands"
        city: "Amsterdam" 
        address: "Damrak 81"
        capacity: 150
        monthlyRental: 10000
        estate:
          owner: "B2C Estates and Sons"
          phone: "(7364) 079343"
          account: "NL86 AMUJ 9303 4156 60"
        amenities:
          - code: "OUTDOOR_SEATING"
            name: "Outdoor seating"
          - code: "OPEN_SPACE" 
            name: "Open space"
        imgURL: "amsterdam-6Uf6-XCKJ-qTKq-ISt2-B3SE.jpg"

    OfficeInput:
      type: object
      required:
        - code
        - country
        - city
        - address
        - coordinates
        - capacity
        - estateOwner
        - amenities
        - monthlyRental
      properties:
        code:
          type: string
        country:
          type: string
        city:
          type: string
        address:
          type: string
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        capacity:
          type: integer
          minimum: 1
        monthlyRental:
          $ref: '#/components/schemas/Money'
        estateOwner:
          type: object
          required:
            - name
            - phone
            - account
          properties:
            name:
              type: string
            phone:
              type: string
            account:
              type: string
        amenities:
          type: array
          items:
            $ref: '#/components/schemas/OfficeAmenity'
        imgURL:
          type: string

    ProjectStatus:
      type: string
      description: Status of the ongoing project's workflow
      enum:
        - "PLANNING"
        - "ACTIVE"
        - "COMPLETED"
        - "ON_HOLD"
      example: "ACTIVE"
    
    EngagementLevel:
      type: string
      description: Level of employee engagement in the project
      enum:
        - "FULL_TIME"
        - "PARTIAL_PLUS"
        - "HALF_TIME"
        - "ON_DEMAND"
      example: "FULL_TIME"

    Project:
      type: object
      required:
        - id
        - name
        - status
        - budget
        - startDate
        - manager
        - description
        - teamSize
      properties:
        id:
          type: string
        name:
          type: string
        status:
          $ref: '#/components/schemas/ProjectStatus'
        budget:
          $ref: '#/components/schemas/Money'
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        manager:
          type: integer
        description:
          type: string
        teamSize:
          type: integer
      example:
        id: "579ef28f-c539-41ff-abe2-e4f6b1c1afed"
        name: "Licensed Cotton Pants"
        status: "on-hold"
        budget: 490000
        startDate: "2013-04-16"
        endDate: "2019-04-27"
        team:
          - id: 4247456
            name: "Anna Bahringer"
        manager: 67429059
        description: "Deleniti rerum impedit.\nCum sed eaque quo accusantium."

    ProjectInput:
      type: object
      required:
        - name
        - status
        - budget
        - startDate
        - endDate
        - team
        - manager
        - description
      properties:
        name:
          type: string
        status:
          $ref: '#/components/schemas/ProjectStatus'
        budget:
          $ref: '#/components/schemas/Money'
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        team:
          type: array
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
              name:
                type: string
        manager:
          type: integer
        description:
          type: string

    ProjectEmployeeInvolvement:
      type: object
      description: Employee's involvement in a project
      required:
        - employeeId
        - projectId
        - employeeName
        - employeePosition
        - projectName
        - projectStatus
        - engagementLevel
        - startDate
        - duration
      properties:
        employeeId:
          type: integer
        projectId:
          type: string
        employeeName:
          type: string
        employeePosition:
          type: string
        employeeURL:
          type: string
          example: "https://placekitten.com/200/200"
        projectName:
          type: string
        projectStatus:
          $ref: '#/components/schemas/ProjectStatus'
        engagementLevel:
          $ref: '#/components/schemas/EngagementLevel'
        startDate:
          $ref: "#/components/schemas/DateString"
        endDate:
          $ref: "#/components/schemas/DateString"
        duration:
          $ref: '#/components/schemas/Duration'

    ProjectWithTeam:
      type: object
      description: Project data combined with its team members
      required:
        - id
        - name
        - status
        - budget
        - startDate
        - manager
        - description
        - team
      properties:
        id:
          type: string
        name:
          type: string
        status:
          $ref: '#/components/schemas/ProjectStatus'
        budget:
          $ref: '#/components/schemas/Money'
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        manager:
          type: integer
        description:
          type: string
        team:
          type: array
          items:
            $ref: '#/components/schemas/ProjectEmployeeInvolvement'

  headers:
    XTotalCount:
      description: Total number of items in collection, considering request query parameters
      schema:
        type: integer
        example: 156
    XTotalPages:
      description: Total number of pages, considering request query parameters
      schema:
        type: integer
        example: 3

  parameters:
    Nationality:
      name: nationality
      in: query
      description: Filter employees by nationality (country code, e.g. US, PL)
      required: false
      schema:
        $ref: '#/components/schemas/Nationality'
      example: US

    PageNumber:
      name: page
      in: query
      required: false
      description: Specify the page number to retrieve 
      schema:
        type: number
        description: Page number to retrieve
        example: 1

    PageSize:
      name: pageSize
      in: query
      required: false
      description: Specify the number of items per page
      schema:
        type: number
        minimum: 1
        maximum: 50
        description: Number of elements per page
        example: 1
    
    SortOrder:
      name: sortOrder
      in: query
      required: false
      description: Sort order
      schema:
        type: string
        enum: ["asc", "desc"]
        default: "asc"
        description: Sort order
        example: "asc"

    # Benefit parameters

    BenefitServiceName:
      name: serviceName
      in: query
      required: false
      description: Filter benefits by service name
      schema:
        type: string
        description: Filter benefits by service name
        example: "MultiSport"

    BenefitCategories:
      name: categories
      in: query
      required: false
      description: Filter benefits by categories
      schema:
        type: string
        description: >
          Comma-separated list of category codes to filter by.
          The search result will return benefits that match any of the provided categories (`ANY`).
        example: "HEALTHCARE,SPORT_WELLNESS"

    BenefitEmployeeId:
      name: employeeId
      in: query
      required: false
      description: Filter benefits by employee ID
      schema:
        type: string
        description: The employee whom this benefit is subscribed to
        example: "91720"

    BenefitFeeFrom:
      name: feeFrom
      in: query
      required: false
      description: Minimum monthly fee amount
      schema:
        type: string
        description: Minimum monthly fee amount
        example: "100"

    BenefitFeeTo:
      name: feeTo
      in: query
      required: false
      description: Maximum monthly fee amount
      schema:
        type: string
        description: Maximum monthly fee amount
        example: "500.50"

    BenefitStatus:
      name: status
      in: query
      required: false
      description: Filter benefits by status
      schema:
        $ref: '#/components/schemas/BenefitSubscriptionSearchStatus'

    # Benefit Charge parameters

    BenefitSubscriptionId:
      name: subscriptionId
      in: query
      required: false
      description: Filter charges by subscription ID
      schema:
        type: string
        description: Filter charges by subscription ID
        example: 'zc9b3b4c-1b1d-4b3e-8b3b-4c1b1d4b3e8b'

    BenefitProviderServiceCode:
      name: providerServiceCode
      in: query
      required: false
      description: Filter charges by provider service code
      schema:
        type: string
        description: Filter charges by provider service code
        example: "MEDICOVER_PREMIUM"

    BenefitChargeStatus:
      name: status
      in: query
      required: false
      description: Filter charges by status
      schema:
        $ref: '#/components/schemas/BenefitChargeStatus'

    BenefitBillingPeriodFrom:
      name: billingPeriodFrom
      in: query
      required: false
      description: Filter charges with billing period starting from this date
      schema:
        type: string
        format: date
        description: Filter charges with billing period starting from this date
        example: "2023-01-01"

    BenefitBillingPeriodTo:
      name: billingPeriodTo
      in: query
      required: false
      description: Filter charges with billing period ending before this date
      schema:
        type: string
        format: date
        description: Filter charges with billing period ending before this date
        example: "2023-12-31"

    # Employee parameters

    EmployeeGroup:
      name: group
      in: query
      required: false
      description: Filter employees by special groups
      schema:
        type: string
        enum: ["ACTIVE", "INVOLVED", "JOBLESS", "DEPARTING", "NEW_HIRES", "PAST"]
        default: "ACTIVE"

    EmployeeName:
      name: employeeName
      in: query
      required: false
      description: Filter employees by name
      schema:
        type: string
        description: Filter employees by name
        example: "John Doe"

    EmployeeDepartmentId:
      name: departmentId
      in: query
      required: false
      description: Filter employees by department ID
      schema:
        type: string
        description: Filter employees by department ID
        example: "123"

    EmployeeSkills:
      name: skills
      in: query
      required: false
      description: Filter employees by skills
      schema:
        type: string
        description: Filter employees by skills according to `skillsFiltering`
        example: "JavaScript,React"

    EmployeeSkillsFiltering:
      name: skillsFiltering
      in: query
      required: false
      description: How to match employee skills
      schema:
        type: string
        enum: ["ANY", "ALL"]
        default: "ANY"
        description: If more than one skill is passed, return either employees with any of the skills (`ANY`) or with all of them (`ALL`)
        example: "ALL"

    EmployeeSalaryFrom:
      name: salaryFrom
      in: query
      required: false
      description: Minimum salary amount
      schema:
        type: string
        description: Minimum salary amount
        example: "5000"

    EmployeeSalaryTo:
      name: salaryTo
      in: query
      required: false
      description: Maximum salary amount
      schema:
        type: string
        description: Maximum salary amount
        example: "10000"

    # Office parameters

    OfficePhrase:
      name: phrase
      in: query
      required: false
      description: Full text search across office fields
      schema:
        type: string
        description: Full text search across country, city, address and estate owner fields
        example: "Amsterdam"

    OfficeCountries:
      name: countries
      in: query
      required: false
      description: Filter offices by country codes
      schema:
        type: string
        description: Comma-separated list of country codes to filter by
        example: "PL,US"

    OfficeAmenities:
      name: amenities
      in: query
      required: false
      description: Filter offices by amenities
      schema:
        type: string
        description: Comma-separated list of amenity codes to filter by
        example: "FREE_PARKING,SHOWER"
  
    OfficeAmenitiesFiltering:
      name: amenitiesFiltering
      in: query
      required: false
      description: How to match office amenities ('ANY' or 'ALL')
      schema:
        type: string
        enum: ["ANY", "ALL"]
        default: "ANY"
        description: If more than one amenity is passed, return either offices with any of the amenities (`ANY`) or with all of them (`ALL`)
        example: "ALL"

    # Project parameters

    ProjectSortBy:
      name: sortBy
      in: query
      required: false
      description: Sort projects by field
      schema:
        type: string
        enum: ["name", "status", "startDate", "endDate", "teamSize"]
        default: "startDate"
        description: Sort projects by field
        example: "startDate"

    ProjectName:
      name: projectName
      in: query
      required: false
      description: Filter projects by name
      schema:
        type: string
        description: Filter projects by name
        example: "Cloud migration"

    ProjectStatus:
      name: status
      in: query
      required: false
      description: Filter projects by status
      schema:
        $ref: '#/components/schemas/ProjectStatus'

    ProjectTeamMembers:
      name: teamMembers
      in: query
      required: false
      description: Filter projects by team member IDs
      schema:
        type: string
        description: Filter projects by team member IDs according to `teamMembersFiltering`
        example: "123,456,789"

    ProjectTeamMembersFiltering:
      name: teamMembersFiltering
      in: query
      required: false
      description: How to match team members 
      schema:
        type: string
        enum: ["ANY", "ALL"]
        default: "ANY"
        description: If more than one ID is passed, return either projects with any of the team members (`ANY`) or with all of them (`ALL`)
        example: "ALL"

    ProjectBudgetFrom:
      name: budgetFrom
      in: query
      required: false
      description: Minimum project budget
      schema:
        type: string
        description: Minimum project budget amount
        example: "10000"

    ProjectBudgetTo:
      name: budgetTo
      in: query
      required: false
      description: Maximum project budget
      schema:
        type: string
        description: Maximum project budget amount
        example: "50000"