api.yaml

# Tip: Use https://editor-next.swagger.io/ to edit and preview this API specification

openapi: 3.0.3
info:
  title: Dojo API
  description: |-
    Welcome to the Dojo API specification
  version: 1.0.0
externalDocs:
  description: Dojo GitHub repository
  url: https://github.com/hackYourFuture/dojo
servers:
  - url: http://localhost:7777/api/
    description: Local development server
  - url: https://dojo-test.hackyourfuture.net/api/
    description: Test server
tags:
  - name: Auth
    description: ''
  - name: Search
    description: ''
  - name: Trainees
    description: ''
  - name: Trainee Education
    description: 'Endpoints to manage Trainee education info such as strikes and tests.'
  - name: Trainee Employment
    description: 'Endpoints to manage Trainee employment info.'
  - name: Cohorts
    description: ''
  - name: Geography
    description: ''
  - name: Dashboard
    description: ''
  - name: Users
    description: 'Endpoints to manage system users'
paths:
  /auth/login:
    post:
      tags:
        - Auth
      summary: Login to the system
      description: The endpoint exchanges Google Auth response code for internal JWT token to be used for authenticated requests
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        401:
          description: Authentication failed. The provided token may be invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: Unauthorized user - The user is not allowed to login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/session:
    get:
      tags:
        - Auth
      summary: Get current logged in user info
      description: This endpoint returns the currently authenticated user. It extracts and verifies the session token.
      security:
        - cookie_token:
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/logout:
    post:
      tags:
        - Auth
      summary: Logout from the system
      description: The endpoint removes the session token from the cookies.
      security:
        - cookie_token:
      responses:
        204:
          description: successful operation
        401:
          description: Not logged in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /search:
    get:
      tags:
        - Search
      summary: Find trainees
      description: Find trainees by a keyword. The search will try to match the first name, last name or email.
      security:
        - cookie_token:
      parameters:
        - name: q
          in: query
          description: Search query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Limit the number of results. Default value is 20, Max value is 50.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  hits:
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: 'Pv3R416r'
                            name:
                              type: string
                              example: John Doe
                            profilePath:
                              type: string
                              example: /trainee/Isaac-Pagaca_HpOjvmwX
                            thumbnailURL:
                              type: string
                              example: https://cdn.example.com/images/HpOjvmwX_thumb.jpeg
                            cohort:
                              type: number
                              example: 52
                            searchScore:
                              type: number
                              example: 100
                      size:
                        type: integer
                        example: 45

        '400':
          description: Missing query

  /trainees:
    post:
      tags:
        - Trainees
      summary: Create new profile
      description: ''
      security:
        - cookie_token:
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Trainee'
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trainee'
  /trainees/{id}:
    get:
      tags:
        - Trainees
      summary: Fetch information about a trainee
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'

      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trainee'
        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    patch:
      tags:
        - Trainees
      summary: Update trainee information
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'Can be partially sent for partial updates'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Trainee'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trainee'
        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Trainees
      summary: Delete trainee from the system
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'

      responses:
        '204':
          description: successful operation

        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /trainees/{id}/profile-picture:
    put:
      tags:
        - Trainees
      summary: Upload new profile picture of a given trainee
      description: >
        Accepts only images. The new image will override the old image.
        Max file size is 10MB. 
        The image may be resized on the backend to reduce its size.

      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'

      requestBody:
        description: ''
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                profilePicture:
                  $ref: '#/components/schemas/Binary'

      responses:
        '200':
          description: successful operation. Returns the image url
          content:
            application/json:
              schema:
                type: object
                properties:
                  imageURL:
                    type: string
                    example: 'https://example.com/image/65e9c0d25cd76173a4e431c.jpeg'
                  thumbnailURL:
                    type: string
                    example: 'https://example.com/image/65e9c0d25cd76173a4e431c_thumbnail.jpeg'
        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Trainees
      summary: Delete profile picture of a given trainee
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'

      responses:
        '204':
          description: successful operation

        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /trainees/{id}/letters:
    post:
      tags:
        - Trainees
      summary: Generate a letter for the trainee
      description: 'This endpoint will generate and return a PDF document as a binary stream.'
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'Provide a valid letter type'
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - github_trainee

      responses:
        '200':
          description: successful operation
          content:
            application/pdf:
              schema:
                $ref: '#/components/schemas/Binary'
        '400':
          description: Request format is invalid or the letter type is not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /trainees/{id}/strikes:
    get:
      tags:
        - Trainee Education
      summary: Fetch all strikes of a trainee
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StrikeWithReporter'
    post:
      tags:
        - Trainee Education
      summary: Create new strike
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'The id field is not required and ignored. If ReporterID is empty, the current logged in user ID will be used as the reporterID'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StrikeWithReporterID'
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrikeWithReporter'

  /trainees/{id}/strikes/{strikeID}:
    put:
      tags:
        - Trainee Education
      summary: Update existing strike
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
        - name: strikeID
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'The id field is not required and ignored. If ReporterID is empty, the current logged in user ID will be used as the reporterID'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StrikeWithReporterID'
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrikeWithReporter'
    delete:
      tags:
        - Trainee Education
      summary: Delete existing strike
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
        - name: strikeID
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      responses:
        204:
          description: successful operation

  /trainees/{id}/interactions:
    get:
      tags:
        - Trainees
      summary: Fetch all interactions of a trainee
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InteractionWithReporter'
    post:
      tags:
        - Trainees
      summary: Create new interaction
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'The id field is not required and ignored. If ReporterID is empty, the current logged in user ID will be used as the reporterID'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InteractionWithReporterID'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionWithReporter'
        '400':
          description: Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /trainees/{id}/interactions/{interactionID}:
    put:
      tags:
        - Trainees
      summary: Update existing interaction details
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
        - name: interactionID
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'The id field is not required and ignored. If ReporterID is empty, the current logged in user ID will be used as the reporterID'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InteractionWithReporterID'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionWithReporter'
        '400':
          description: Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trainee or interaction was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Trainees
      summary: Delete existing interaction
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
        - name: interactionID
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      responses:
        '204':
          description: successful operation
        '404':
          description: Trainee or interaction was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /trainees/{id}/tests:
    get:
      tags:
        - Trainee Education
      summary: Fetch all the tests of a trainee
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Test'
    post:
      tags:
        - Trainee Education
      summary: Create a new test record
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'The id field is not required and ignored.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Test'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Test'
        '400':
          description: Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /trainees/{id}/tests/{testID}:
    put:
      tags:
        - Trainee Education
      summary: Update existing test details
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
        - name: testID
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'The id field is not required and ignored.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Test'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Test'
        '400':
          description: Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trainee or test was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Trainee Education
      summary: Delete existing test information
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
        - name: testID
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      responses:
        '204':
          description: successful operation
        '404':
          description: Trainee or test was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /trainees/{id}/employment-history:
    get:
      tags:
        - Trainee Employment
      summary: Fetch employment history of a trainee
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmploymentHistory'
    post:
      tags:
        - Trainee Employment
      summary: Create a new employment history record for a trainee
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'The id field is not required and ignored.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmploymentHistory'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentHistory'
        '400':
          description: Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trainee was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /trainees/{id}/employment-history/{employmentHistoryID}:
    put:
      tags:
        - Trainee Employment
      summary: Update existing employment history data
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
        - name: employmentHistoryID
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      requestBody:
        description: 'The id field is not required and ignored.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmploymentHistory'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentHistory'
        '400':
          description: Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trainee or employment history was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Trainee Employment
      summary: Delete existing employment history information
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
        - name: employmentHistoryID
          in: path
          required: true
          schema:
            type: string
            example: '3jvz35Z'
      responses:
        '204':
          description: successful operation
        '404':
          description: Trainee or employment history was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /cohorts:
    get:
      tags:
        - Cohorts
      summary: Fetch a list of cohorts with their trainees
      description: Returns a list of cohorts for a specified range.
      security:
        - cookie_token:
      parameters:
        - name: start
          in: query
          description: 'Lower range of the cohort. Default: 0'
          schema:
            type: integer
            minimum: 0
            maximum: 999
        - name: end
          in: query
          description: 'Upper range of the cohort. Default: 999'
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 999
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cohort:
                      type: number
                    trainees:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                          thumbnailURL:
                            type: string
                          displayName:
                            type: string
                          location:
                            type: string
                          hasWorkPermit:
                            type: boolean
                          email:
                            type: string
                          slackID:
                            type: string
                          githubHandle:
                            type: string
                          linkedIn:
                            type: string
                          learningStatus:
                            $ref: '#/components/schemas/LearningStatus'
                          jobPath:
                            $ref: '#/components/schemas/JobPath'

  /geo/cities:
    get:
      tags:
        - Geography
      summary: Get list of cities
      description: Find cities by a keyword. Query and limit variables are optional. This endpoint is useful for auto-complete fields
      security:
        - cookie_token:
      parameters:
        - name: q
          in: query
          description: Search query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Limit the number of results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: 'Amsterdam'

  /geo/countries:
    get:
      tags:
        - Geography
      summary: Get list of countries
      description: Find countries by a keyword. Query and limit variables are optional. This endpoint is useful for auto-complete fields
      security:
        - cookie_token:
      parameters:
        - name: q
          in: query
          description: Search query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Limit the number of results
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      example: 'The Netherlands'
                    flag:
                      type: string
                      example: '🇳🇱'

  /admin/users:
    get:
      tags:
        - Users
      summary: Get all users
      description: Retrieve a list of all users in the system
      security:
        - cookie_token: []
      responses:
        200:
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      tags:
        - Users
      summary: Create a new user
      description: Create a new user in the system
      security:
        - cookie_token: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        201:
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        400:
          description: Invalid user data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: Email already in use
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /admin/users/{id}:
    put:
      tags:
        - Users
      summary: Update an existing user
      description: Update user information by ID
      security:
        - cookie_token: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the user to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
      responses:
        200:
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        400:
          description: Invalid user data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Users
      summary: Delete a user
      description: Delete a user from the system by ID
      security:
        - cookie_token: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The ID of the user to delete
      responses:
        204:
          description: User deleted successfully
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /dashboard:
    get:
      tags:
        - Dashboard
      summary: Get the data to display on the dashboard
      description: ''
      security:
        - cookie_token:
      parameters:
        - name: startDate
          in: query
          description: Include all trainees who started the program on or after startDate
          required: true
          schema:
            type: string
            format: date-time
            example: '2024-01-01'

        - name: endDate
          in: query
          description: Include all trainees who started the program before or on endDate
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01'

      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  demographics:
                    type: object
                    properties:
                      genderDistribution:
                        type: array
                        items:
                          $ref: '#/components/schemas/DashboardData'
                      countryOfOrigin:
                        type: array
                        items:
                          $ref: '#/components/schemas/DashboardData'
                  program:
                    properties:
                      graduations:
                        type: array
                        items:
                          $ref: '#/components/schemas/DashboardData'
                      employment:
                        type: array
                        items:
                          $ref: '#/components/schemas/DashboardData'

components:
  schemas:
    LoginRequest:
      type: object
      properties:
        authCode:
          type: string
          example: 4/0AnvDMrB6_8zVFU2GeTDALqZB_WDSYf6Zg8as7mAHQ84gJ5xrnwZA37Cz0tEned-MhPPn9w
        redirectURI:
          type: string
          description: 'The callback URI that was used in the Google Auth request. It should match the base URL of the frontend'
          example: http://localhost:5142

    LoginResponse:
      type: object
      properties:
        token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

    Trainee:
      type: object
      required:
        - personalInfo
        - contactInfo
        - educationInfo
      properties:
        id:
          type: string
          example: '65ea2e1e696deb3b3ebff843'
        createdAt:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
        displayName:
          type: string
          example: Johnny Doe
        profilePath:
          type: string
          example: /trainee/Isaac-Pagaca_HpOjvmwX
        imageURL:
          type: string
          example: https://cdn.example.com/images/profile/HpOjvmwX.jpeg
        thumbnailURL:
          type: string
          example: https://cdn.example.com/images/HpOjvmwX_thumb.jpeg
        personalInfo:
          $ref: '#/components/schemas/TraineePersonalInfo'
        contactInfo:
          $ref: '#/components/schemas/TraineeContactInfo'
        educationInfo:
          $ref: '#/components/schemas/TraineeEducationInfo'
        employmentInfo:
          $ref: '#/components/schemas/TraineeEmploymentInfo'
        interactions:
          type: array
          items:
            $ref: '#/components/schemas/InteractionWithReporter'

    TraineePersonalInfo:
      type: object
      required:
        - firstName
        - lastName
        - gender
      properties:
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        preferredName:
          type: string
          example: Johnny
        gender:
          type: string
          enum:
            - man
            - woman
            - non-binary
            - other
        pronouns:
          type: string
          example: He/His
        location:
          type: string
          example: Amsterdam
        englishLevel:
          type: string
          enum:
            - needs-work
            - moderate
            - good
          example: good
        professionalDutch:
          type: boolean
          example: true
        countryOfOrigin:
          type: string
          example: Syria
        background:
          type: string
          enum:
            - refugee
            - family-reunification
            - partner-of-skilled-migrant
            - vulnerable-group
            - eu-citizen
          example: refugee
        hasWorkPermit:
          type: boolean
          example: true
        residencyStatus:
          type: string
          enum:
            - first-interview
            - second-interview
            - residency
            - citizenship
        receivesSocialBenefits:
          type: boolean
          example: true
        caseManagerUrging:
          type: boolean
          example: false
        educationLevel:
          type: string
          enum:
            - none
            - high-school
            - diploma
            - bachelors-degree
            - masters-degree
            - phd
          example: bachelors-degree
        educationBackground:
          type: string
          example: BSc in Biology
        comments:
          type: string

    TraineeContactInfo:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          example: john.doe@example.com
        slackId:
          type: string
          example: U068AQ9G99F
        phone:
          type: string
          example: 0612345678
        githubHandle:
          type: string
          example: johngithub
        linkedin:
          type: string
          example: https://linkedin.com/in/john.doe
        emergencyContactName:
          type: string
          example: John Doe
        emergencyContactPhoneNum:
          type: string
          example: 0612345678

    TraineeEducationInfo:
      type: object
      required:
        - learningStatus
        - startCohort
      properties:
        startCohort:
          type: number
          example: 46
          minimum: 0
          maximum: 999
        currentCohort:
          type: number
          example: 47
          minimum: 0
          maximum: 999
        learningStatus:
          $ref: '#/components/schemas/LearningStatus'
        techMentor:
          type: string
          example: "John Doe"
        hrMentor:
          type: string
          example: "John Doe"
        englishMentor:
          type: string
          example: "John Doe"
        startDate:
          type: string
          format: date-time
          example: 2024-01-01
        graduationDate:
          type: string
          format: date-time
          example: 2024-01-01
        quitReason:
          type: string
          enum:
            - technical
            - social-skills
            - personal
            - withdrawn
            - municipality-or-monetary
            - left-nl
            - other
        quitDate:
          type: string
          format: date-time
          example: 2024-01-01
        strikes:
          type: array
          items:
            $ref: '#/components/schemas/StrikeWithReporter'
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/Assignment'
        tests:
          type: array
          items:
            $ref: '#/components/schemas/Test'
        comments:
          type: string

    TraineeEmploymentInfo:
      type: object
      required:
        - jobPath
      properties:
        jobPath:
          $ref: '#/components/schemas/JobPath'
        cvURL:
          type: string
          example: https://example.com/cv.pdf
        availability:
          type: string
        preferredRole:
          type: string
        preferredLocation:
          type: string
        drivingLicense:
          type: boolean
          example: false
        extraTechnologies:
          type: string
        employmentHistory:
          type: array
          items:
            $ref: '#/components/schemas/EmploymentHistory'
        comments:
          type: string

    Strike:
      type: object
      required:
        - date
        - reason
        - comments
      properties:
        id:
          type: string
          example: g5HQGuL8
        date:
          type: string
          format: date-time
          example: 2024-01-01T00:00:00.000Z
        reason:
          type: string
          enum:
            - absence
            - incomplete-submission
            - late-attendance
            - late-submission
            - missed-submission
            - pending-feedback
            - other
        comments:
          type: string

    StrikeWithReporter:
      allOf:
        - $ref: '#/components/schemas/Strike'
        - type: object
          required:
            - reporter
          properties:
            reporter:
              type: object
              properties:
                name:
                  type: string
                imageUrl:
                  type: string

    StrikeWithReporterID:
      allOf:
        - $ref: '#/components/schemas/Strike'
        - type: object
          properties:
            reporterID:
              type: string
              example: g5HQGuL8

    Interaction:
      type: object
      required:
        - date
        - type
        - details
      properties:
        id:
          type: string
          example: g5HQGuL8
        date:
          type: string
          format: date-time
          example: 2024-01-01T00:00:00.000Z
        type:
          type: string
          enum:
            - call
            - chat
            - feedback
            - in-person
            - tech-hour
            - english-mentorship
            - tech-support
            - hr-mentorship
            - grad-mentorship
            - other
        title:
          type: string
        details:
          type: string

    InteractionWithReporter:
      allOf:
        - $ref: '#/components/schemas/Interaction'
        - type: object
          required:
            - reporter
          properties:
            reporter:
              type: object
              properties:
                name:
                  type: string
                imageUrl:
                  type: string

    InteractionWithReporterID:
      allOf:
        - $ref: '#/components/schemas/Interaction'
        - type: object
          properties:
            reporterID:
              type: string
              example: g5HQGuL8

    Assignment:
      type: object
      required:
        - type
        - status
      properties:
        id:
          type: string
          example: g5HQGuU8
        createDate:
          type: string
          format: date-time
          example: 2024-01-01T00:00:00.000Z
        type:
          type: string
          example: 'JS week 2'
        status:
          type: string
          example: 'waiting-review'
        content:
          type: string
          example: 'https://github.com/link/to/assignment'
        comments:
          type: string

    Test:
      type: object
      required:
        - date
        - type
        - result
      properties:
        id:
          type: string
          example: g5HQGuL8
        date:
          type: string
          format: date-time
          example: 2024-01-01
        type:
          type: string
          enum:
            - presentation
            - javascript
            - browsers-interview
            - using-apis-interview
            - nodejs
            - react-interview
            - final-project-interview
            - core-mid-term-interview
            - core-end-interview
            - frontend-mid-term-interview
            - backend-mid-term-interview
            - cloud-mid-term-interview
            - data-mid-term-interview
            - tester-mid-term-interview
        score:
          type: number
          example: 8.6
        result:
          type: string
          enum:
            - passed
            - passed-with-warning
            - failed
            - disqualified
        comments:
          type: string

    EmploymentHistory:
      type: object
      required:
        - startDate
        - type
        - role
        - feeCollected
      properties:
        id:
          type: string
          example: g5HQGuL8
        type:
          type: string
          enum:
            - internship
            - job
        companyName:
          type: string
          example: HackYourFuture
        role:
          type: string
          example: 'Frontend developer'
        startDate:
          type: string
          format: date-time
          example: 2024-01-01
        endDate:
          type: string
          format: date-time
          example: 2024-01-01
        feeCollected:
          type: boolean
        feeAmount:
          type: number
          example: 500
        comments:
          type: string

    LearningStatus:
      type: string
      enum:
        - studying
        - graduated
        - on-hold
        - quit
      example: studying | graduated | on-hold | quit

    JobPath:
      type: string
      enum:
        - not-graduated
        - searching
        - internship
        - tech-job
        - non-tech-job
        - not-searching
        - other-studies
        - no-longer-helping
      example: not-graduated

    User:
      type: object
      properties:
        id:
          type: string
          example: Pv3R416r
        name:
          type: string
        email:
          type: string
          example: user@example.com
        imageUrl:
          type: string
          example: 'https://images.example.com/image.png'
        isActive:
          type: boolean
          example: true

    CreateUser:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          example: John Doe
        imageUrl:
          type: string
          example: 'https://images.example.com/image.png'
        isActive:
          type: boolean
          default: true
          example: true

    UpdateUser:
      type: object
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          example: John Doe
        imageUrl:
          type: string
          example: 'https://images.example.com/image.png'
        isActive:
          type: boolean
          example: true

    DashboardData:
      type: object
      properties:
        label:
          type: string
        value:
          type: number
          example: 42.12
        percent:
          type: number
          example: 58.1

    Error:
      type: object
      properties:
        message:
          type: string
          example: 'Error message'

    Binary:
      type: string
      format: binary
      example: <binary data>

  securitySchemes:
    cookie_token:
      type: apiKey
      name: dojo_token
      description: A JWT which was provided after a successful login
      in: cookie