CV_Management_API_OpenAPI_v1.6.0.yaml

openapi: 3.1.1
info:
  title: CV Management and Deterministic Internship Candidate Filtering API
  version: 1.6.0
  description:
    REST/JSON API contract for the locked Version 1 scope. Version 1.6.0 preserves the finalized Sprint 1-6 contracts
    and freezes the Sprint 7 Admin Student inspection, company and internship-request contracts plus the Sprint 8 deterministic
    filtering, manual shortlist, finalization, and export contracts.
  x-revision-summary:
    - Preserved every valid Sprint 1-6 path and operationId from OpenAPI v1.5.0.
    - Finalized read-only Admin Student deep-dive and latest-saved CV availability/download semantics.
    - Finalized company metadata with Admin-managed CRUD and destructive deletion; no active/inactive lifecycle.
    - Finalized internship requests with taxonomy-backed required skills and no persisted GPA criteria.
    - Finalized persisted deterministic filtering runs using runtime official GPA and declared skills only.
    - Finalized manual draft shortlists, non-blocking guidance acknowledgement, and atomic conflict-aware finalization.
    - Separated asynchronous CSV shortlist-summary export from ZIP latest-saved-CV export.
    - Added explicit missing-CV reporting, constrained pagination/sorting, optimistic concurrency, and endpoint-specific errors.
    - Expanded deterministic frontend metadata and scope-preservation validation for Sprint 7-8.
  x-implementation-status:
    frontendContract: READY
    backendImplementation: PLANNED
    sprint7FrontendImplementation: BLOCKED_BY_INTEGRATION
    sprint8FrontendImplementation: BLOCKED_BY_INTEGRATION
  x-academic-ledger-file-contract:
    format: CSV
    mediaType: text/csv
    extension: .csv
    charset: UTF-8
    maxSizeBytes: 5242880
    headerRowRequired: true
    headerOrderRequired: true
    columns:
      - name: student_index_number
        required: true
        description: Existing eligible Student index number.
      - name: course_code
        required: true
        description: Canonical subject code resolved by the backend.
      - name: credits
        required: true
        description: Positive subject credit value.
      - name: letter_grade
        required: true
        description: Grade resolved through the developer-managed grade scale.
      - name: semester
        required: true
        description: Official semester or period label.
      - name: academic_year
        required: true
        description: Academic year in YYYY/YYYY form.
      - name: attempt_number
        required: true
        description: Positive attempt number.
      - name: result_status
        required: true
        description:
          Closed official result status. Use PASSED for A+ through C, FAILED for C- through E,
          and ABSENT only for E*.
    derivedFields:
      - studentId
      - courseTitle
      - gradePoint
    duplicateBehavior:
      The backend may compute an internal content digest. Identical content matching an active or committed
      upload is rejected with 409. A prior PROCESSING_FAILED or VALIDATION_FAILED batch does not prevent a corrected file
      upload.
  x-sprint-7-8-contract-decisions:
    companyDeletion: DELETE permanently removes the company and cascades to its linked internship requests.
    requestDeletion: DELETE permanently removes the internship request and its required-skill associations.
    requestSkillMutation: Create/update may atomically replace the full skill set; nested endpoints support incremental edits.
    filterRuns: Persisted sanitized runtime metadata; candidate results are recomputed from latest committed data.
    shortlistCardinality: One shortlist resource per internship request in Version 1.
    shortlistGuidance: Advisory only; acknowledgement permits finalization when exceeded.
    summaryExport: Asynchronous CSV.
    bulkCvExport: Asynchronous ZIP of available latest-saved ATS-compliant PDF CVs with explicit missing-CV reporting.
servers:
  - url: /api/v1
security:
  - bearerAuth: []
tags:
  - name: Authentication
  - name: Student Verification and OTP
  - name: Password Reset
    description: Shared OTP-based password recovery for supported STUDENT and ADMIN accounts.
  - name: Student Dashboard
    description: Authenticated Student summary metrics sourced from persisted backend data.
  - name: Student Profile
    description: Authenticated Student-owned profile, CV-supporting records, and profile file operations.
  - name: Declared Skills and Taxonomy
  - name: Project Portfolio
  - name: Academic Records
  - name: CV Generation and Active CV
  - name: Admin Dashboard
  - name: Academic Ledger
  - name: Registered Students
  - name: Company Metadata
  - name: Internship Requests
  - name: Candidate Filtering
  - name: Shortlists
  - name: Exports
  - name: Audit/System Events
paths:
  /auth/student/login:
    post:
      tags:
        - Authentication
      summary: Authenticate a Student using university email and password.
      operationId: postAuthStudentLogin
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public. Audit: Security. Authenticates an existing Student account only; no Admin approval, company
        login, or temporary-password workflow.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudentLoginRequest'
  /auth/admin/login:
    post:
      tags:
        - Authentication
      summary: Authenticate a predefined Department Admin.
      operationId: postAuthAdminLogin
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public. Audit: Security. Authenticates a predefined, enabled Department Admin only; no Admin self-registration
        or account creation is permitted.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminLoginRequest'
  /auth/logout:
    post:
      tags:
        - Authentication
      summary: End the current authenticated session or token context.
      operationId: postAuthLogout
      responses:
        '204':
          description: No content.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student/Admin. Audit: Security. No request body is required. The backend invalidates server-side
        session or refresh-token state where supported; clients must clear local auth state.'
  /auth/me:
    get:
      tags:
        - Authentication
      summary: Return current authenticated user context and role claims.
      operationId: getAuthMe
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentUserResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student/Admin. Audit: Security. Frontend route guards cannot replace backend authorization.'
  /student-verifications:
    post:
      tags:
        - Student Verification and OTP
      summary: Start Student sign-up auto-verification using full name, index number and university email.
      operationId: postStudentVerifications
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentVerificationResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public. Audit: Security. Full name is display data only; index number and university email are
        verification authority.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudentVerificationStartRequest'
  /student-verifications/{verificationId}/otp/verify:
    post:
      tags:
        - Student Verification and OTP
      summary: Verify the OTP issued after successful student auto-verification.
      operationId: postStudentVerificationsByVerificationIdOtpVerify
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtpVerifyResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Public. Audit: Security. Raw OTP is never returned or logged.'
      security: []
      parameters:
        - name: verificationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: verificationId identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpVerifyRequest'
  /student-verifications/{verificationId}/otp/resend:
    post:
      tags:
        - Student Verification and OTP
      summary: Resend a valid OTP after expiry or non-delivery subject to rate limits.
      operationId: postStudentVerificationsByVerificationIdOtpResend
      responses:
        '202':
          description: OTP resend request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtpResendResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public. Audit: Security. Enforces expiry, resend cooldown, resend limits, and anti-abuse controls.
        Raw OTP values are never returned or logged.'
      security: []
      parameters:
        - name: verificationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: verificationId identifier.
  /student-verifications/{verificationId}/password:
    post:
      tags:
        - Student Verification and OTP
      summary: Create initial Student password after OTP verification.
      operationId: postStudentVerificationsByVerificationIdPassword
      responses:
        '204':
          description: Initial Student password created successfully; no response body.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public with a verified onboarding context. Audit: Security. Creates the initial Student password
        hash only; no temporary password is generated or returned.'
      security: []
      parameters:
        - name: verificationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: verificationId identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordCreateRequest'
  /password-resets:
    post:
      tags:
        - Password Reset
      summary: Start OTP-based password reset for a supported Student or Admin account.
      operationId: postPasswordResets
      responses:
        '202':
          description: Password-reset request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResetResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public. Audit: Security. Supports STUDENT and predefined ADMIN accounts. For every syntactically
        valid request, the API returns the same 202 status and safe response shape. The response must not confirm whether
        an eligible account exists. This endpoint never creates accounts, approves registrations, or issues temporary passwords.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetStartRequest'
  /password-resets/{resetId}/otp/verify:
    post:
      tags:
        - Password Reset
      summary: Verify the OTP for an active password-reset context.
      operationId: postPasswordResetsByResetIdOtpVerify
      responses:
        '200':
          description: Password-reset OTP verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtpVerifyResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public with a valid reset context. Audit: Security. Enforces OTP expiry, verification-attempt
        limits, and rate limits. Raw OTP values are never returned or logged.'
      security: []
      parameters:
        - name: resetId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: resetId identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpVerifyRequest'
  /password-resets/{resetId}/otp/resend:
    post:
      tags:
        - Password Reset
      summary: Resend the OTP for an active password-reset context.
      operationId: postPasswordResetsByResetIdOtpResend
      responses:
        '202':
          description: Password-reset OTP resend request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtpResendResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public with a valid reset context. Audit: Security. Enforces expiry, resend cooldown, resend limits,
        and anti-abuse controls. Raw OTP values are never returned or logged.'
      security: []
      parameters:
        - name: resetId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Opaque resetId identifier.
  /password-resets/{resetId}/password:
    post:
      tags:
        - Password Reset
      summary: Set a new password after successful password-reset OTP verification.
      operationId: postPasswordResetsByResetIdPassword
      responses:
        '204':
          description: Password updated successfully; no response body.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Public with a verified reset context. Audit: Security. Updates only the password hash, closes
        the reset context, and returns no password or temporary credential.'
      security: []
      parameters:
        - name: resetId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: resetId identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordCreateRequest'
  /me/dashboard/metrics:
    get:
      tags:
        - Student Dashboard
      summary: Retrieve persisted summary metrics for the authenticated Student dashboard.
      operationId: getMeDashboardMetrics
      description:
        'Access: Student. Audit: No. Returns only the authenticated Student’s persisted project, declared-skill,
        shortlist, and official GPA summary values. Counts are never calculated from frontend demo data. A null officialCumulativeGpa
        means no committed GPA is available.'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentDashboardMetricsResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
  /me/profile:
    get:
      tags:
        - Student Profile
      summary: Retrieve the authenticated Student profile and immutable identity fields.
      operationId: getMeProfile
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentProfileResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: No. Returns only the authenticated Student’s profile, immutable identity values,
        read-only Student level/cohort context, current profile photo metadata, and entity version.'
    patch:
      tags:
        - Student Profile
      summary: Update editable profile fields and CV-supporting profile summary.
      operationId: patchMeProfile
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentProfileResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: Yes. Updates only editable own-profile fields. Index number, university email,
        Student level, and cohort year are immutable and are not accepted in the request body. Successful changes must update
        CV-source freshness metadata.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudentProfileUpdateRequest'
      parameters:
        - $ref: '#/components/parameters/IfMatchVersion'
  /me/profile/upload-policy:
    get:
      tags:
        - Student Profile
      summary: Retrieve the active upload constraints for Student profile files.
      operationId: getMeProfileUploadPolicy
      description:
        'Access: Student. Audit: No. Returns server-controlled MIME-type and maximum-size limits so the frontend
        can validate and display accurate upload guidance without hardcoded limits.'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileUploadPolicyResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
  /me/profile/photo:
    put:
      tags:
        - Student Profile
      summary: Upload or replace the authenticated Student profile photo.
      operationId: putMeProfilePhoto
      description:
        'Access: Student. Audit: Yes. Replaces the current profile photo atomically after ownership, MIME-type,
        size, and file-safety validation. Returns the updated Profile and incremented version.'
      parameters:
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Profile image that satisfies the current profilePhoto upload policy.
      responses:
        '200':
          description: Profile photo updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentProfileResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '413':
          $ref: '#/components/responses/Error413'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
    delete:
      tags:
        - Student Profile
      summary: Remove the authenticated Student profile photo.
      operationId: deleteMeProfilePhoto
      description:
        'Access: Student. Audit: Yes. Removes only the authenticated Student’s current profile photo and returns
        the updated Profile.'
      parameters:
        - $ref: '#/components/parameters/IfMatchVersion'
      responses:
        '200':
          description: Profile photo removed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentProfileResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
  /me/profile/contact-links:
    get:
      tags:
        - Student Profile
      summary: List own Student contact link records used by profile and CV generation.
      operationId: getMeProfileContactLinks
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedContactLinkResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: No. Own records only. Search applies to label and URL. Approved sort fields: displayOrder,
        label, createdAt, updatedAt.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
    post:
      tags:
        - Student Profile
      summary: Create an own Student contact link record.
      operationId: postMeProfileContactLinks
      responses:
        '201':
          description: Resource created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactLinkResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Own records only.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactLinkCreateRequest'
  /me/profile/contact-links/{contactLinkId}:
    patch:
      tags:
        - Student Profile
      summary: Update an own Student contact link record.
      operationId: patchMeProfileContactLinksByContactLinkId
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactLinkResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: contactLinkId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: contactLinkId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactLinkUpdateRequest'
    delete:
      tags:
        - Student Profile
      summary: Delete an own Student contact link record.
      operationId: deleteMeProfileContactLinksByContactLinkId
      responses:
        '204':
          description: Resource deleted successfully; no response body.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: contactLinkId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: contactLinkId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
  /me/profile/certificates:
    get:
      tags:
        - Student Profile
      summary: List own Student certificate records used by profile and CV generation.
      operationId: getMeProfileCertificates
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedCertificateResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: No. Own records only. Search applies to title and issuer. Approved sort fields:
        issueDate, title, createdAt, updatedAt.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
    post:
      tags:
        - Student Profile
      summary: Create an own Student certificate record.
      operationId: postMeProfileCertificates
      responses:
        '201':
          description: Resource created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Own records only.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateCreateRequest'
  /me/profile/certificates/{certificateId}:
    patch:
      tags:
        - Student Profile
      summary: Update an own Student certificate record.
      operationId: patchMeProfileCertificatesByCertificateId
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: certificateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: certificateId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateUpdateRequest'
    delete:
      tags:
        - Student Profile
      summary: Delete an own Student certificate record.
      operationId: deleteMeProfileCertificatesByCertificateId
      responses:
        '204':
          description: Resource deleted successfully; no response body.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: certificateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: certificateId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
  /me/profile/certificates/{certificateId}/evidence:
    put:
      tags:
        - Student Profile
      summary: Upload or replace evidence for an authenticated Student certificate.
      operationId: putMeProfileCertificateEvidence
      description:
        'Access: Student. Audit: Yes. Associates one PDF, JPEG, or PNG evidence file with the owned certificate
        after file and ownership validation. Returns the updated certificate and version.'
      parameters:
        - name: certificateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Owned certificate identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Certificate evidence file that satisfies the current certificateEvidence upload policy.
      responses:
        '200':
          description: Certificate evidence updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '413':
          $ref: '#/components/responses/Error413'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
    delete:
      tags:
        - Student Profile
      summary: Remove evidence from an authenticated Student certificate.
      operationId: deleteMeProfileCertificateEvidence
      description:
        'Access: Student. Audit: Yes. Removes only the evidence associated with the owned certificate and returns
        the updated certificate.'
      parameters:
        - name: certificateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Owned certificate identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      responses:
        '200':
          description: Certificate evidence removed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
  /me/profile/awards:
    get:
      tags:
        - Student Profile
      summary: List own Student award records used by profile and CV generation.
      operationId: getMeProfileAwards
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAwardResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: No. Own records only. Search applies to title, issuer, and description. Approved
        sort fields: awardDate, title, createdAt, updatedAt.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
    post:
      tags:
        - Student Profile
      summary: Create an own Student award record.
      operationId: postMeProfileAwards
      responses:
        '201':
          description: Resource created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Own records only.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardCreateRequest'
  /me/profile/awards/{awardId}:
    patch:
      tags:
        - Student Profile
      summary: Update an own Student award record.
      operationId: patchMeProfileAwardsByAwardId
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: awardId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: awardId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardUpdateRequest'
    delete:
      tags:
        - Student Profile
      summary: Delete an own Student award record.
      operationId: deleteMeProfileAwardsByAwardId
      responses:
        '204':
          description: Resource deleted successfully; no response body.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: awardId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: awardId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
  /me/profile/activities:
    get:
      tags:
        - Student Profile
      summary: List own Student activity records used by profile and CV generation.
      operationId: getMeProfileActivities
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedActivityResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: No. Own records only. Search applies to activityName, roleTitle, and description.
        Approved sort fields: startDate, activityName, createdAt, updatedAt.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
    post:
      tags:
        - Student Profile
      summary: Create an own Student activity record.
      operationId: postMeProfileActivities
      responses:
        '201':
          description: Resource created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Own records only.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityCreateRequest'
  /me/profile/activities/{activityId}:
    patch:
      tags:
        - Student Profile
      summary: Update an own Student activity record.
      operationId: patchMeProfileActivitiesByActivityId
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: activityId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: activityId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityUpdateRequest'
    delete:
      tags:
        - Student Profile
      summary: Delete an own Student activity record.
      operationId: deleteMeProfileActivitiesByActivityId
      responses:
        '204':
          description: Resource deleted successfully; no response body.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: activityId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: activityId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
  /me/profile/experience:
    get:
      tags:
        - Student Profile
      summary: List own Student experience records used by profile and CV generation.
      operationId: getMeProfileExperience
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedExperienceResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: No. Own records only. Search applies to organization, positionTitle, location,
        and description. Approved sort fields: startDate, organization, positionTitle, createdAt, updatedAt.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
    post:
      tags:
        - Student Profile
      summary: Create an own Student experience record.
      operationId: postMeProfileExperience
      responses:
        '201':
          description: Resource created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperienceResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Own records only.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperienceCreateRequest'
  /me/profile/experience/{experienceId}:
    patch:
      tags:
        - Student Profile
      summary: Update an own Student experience record.
      operationId: patchMeProfileExperienceByExperienceId
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperienceResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: experienceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: experienceId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperienceUpdateRequest'
    delete:
      tags:
        - Student Profile
      summary: Delete an own Student experience record.
      operationId: deleteMeProfileExperienceByExperienceId
      responses:
        '204':
          description: Resource deleted successfully; no response body.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '428':
          $ref: '#/components/responses/Error428'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: Yes. Object ownership is mandatory.'
      parameters:
        - name: experienceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: experienceId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
  /skill-taxonomy:
    get:
      tags:
        - Declared Skills and Taxonomy
      summary: Read developer-managed skill taxonomy tree.
      operationId: getSkillTaxonomy
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillTaxonomyResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student/Admin. Audit: No. Read-only developer-managed taxonomy. A cross-mapped skill may appear
        in multiple categories but retains one canonical UUID. No Admin or Student taxonomy mutation API exists.'
  /skill-taxonomy/clusters:
    get:
      tags:
        - Declared Skills and Taxonomy
      summary: List skill clusters.
      operationId: getSkillTaxonomyClusters
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSkillClusterResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student/Admin. Audit: No. Server-side search applies to cluster names. Results use stable UUIDs
        and API-provided dynamic data.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
  /skill-taxonomy/categories:
    get:
      tags:
        - Declared Skills and Taxonomy
      summary: List skill categories with optional cluster filters.
      operationId: getSkillTaxonomyCategories
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSkillCategoryResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student/Admin. Audit: No. Server-side search applies to category names. clusterId limits results
        to categories belonging to the selected Core Cluster.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/ClusterIdFilter'
  /skill-taxonomy/skills:
    get:
      tags:
        - Declared Skills and Taxonomy
      summary: List individual skills selectable by Students and Admin filtering.
      operationId: getSkillTaxonomySkills
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedIndividualSkillResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student/Admin. Audit: No. Returns active/selectable canonical Individual Skills only. Server-side
        search applies to approved skill-name/alias fields. clusterId and categoryId are conjunctive when both are supplied.
        Cross-mapped skills reuse one skillId instead of duplicate records.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/ClusterIdFilter'
        - $ref: '#/components/parameters/CategoryIdFilter'
  /me/declared-skills:
    get:
      tags:
        - Declared Skills and Taxonomy
      summary: List own declared skills and competency levels.
      operationId: getMeDeclaredSkills
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDeclaredSkillResponse'
              examples:
                declaredSkillsPage:
                  summary: Paged declared-skill response
                  value:
                    items:
                      - declaredSkillId: 550e8400-e29b-41d4-a716-446655440001
                        skillId: 11111111-1111-4111-8111-111111111111
                        skillName: React
                        competencyLevel: INTERMEDIATE
                        version: 3
                        createdAt: '2026-07-16T08:30:00Z'
                        updatedAt: '2026-07-16T09:15:00Z'
                    page:
                      page: 0
                      size: 20
                      totalElements: 1
                      totalPages: 1
                      sort: skillName,asc
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: No. Returns only the authenticated Student’s declared skills. Server-side search
        applies to skillName; supported sorting includes skillName, competencyLevel, and updatedAt. No verified-skill state
        exists.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
    post:
      tags:
        - Declared Skills and Taxonomy
      summary: Declare a skill from the developer-managed taxonomy.
      operationId: postMeDeclaredSkills
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclaredSkillResponse'
              examples:
                declaredSkillCreated:
                  summary: Created declared skill
                  value:
                    declaredSkillId: 550e8400-e29b-41d4-a716-446655440001
                    skillId: 11111111-1111-4111-8111-111111111111
                    skillName: React
                    competencyLevel: INTERMEDIATE
                    version: 3
                    createdAt: '2026-07-16T08:30:00Z'
                    updatedAt: '2026-07-16T09:15:00Z'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/DuplicateDeclaredSkill409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: Yes. Declares one active/selectable taxonomy skill for the authenticated Student.
        Duplicate declarations return 409. Successful changes update CV-source freshness metadata.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeclaredSkillCreateRequest'
            examples:
              declareSkill:
                summary: Declare React
                value:
                  skillId: 11111111-1111-4111-8111-111111111111
                  competencyLevel: INTERMEDIATE
  /me/declared-skills/{declaredSkillId}:
    patch:
      tags:
        - Declared Skills and Taxonomy
      summary: Update own declared skill competency level.
      operationId: patchMeDeclaredSkillsByDeclaredSkillId
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclaredSkillResponse'
              examples:
                declaredSkillUpdated:
                  summary: Updated declared skill
                  value:
                    declaredSkillId: 550e8400-e29b-41d4-a716-446655440001
                    skillId: 11111111-1111-4111-8111-111111111111
                    skillName: React
                    competencyLevel: ADVANCED
                    version: 4
                    createdAt: '2026-07-16T08:30:00Z'
                    updatedAt: '2026-07-16T10:00:00Z'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
      description:
        'Access: Student. Audit: Yes. Updates only the competency level of an owned declared-skill record. The
        taxonomy skill reference is immutable. If-Match is required; successful changes update CV-source freshness metadata.'
      parameters:
        - name: declaredSkillId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: declaredSkillId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeclaredSkillUpdateRequest'
            examples:
              updateCompetency:
                summary: Promote competency
                value:
                  competencyLevel: ADVANCED
    delete:
      tags:
        - Declared Skills and Taxonomy
      summary: Remove an own declared skill.
      operationId: deleteMeDeclaredSkillsByDeclaredSkillId
      responses:
        '204':
          description: No content.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
      description:
        'Access: Student. Audit: Yes. Removes an owned declared-skill record. If-Match is required; successful
        removal updates CV-source freshness metadata.'
      parameters:
        - name: declaredSkillId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: declaredSkillId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
  /me/projects:
    get:
      tags:
        - Project Portfolio
      summary: List own portfolio projects.
      operationId: getMeProjects
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedProjectResponse'
              examples:
                projectsPage:
                  summary: Paged project response
                  value:
                    items:
                      - projectId: 660e8400-e29b-41d4-a716-446655440001
                        title: Accessible Internship Portal
                        description: A responsive portfolio project for managing structured internship application data.
                        repositoryUrl: https://github.com/example/accessible-internship-portal
                        demoUrl: null
                        startDate: '2026-01-10'
                        endDate: '2026-05-15'
                        skills:
                          - skillId: 11111111-1111-4111-8111-111111111111
                            name: React
                            description: Component-based frontend library.
                          - skillId: 22222222-2222-4222-8222-222222222222
                            name: TypeScript
                            description: null
                        includeInCv: true
                        version: 2
                        createdAt: '2026-07-16T08:00:00Z'
                        updatedAt: '2026-07-16T09:45:00Z'
                    page:
                      page: 0
                      size: 20
                      totalElements: 1
                      totalPages: 1
                      sort: updatedAt,desc
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: No. Returns only the authenticated Student’s portfolio projects. Server-side search
        covers title, description, and associated skill name. Supported sorting includes title, startDate, and updatedAt.
        Projects remain portfolio-only and do not affect candidate filtering.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
    post:
      tags:
        - Project Portfolio
      summary: Create own portfolio project.
      operationId: postMeProjects
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
              examples:
                projectCreated:
                  summary: Created project
                  value:
                    projectId: 660e8400-e29b-41d4-a716-446655440001
                    title: Accessible Internship Portal
                    description: A responsive portfolio project for managing structured internship application data.
                    repositoryUrl: https://github.com/example/accessible-internship-portal
                    demoUrl: null
                    startDate: '2026-01-10'
                    endDate: '2026-05-15'
                    skills:
                      - skillId: 11111111-1111-4111-8111-111111111111
                        name: React
                        description: Component-based frontend library.
                      - skillId: 22222222-2222-4222-8222-222222222222
                        name: TypeScript
                        description: null
                    includeInCv: true
                    version: 2
                    createdAt: '2026-07-16T08:00:00Z'
                    updatedAt: '2026-07-16T09:45:00Z'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/InvalidProjectDateRange422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description:
        'Access: Student. Audit: Yes. Creates one Student-owned portfolio project and its normalized project-skill
        mappings as a single transaction. Technologies are supplied only as skillIds. Successful changes update CV-source
        freshness metadata.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreateRequest'
            examples:
              createProject:
                summary: Create portfolio project
                value:
                  title: Accessible Internship Portal
                  description: A responsive portfolio project for managing structured internship application data.
                  repositoryUrl: https://github.com/example/accessible-internship-portal
                  demoUrl: null
                  startDate: '2026-01-10'
                  endDate: '2026-05-15'
                  skillIds:
                    - 11111111-1111-4111-8111-111111111111
                    - 22222222-2222-4222-8222-222222222222
                  includeInCv: true
  /me/projects/{projectId}:
    get:
      tags:
        - Project Portfolio
      summary: Retrieve own portfolio project.
      operationId: getMeProjectsByProjectId
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
              examples:
                project:
                  summary: Portfolio project
                  value:
                    projectId: 660e8400-e29b-41d4-a716-446655440001
                    title: Accessible Internship Portal
                    description: A responsive portfolio project for managing structured internship application data.
                    repositoryUrl: https://github.com/example/accessible-internship-portal
                    demoUrl: null
                    startDate: '2026-01-10'
                    endDate: '2026-05-15'
                    skills:
                      - skillId: 11111111-1111-4111-8111-111111111111
                        name: React
                        description: Component-based frontend library.
                      - skillId: 22222222-2222-4222-8222-222222222222
                        name: TypeScript
                        description: null
                    includeInCv: true
                    version: 2
                    createdAt: '2026-07-16T08:00:00Z'
                    updatedAt: '2026-07-16T09:45:00Z'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Student. Audit: No. Retrieves one portfolio-only project owned by the authenticated Student.'
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: projectId identifier.
    patch:
      tags:
        - Project Portfolio
      summary: Update own portfolio project.
      operationId: patchMeProjectsByProjectId
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
              examples:
                projectUpdated:
                  summary: Updated project
                  value:
                    projectId: 660e8400-e29b-41d4-a716-446655440001
                    title: Accessible Internship Portal
                    description: Updated project summary with improved accessibility and validation coverage.
                    repositoryUrl: https://github.com/example/accessible-internship-portal
                    demoUrl: https://example.test/accessible-internship-portal
                    startDate: '2026-01-10'
                    endDate: '2026-05-15'
                    skills:
                      - skillId: 11111111-1111-4111-8111-111111111111
                        name: React
                        description: Component-based frontend library.
                      - skillId: 22222222-2222-4222-8222-222222222222
                        name: TypeScript
                        description: null
                    includeInCv: true
                    version: 3
                    createdAt: '2026-07-16T08:00:00Z'
                    updatedAt: '2026-07-16T10:15:00Z'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/StaleProjectVersion412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/InvalidProjectDateRange422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
      description:
        'Access: Student. Audit: Yes. Applies a true partial update to an owned portfolio project. The project
        row and project-skill mappings change atomically. If-Match is required; successful changes update CV-source freshness
        metadata. No reviewer, approval, verification, eligibility, score, or rank fields exist.'
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: projectId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectUpdateRequest'
            examples:
              updateProject:
                summary: Partially update project
                value:
                  description: Updated project summary with improved accessibility and validation coverage.
                  demoUrl: https://example.test/accessible-internship-portal
                  includeInCv: true
    delete:
      tags:
        - Project Portfolio
      summary: Delete own portfolio project.
      operationId: deleteMeProjectsByProjectId
      responses:
        '204':
          description: No content.
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
      description:
        'Access: Student. Audit: Yes. Deletes one owned portfolio project and its project-skill mappings atomically.
        If-Match is required; successful removal updates CV-source freshness metadata.'
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: projectId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
  /me/academic-records:
    get:
      tags:
        - Academic Records
      summary: Read own official committed academic records.
      operationId: getMeAcademicRecords
      responses:
        '200':
          description: Official committed academic records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAcademicRecordResponse'
              examples:
                recordsAvailable:
                  summary: Committed academic records
                  value:
                    items:
                      - academicRecordId: 10000000-0000-4000-8000-000000000001
                        subjectId: 20000000-0000-4000-8000-000000000001
                        courseCode: CSC3112
                        courseTitle: Web Technologies
                        credits: 4.0
                        letterGrade: A-
                        gradePoint: 3.7
                        semester: Semester 1
                        academicYear: 2025/2026
                        attemptNumber: 1
                        resultStatus: PASSED
                        committedAt: '2026-07-20T09:30:00Z'
                      - academicRecordId: 10000000-0000-4000-8000-000000000002
                        subjectId: 20000000-0000-4000-8000-000000000002
                        courseCode: CSC3122
                        courseTitle: Software Engineering
                        credits: 3.0
                        letterGrade: A
                        gradePoint: 4.0
                        semester: Semester 1
                        academicYear: 2025/2026
                        attemptNumber: 1
                        resultStatus: PASSED
                        committedAt: '2026-07-20T09:30:00Z'
                    page:
                      page: 0
                      size: 20
                      totalElements: 2
                      totalPages: 1
                      sort: academicYear,desc
                noCommittedRecords:
                  summary: No committed records
                  value:
                    items: []
                    page:
                      page: 0
                      size: 20
                      totalElements: 0
                      totalPages: 0
                      sort: academicYear,desc
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/AcademicDataUnavailable503'
      description:
        'Access: Student. Audit: No. Owner-scoped read-only committed ledger data. Search applies to courseCode
        and courseTitle. Supported sort properties are academicYear, semester, courseCode, courseTitle, credits, letterGrade,
        gradePoint, and committedAt. An ordinary no-record state returns 200 with items: [] and valid PageMetadata.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
      security:
        - bearerAuth: []
  /me/academic-records/gpa:
    get:
      tags:
        - Academic Records
      summary: Read own official Computer Science GPA summary.
      operationId: getMeAcademicRecordsGpa
      responses:
        '200':
          description: Official Computer Science GPA summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GpaSummaryResponse'
              examples:
                gpaAvailable:
                  summary: Official GPA available
                  value:
                    studentId: 30000000-0000-4000-8000-000000000001
                    status: AVAILABLE
                    computerScienceGpa: 3.75
                    totalCredits: 42.0
                    calculatedAt: '2026-07-20T09:35:00Z'
                    source:
                      sourceUploadId: 40000000-0000-4000-8000-000000000001
                      committedAt: '2026-07-20T09:30:00Z'
                gpaNotAvailable:
                  summary: No committed academic records
                  value:
                    studentId: 30000000-0000-4000-8000-000000000002
                    status: NOT_AVAILABLE
                    computerScienceGpa: null
                    totalCredits: null
                    calculatedAt: null
                    source: null
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/AcademicDataUnavailable503'
      description:
        'Access: Student. Audit: No. Owner-scoped official Computer Science GPA derived only from committed ledger
        data. No committed records is represented by a successful NOT_AVAILABLE response, not 404.'
      security:
        - bearerAuth: []
  /me/cv/source-freshness:
    get:
      tags:
        - CV Generation and Active CV
      summary: Check whether saved CV source data is current.
      operationId: getMeCvSourceFreshness
      responses:
        '200':
          description: Typed CV source freshness.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CvFreshnessResponse'
              examples:
                noSavedCv:
                  summary: No saved CV exists
                  value:
                    status: NOT_SAVED
                    changedAreas: []
                    cvId: null
                    savedAt: null
                    evaluatedAt: '2026-07-21T08:00:00Z'
                    message: No saved CV exists yet.
                currentCv:
                  summary: Latest saved CV is current
                  value:
                    status: CURRENT
                    changedAreas: []
                    cvId: 50000000-0000-4000-8000-000000000001
                    savedAt: '2026-07-21T07:30:00Z'
                    evaluatedAt: '2026-07-21T08:00:00Z'
                    message: The latest saved CV matches current source data.
                outdatedAfterProfile:
                  summary: Outdated after profile change
                  value:
                    status: OUTDATED
                    changedAreas:
                      - PROFILE
                    cvId: 50000000-0000-4000-8000-000000000001
                    savedAt: '2026-07-21T07:30:00Z'
                    evaluatedAt: '2026-07-21T08:00:00Z'
                    message: Profile data changed after the latest CV was saved.
                outdatedAfterSkillsProjects:
                  summary: Outdated after skill/project changes
                  value:
                    status: OUTDATED
                    changedAreas:
                      - DECLARED_SKILLS
                      - PROJECTS
                    cvId: 50000000-0000-4000-8000-000000000001
                    savedAt: '2026-07-21T07:30:00Z'
                    evaluatedAt: '2026-07-21T08:00:00Z'
                    message: Declared skills or projects changed after the latest CV was saved.
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/CvGenerationFailed503'
      description:
        'Access: Student. Audit: No. Owner-scoped notice comparing current approved CV source areas with the latest
        saved CV. NOT_SAVED is a successful first-time state. This operation creates no submission, review, or approval state.'
      security:
        - bearerAuth: []
  /me/cv/preview:
    post:
      tags:
        - CV Generation and Active CV
      summary: Generate a backend-controlled ATS-compliant CV preview in the fixed default order.
      operationId: postMeCvPreview
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CvPreviewRequest'
      responses:
        '200':
          description: Generated sanitized HTML preview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CvPreviewResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/InvalidCvConfiguration422'
        '429':
          $ref: '#/components/responses/Error429'
        '503':
          $ref: '#/components/responses/CvGenerationFailed503'
      description:
        'Access: Student. Audit: Yes. Generates an expiring owner-scoped preview. The backend applies the fixed
        approved section order and validates every selected source record against the authenticated Student. No internal generator
        source or governance state is exposed.'
      security:
        - bearerAuth: []
  /me/cv:
    get:
      tags:
        - CV Generation and Active CV
      summary: Retrieve the authenticated Student's active saved CV metadata.
      operationId: getMeCv
      responses:
        '200':
          description: Active saved CV metadata.
          headers:
            ETag:
              required: true
              schema:
                type: string
              description: Quoted current revision used for conditional replacement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CvResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/NoSavedCv404'
      description: 'Access: Student. Audit: No. Returns only the authenticated Student owner’s single active CV.'
      security:
        - bearerAuth: []
    put:
      tags:
        - CV Generation and Active CV
      summary: Create or replace the authenticated Student's active CV from a confirmed preview.
      operationId: putMeCv
      parameters:
        - name: If-Match
          in: header
          required: false
          schema:
            type: string
          description: Required for replacement and must contain the quoted current revision.
        - name: If-None-Match
          in: header
          required: false
          schema:
            type: string
            enum:
              - '*'
          description: Required with value * for first creation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CvSaveRequest'
      responses:
        '200':
          description: Existing active CV replaced atomically.
          headers:
            ETag:
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CvResponse'
        '201':
          description: First active CV created.
          headers:
            ETag:
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CvResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '409':
          $ref: '#/components/responses/CvPreviewExpired409'
        '412':
          $ref: '#/components/responses/StaleCv412'
        '422':
          $ref: '#/components/responses/InvalidCvConfiguration422'
        '428':
          $ref: '#/components/responses/CvPreconditionRequired428'
      description:
        'Access: Student. Audit: Yes. Saves the exact unexpired preview. The first save requires If-None-Match:
        *; replacement requires If-Match. The unique owner row, PDF reference, source fingerprint, and revision are replaced
        atomically.'
      security:
        - bearerAuth: []
  /me/cv/download:
    get:
      tags:
        - CV Generation and Active CV
      summary: Download the authenticated Student's active saved CV PDF.
      operationId: getMeCvDownload
      responses:
        '200':
          description: ATS-compliant PDF attachment.
          headers:
            Content-Disposition:
              required: true
              schema:
                type: string
                pattern: ^attachment; filename="[A-Za-z0-9._-]+\.pdf"$
            Cache-Control:
              required: true
              schema:
                type: string
                enum:
                  - no-store
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/NoSavedCv404'
        '503':
          $ref: '#/components/responses/CvFileUnavailable503'
      description:
        'Access: Student. Audit: Yes. Downloads only the owner’s current saved PDF and never creates another CV
        record.'
      security:
        - bearerAuth: []
  /admin/dashboard/metrics:
    get:
      tags:
        - Admin Dashboard
      summary: Retrieve live Admin dashboard metrics.
      operationId: getAdminDashboardMetrics
      description:
        'Access: Admin. Audit: No for ordinary reads. Read-only. Returns persisted or backend-computed values;
        wireframe demonstration counts are non-authoritative.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      responses:
        '200':
          description: Current persisted Admin dashboard metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDashboardMetricsResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/AdminDashboardUnavailable503'
  /admin/academic-ledger/uploads:
    post:
      tags:
        - Academic Ledger
      summary: Accept an official academic-ledger CSV for asynchronous parsing, staging, and validation.
      operationId: postAdminAcademicLedgerUploads
      description:
        'Access: Admin. Audit: Yes for acceptance and failure. Mutation: creates a staging batch only. The request
        never commits official academic data. Poll the Location resource no faster than Retry-After.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      x-state-preconditions:
        - Authenticated predefined Admin
        - UTF-8 CSV
        - File size <= 5 MiB
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AcademicLedgerUploadRequest'
            encoding:
              file:
                contentType: text/csv
      responses:
        '202':
          description: Upload accepted. Parsing, staging, and validation continue asynchronously.
          headers:
            Location:
              $ref: '#/components/headers/Location'
            Retry-After:
              $ref: '#/components/headers/RetryAfterSeconds'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcademicLedgerUploadDetailResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '409':
          $ref: '#/components/responses/LedgerDuplicateUpload409'
        '413':
          $ref: '#/components/responses/LedgerFileTooLarge413'
        '415':
          $ref: '#/components/responses/LedgerUnsupportedMediaType415'
        '422':
          $ref: '#/components/responses/LedgerParseFailed422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
    get:
      tags:
        - Academic Ledger
      summary: List academic-ledger upload batches.
      operationId: getAdminAcademicLedgerUploads
      description: 'Access: Admin. Audit: No for ordinary reads. Read-only server-side search, filters, sorting, and pagination.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/LedgerUploadSort'
        - $ref: '#/components/parameters/LedgerSearch'
        - $ref: '#/components/parameters/LedgerUploadStatusFilter'
        - $ref: '#/components/parameters/LedgerValidationStatusFilter'
      responses:
        '200':
          description: 'Typed upload-batch page. No matches return items: [].'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAcademicLedgerUploadResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
  /admin/academic-ledger/uploads/{uploadId}:
    get:
      tags:
        - Academic Ledger
      summary: Retrieve an academic-ledger upload batch and its current lifecycle state.
      operationId: getAdminAcademicLedgerUploadsByUploadId
      description:
        'Access: Admin. Audit: No. Read-only polling/status resource. Temporary states include a nextPollAfterSeconds
        hint.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Academic-ledger upload identifier.
      responses:
        '200':
          description: Current upload-batch detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcademicLedgerUploadDetailResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/LedgerBatchNotFound404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
  /admin/academic-ledger/uploads/{uploadId}/validation-results:
    get:
      tags:
        - Academic Ledger
      summary: Retrieve typed validation results for an academic-ledger upload.
      operationId: getAdminAcademicLedgerUploadsByUploadIdValidationResults
      description: 'Access: Admin. Audit: No. Read-only. Validation failure never commits official academic data.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      x-state-preconditions:
        - Validation has started or completed
      parameters:
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Academic-ledger upload identifier.
      responses:
        '200':
          description: Validation summary and safe row-level diagnostics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcademicLedgerValidationResultResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/LedgerBatchNotFound404'
        '409':
          $ref: '#/components/responses/LedgerNotReady409'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
  /admin/academic-ledger/uploads/{uploadId}/commit:
    post:
      tags:
        - Academic Ledger
      summary: Atomically commit a validated academic-ledger upload.
      operationId: postAdminAcademicLedgerUploadsByUploadIdCommit
      description:
        'Access: Admin. Audit: Yes for success and failure. Mutation: promotes all staged rows to official grades
        and recalculates affected Computer Science GPA summaries in one transaction. A backend row/state lock performs READY_TO_COMMIT
        -> COMMITTING -> COMMITTED. Concurrent or repeated commits return 409. A failed transaction is fully rolled back and
        the batch returns to READY_TO_COMMIT for a safe retry.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      x-state-preconditions:
        - Upload status is READY_TO_COMMIT
        - Validation status is PASSED
        - invalidRows is zero
      parameters:
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Academic-ledger upload identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcademicLedgerCommitRequest'
      responses:
        '200':
          description: All official records and GPA summaries committed atomically.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcademicLedgerCommitResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/LedgerBatchNotFound404'
        '409':
          $ref: '#/components/responses/LedgerCommitState409'
        '422':
          $ref: '#/components/responses/LedgerValidationFailed422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/LedgerCommitFailed500'
        '503':
          $ref: '#/components/responses/Error503'
  /admin/academic-records:
    get:
      tags:
        - Academic Ledger
      summary: List committed official academic records across registered Students.
      operationId: getAdminAcademicRecords
      description: 'Access: Admin. Audit: No for ordinary reads. Read-only global inspection; no mutation endpoint exists.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/AcademicRecordSort'
        - $ref: '#/components/parameters/AcademicRecordSearch'
        - $ref: '#/components/parameters/CourseCodeFilter'
        - $ref: '#/components/parameters/StudentIdFilter'
      responses:
        '200':
          description: 'Typed committed academic-record page. No matches return items: [].'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAcademicRecordResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/AcademicDataUnavailable503'
  /admin/students:
    get:
      tags:
        - Registered Students
      summary: Search, filter, sort, and paginate registered Students.
      operationId: getAdminStudents
      description:
        'Access: Admin. Audit: No for ordinary list reads. Read-only. Search covers full name, index number, university
        email, and academic batch. Empty results return 200 with items: [].'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/RegisteredStudentSort'
        - $ref: '#/components/parameters/RegisteredStudentSearch'
        - $ref: '#/components/parameters/RegisteredStudentLevel'
      responses:
        '200':
          description: Typed Registered Students page. page.totalElements supplies the live roster count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedStudentSummaryResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/AcademicDataUnavailable503'
  /admin/students/{studentId}:
    get:
      tags:
        - Registered Students
      summary: Retrieve read-only Student deep-dive details.
      operationId: getAdminStudentsByStudentId
      description:
        Admin-only read. Returns identity/profile/CV-supporting summary; declared skills, projects, and academic
        records are separate paged reads. No Admin Student mutation exists.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: studentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable studentId identifier.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminStudentDetailResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/RegisteredStudentNotFound404'
        '503':
          $ref: '#/components/responses/Error503'
  /admin/students/{studentId}/academic-records:
    get:
      tags:
        - Registered Students
      summary: Retrieve one registered Student’s committed official academic records.
      operationId: getAdminStudentsByStudentIdAcademicRecords
      description:
        'Access: Admin. Audit: No for ordinary reads. Read-only. Supports the Academic Ledger Student details modal.
        No records return 200 with items: []; no mutation operation exists.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: studentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable registered Student identifier.
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/AcademicRecordSort'
        - $ref: '#/components/parameters/AcademicRecordSearch'
        - $ref: '#/components/parameters/CourseCodeFilter'
      responses:
        '200':
          description: Typed committed academic-record page for the selected Student.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAcademicRecordResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/RegisteredStudentNotFound404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/AcademicDataUnavailable503'
  /admin/students/{studentId}/declared-skills:
    get:
      tags:
        - Registered Students
      summary: Retrieve Student declared skills for read-only inspection.
      operationId: getAdminStudentsByStudentIdDeclaredSkills
      description: Admin-only read. No verification, approval, reviewer, score, rank, or mutation state is returned.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: studentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable studentId identifier.
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDeclaredSkillResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/RegisteredStudentNotFound404'
        '503':
          $ref: '#/components/responses/Error503'
  /admin/students/{studentId}/projects:
    get:
      tags:
        - Registered Students
      summary: Retrieve Student portfolio projects for read-only inspection.
      operationId: getAdminStudentsByStudentIdProjects
      description: Admin-only read. No verification, approval, reviewer, score, rank, or mutation state is returned.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: studentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable studentId identifier.
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedProjectResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/RegisteredStudentNotFound404'
        '503':
          $ref: '#/components/responses/Error503'
  /admin/students/{studentId}/latest-cv:
    get:
      tags:
        - Registered Students
      summary: Retrieve latest saved CV availability and metadata.
      operationId: getAdminStudentsByStudentIdLatestCv
      description: Admin-only read. Returns 200 with AVAILABLE or NOT_SAVED; it creates no CV submission or review lifecycle.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: studentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable studentId identifier.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminLatestCvResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/RegisteredStudentNotFound404'
        '503':
          $ref: '#/components/responses/Error503'
  /admin/students/{studentId}/latest-cv/download:
    get:
      tags:
        - Registered Students
      summary: Download latest saved Student CV PDF.
      operationId: getAdminStudentsByStudentIdLatestCvDownload
      description: Admin-only audited read of the latest saved ATS-compliant PDF. Storage paths are never exposed.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: false
      parameters:
        - name: studentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable studentId identifier.
      responses:
        '200':
          description: Latest saved ATS-compliant CV PDF attachment.
          headers:
            Content-Disposition:
              $ref: '#/components/headers/ContentDispositionPdf'
            Cache-Control:
              $ref: '#/components/headers/CacheControlNoStore'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/NoSavedCv404'
        '503':
          $ref: '#/components/responses/CvFileUnavailable503'
  /admin/companies:
    get:
      tags:
        - Company Metadata
      summary: List company metadata records.
      operationId: getAdminCompanies
      description:
        Admin-only server-side list. Search covers company name and approved contact fields. Companies are external
        stakeholders with no login.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/CompanySort'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedCompanyResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
    post:
      tags:
        - Company Metadata
      summary: Create company metadata record.
      operationId: postAdminCompanies
      description: Admin-only audited metadata creation. No company account is created.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyRequest'
      responses:
        '201':
          description: Company created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '409':
          $ref: '#/components/responses/DuplicateCompany409'
  /admin/companies/{companyId}:
    get:
      tags:
        - Company Metadata
      summary: Retrieve company metadata record.
      operationId: getAdminCompaniesByCompanyId
      description: Admin-only metadata read.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable companyId identifier.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/CompanyNotFound404'
    patch:
      tags:
        - Company Metadata
      summary: Update company metadata record.
      operationId: patchAdminCompaniesByCompanyId
      description: Admin-only audited partial update with optimistic concurrency.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable companyId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyUpdateRequest'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/CompanyNotFound404'
        '409':
          $ref: '#/components/responses/DuplicateCompany409'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
    delete:
      tags:
        - Company Metadata
      summary: Delete company metadata record.
      operationId: deleteAdminCompaniesByCompanyId
      description: Permanently deletes the company metadata record and its linked internship requests.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable companyId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      responses:
        '204':
          description: Company and linked internship requests were deleted.
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/CompanyNotFound404'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
  /admin/internship-requests:
    get:
      tags:
        - Internship Requests
      summary: List internship requests.
      operationId: getAdminInternshipRequests
      description:
        Admin-only server-side list. Search covers role title and company name. GPA criteria are absent.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/InternshipRequestSort'
        - $ref: '#/components/parameters/CompanyIdFilter'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedInternshipRequestResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
    post:
      tags:
        - Internship Requests
      summary: Create internship request.
      operationId: postAdminInternshipRequests
      description:
        Admin-only audited atomic creation of request metadata and taxonomy-backed required skills. No GPA criteria
        are accepted.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternshipRequestCreateRequest'
      responses:
        '201':
          description: Internship request created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternshipRequestResponse'
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '415':
          $ref: '#/components/responses/Error415'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/CompanyNotFound404'
        '422':
          $ref: '#/components/responses/InvalidTaxonomySkill422'
  /admin/internship-requests/{requestId}:
    get:
      tags:
        - Internship Requests
      summary: Retrieve internship request.
      operationId: getAdminInternshipRequestsByRequestId
      description: Admin-only request read. GPA criteria are absent.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable requestId identifier.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternshipRequestResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/InternshipRequestNotFound404'
    patch:
      tags:
        - Internship Requests
      summary: Update internship request.
      operationId: patchAdminInternshipRequestsByRequestId
      description: Admin-only audited partial update. If requiredSkills is present it atomically replaces the complete set.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable requestId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternshipRequestUpdateRequest'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternshipRequestResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/InternshipRequestNotFound404'
        '422':
          $ref: '#/components/responses/InvalidTaxonomySkill422'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
    delete:
      tags:
        - Internship Requests
      summary: Delete internship request.
      operationId: deleteAdminInternshipRequestsByRequestId
      description: Permanently deletes the internship request when allowed by referential-integrity rules.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable requestId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      responses:
        '204':
          description: Internship request was deleted.
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/InternshipRequestNotFound404'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
  /admin/internship-requests/{requestId}/required-skills:
    get:
      tags:
        - Internship Requests
      summary: List required skills for an internship request.
      operationId: getAdminInternshipRequestsByRequestIdRequiredSkills
      description: Admin-only paged read of normalized taxonomy requirements.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable requestId identifier.
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedInternshipRequiredSkillResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/InternshipRequestNotFound404'
    post:
      tags:
        - Internship Requests
      summary: Add one required skill.
      operationId: postAdminInternshipRequestsByRequestIdRequiredSkills
      description: Incremental audited skill mutation for request editing. Taxonomy is read-only and developer-managed.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable requestId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternshipRequiredSkillRequest'
      responses:
        '201':
          description: Required skill added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternshipRequiredSkillResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/InternshipRequestNotFound404'
        '409':
          $ref: '#/components/responses/DuplicateRequiredSkill409'
        '422':
          $ref: '#/components/responses/InvalidTaxonomySkill422'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
  /admin/internship-requests/{requestId}/required-skills/{requiredSkillId}:
    delete:
      tags:
        - Internship Requests
      summary: Remove one required skill.
      operationId: deleteAdminInternshipRequestsByRequestIdRequiredSkillsByRequiredSkillId
      description: Incremental audited removal from the request. The taxonomy skill itself is never deleted.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable requestId identifier.
        - name: requiredSkillId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable requiredSkillId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      responses:
        '204':
          description: Required-skill association removed.
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/InternshipRequestNotFound404'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
  /admin/candidate-filtering/runs:
    post:
      tags:
        - Candidate Filtering
      summary: Create deterministic filtering run.
      operationId: postAdminCandidateFilteringRuns
      description:
        Persists sanitized runtime criteria and computes deterministic results from latest committed official GPA
        and current declared skills. It never selects candidates.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateFilteringRunRequest'
      responses:
        '201':
          description: Filtering run created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateFilteringRunResponse'
          headers:
            Location:
              $ref: '#/components/headers/Location'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '415':
          $ref: '#/components/responses/Error415'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/InternshipRequestNotFound404'
        '422':
          $ref: '#/components/responses/FilterCriteria422'
        '503':
          $ref: '#/components/responses/FilterDependencyUnavailable503'
  /admin/candidate-filtering/runs/{filterRunId}:
    get:
      tags:
        - Candidate Filtering
      summary: Retrieve filtering run metadata.
      operationId: getAdminCandidateFilteringRunsByFilterRunId
      description: Admin-only read of sanitized runtime criteria and current count metadata.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: filterRunId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable filterRunId identifier.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateFilteringRunResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/FilterRunNotFound404'
        '503':
          $ref: '#/components/responses/FilterDependencyUnavailable503'
  /admin/candidate-filtering/runs/{filterRunId}/candidates:
    get:
      tags:
        - Candidate Filtering
      summary: List deterministic candidate results.
      operationId: getAdminCandidateFilteringRunsByFilterRunIdCandidates
      description:
        Server-side paged results recomputed from latest committed data. Stable order; no score, rank, probability,
        recommendation, or match percentage.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: filterRunId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable filterRunId identifier.
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/CandidateSort'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedCandidateFilteringCandidateResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/FilterRunNotFound404'
        '503':
          $ref: '#/components/responses/FilterDependencyUnavailable503'
  /admin/shortlists:
    get:
      tags:
        - Shortlists
      summary: List shortlists.
      operationId: getAdminShortlists
      description: Admin-only server-side shortlist summary list. Candidate arrays are not embedded in list rows.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/ShortlistSort'
        - $ref: '#/components/parameters/ShortlistStatusFilter'
        - $ref: '#/components/parameters/CompanyIdFilter'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedShortlistResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
    post:
      tags:
        - Shortlists
      summary: Create draft shortlist.
      operationId: postAdminShortlists
      description: Creates the single Version 1 shortlist for a request. It does not infer or auto-select all filtering results.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShortlistCreateRequest'
      responses:
        '201':
          description: Draft shortlist created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortlistResponse'
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/InternshipRequestNotFound404'
        '409':
          $ref: '#/components/responses/ShortlistState409'
  /admin/shortlists/{shortlistId}:
    get:
      tags:
        - Shortlists
      summary: Retrieve shortlist details and paged candidates.
      operationId: getAdminShortlistsByShortlistId
      description: Admin-only shortlist read. Candidate search and sorting are server-side.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: shortlistId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable shortlistId identifier.
        - $ref: '#/components/parameters/CandidatePage'
        - $ref: '#/components/parameters/CandidateSize'
        - $ref: '#/components/parameters/CandidateSearch'
        - $ref: '#/components/parameters/CandidateSort'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortlistDetailResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/ShortlistNotFound404'
  /admin/shortlists/{shortlistId}/candidates:
    post:
      tags:
        - Shortlists
      summary: Add manually selected candidates to a draft shortlist.
      operationId: postAdminShortlistsByShortlistIdCandidates
      description:
        Admin-only audited manual batch addition. Finalized shortlists are immutable; duplicate candidates are
        reported without duplicate rows.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: shortlistId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable shortlistId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShortlistCandidateRequest'
      responses:
        '200':
          description: Candidate selection updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortlistCandidateMutationResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/ShortlistNotFound404'
        '409':
          $ref: '#/components/responses/ShortlistState409'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
  /admin/shortlists/{shortlistId}/candidates/{studentId}:
    delete:
      tags:
        - Shortlists
      summary: Remove one candidate from a draft shortlist.
      operationId: deleteAdminShortlistsByShortlistIdCandidatesByStudentId
      description: Admin-only audited manual removal. Finalized shortlists are immutable.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: shortlistId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable shortlistId identifier.
        - name: studentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable studentId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      responses:
        '200':
          description: Candidate removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortlistCandidateMutationResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/ShortlistNotFound404'
        '409':
          $ref: '#/components/responses/ShortlistState409'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
  /admin/shortlists/{shortlistId}/finalize:
    post:
      tags:
        - Shortlists
      summary: Finalize shortlist.
      operationId: postAdminShortlistsByShortlistIdFinalize
      description:
        Atomically transitions DRAFT to FINALIZED. Guidance is non-blocking after explicit acknowledgement; concurrent
        or repeated finalization is rejected.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: shortlistId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable shortlistId identifier.
        - $ref: '#/components/parameters/IfMatchVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShortlistFinalizeRequest'
      responses:
        '200':
          description: Shortlist finalized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortlistFinalizeResponse'
          headers:
            ETag:
              $ref: '#/components/headers/EntityTag'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/ShortlistNotFound404'
        '409':
          $ref: '#/components/responses/ShortlistGuidanceAcknowledgement409'
        '428':
          $ref: '#/components/responses/MissingIfMatch428'
  /admin/exports/shortlists/{shortlistId}:
    post:
      tags:
        - Exports
      summary: Create final shortlist summary CSV export.
      operationId: postAdminExportsShortlistsByShortlistId
      description: Creates an asynchronous audited CSV export job for a finalized shortlist.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: shortlistId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable shortlistId identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShortlistSummaryExportCreateRequest'
      responses:
        '202':
          description: Export job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
          headers:
            Location:
              $ref: '#/components/headers/Location'
            Retry-After:
              $ref: '#/components/headers/RetryAfterSeconds'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/ShortlistNotFound404'
        '409':
          $ref: '#/components/responses/ShortlistState409'
  /admin/exports/{exportJobId}:
    get:
      tags:
        - Exports
      summary: Retrieve export job status.
      operationId: getAdminExportsByExportJobId
      description: Admin-only status read. Download URLs remain null until completion.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      parameters:
        - name: exportJobId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable exportJobId identifier.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/ExportJobNotFound404'
  /admin/exports/{exportJobId}/download:
    get:
      tags:
        - Exports
      summary: Download completed shortlist summary CSV.
      operationId: getAdminExportsByExportJobIdDownload
      description: Admin-only audited one-purpose CSV download. Storage paths are never exposed.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: false
      parameters:
        - name: exportJobId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable exportJobId identifier.
      responses:
        '200':
          description: Final shortlist summary CSV attachment.
          headers:
            Content-Disposition:
              $ref: '#/components/headers/ContentDispositionCsv'
            Cache-Control:
              $ref: '#/components/headers/CacheControlNoStore'
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/ExportJobNotFound404'
        '409':
          $ref: '#/components/responses/ExportNotReady409'
        '503':
          $ref: '#/components/responses/ExportFileUnavailable503'
  /admin/exports/shortlists/{shortlistId}/bulk-cvs:
    post:
      tags:
        - Exports
      summary: Create bulk latest-saved CV ZIP export.
      operationId: postAdminExportsShortlistsByShortlistIdBulkCvs
      description:
        Creates an asynchronous audited ZIP export containing available latest-saved ATS-compliant PDF CVs. Missing
        CVs are explicitly reported.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: true
      parameters:
        - name: shortlistId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable shortlistId identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCvExportCreateRequest'
      responses:
        '202':
          description: Bulk CV export job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
          headers:
            Location:
              $ref: '#/components/headers/Location'
            Retry-After:
              $ref: '#/components/headers/RetryAfterSeconds'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
        '404':
          $ref: '#/components/responses/ShortlistNotFound404'
        '409':
          $ref: '#/components/responses/ShortlistState409'
  /admin/exports/{exportJobId}/bulk-cvs/download:
    get:
      tags:
        - Exports
      summary: Download completed bulk latest-saved CV ZIP.
      operationId: getAdminExportsByExportJobIdBulkCvsDownload
      description:
        Admin-only audited ZIP download of available latest-saved ATS-compliant PDF CVs. Missing CVs were reported
        by the job status.
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: true
      x-mutation: false
      parameters:
        - name: exportJobId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Stable exportJobId identifier.
      responses:
        '200':
          description: ZIP attachment containing available latest-saved ATS-compliant PDF CVs.
          headers:
            Content-Disposition:
              $ref: '#/components/headers/ContentDispositionZip'
            Cache-Control:
              $ref: '#/components/headers/CacheControlNoStore'
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '404':
          $ref: '#/components/responses/ExportJobNotFound404'
        '409':
          $ref: '#/components/responses/ExportNotReady409'
        '503':
          $ref: '#/components/responses/ExportFileUnavailable503'
  /admin/audit-events:
    get:
      tags:
        - Audit/System Events
      summary: Retrieve Admin-visible audit events when enabled by policy.
      operationId: getAdminAuditEvents
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAuditEventResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '412':
          $ref: '#/components/responses/Error412'
        '415':
          $ref: '#/components/responses/Error415'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      description: 'Access: Admin. Audit: No. May be omitted if audit remains internal backend concern.'
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Search'
  /admin/academic-ledger/uploads/{uploadId}/staged-rows:
    get:
      tags:
        - Academic Ledger
      summary: Retrieve normalized staged rows for an academic-ledger upload.
      operationId: getAdminAcademicLedgerUploadsByUploadIdStagedRows
      description:
        'Access: Admin. Audit: No. Read-only. Staged rows are not official records. Version 1 exposes no update,
        delete, cancel, rollback, or inline-override operation.'
      security:
        - bearerAuth: []
      x-access-role: ADMIN
      x-audit-required: false
      x-mutation: false
      x-state-preconditions:
        - Upload status is STAGED, READY_TO_COMMIT, VALIDATION_FAILED, COMMITTING, or COMMITTED
      parameters:
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Academic-ledger upload identifier.
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/LedgerStagedRowSort'
        - $ref: '#/components/parameters/LedgerStagedRowSearch'
        - $ref: '#/components/parameters/LedgerRowValidationFilter'
      responses:
        '200':
          description: 'Typed staged-row page. No matches return items: [].'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAcademicLedgerStagedRowResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/LedgerBatchNotFound404'
        '409':
          $ref: '#/components/responses/LedgerNotReady409'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Zero-based page index.
    Size:
      name: size
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Page size with an implementation-defined upper bound.
    Sort:
      name: sort
      in: query
      schema:
        type: string
      description: Sort expression such as createdAt,desc.
    Search:
      name: search
      in: query
      schema:
        type: string
      description: Search term applied to approved searchable fields.
    IfMatchVersion:
      name: If-Match
      in: header
      required: true
      schema:
        type: string
        pattern: ^"[0-9]+"$
        examples:
          - '"3"'
      description:
        Quoted entity version from the most recent response, for example `"3"`. The server returns 412 when the
        entity has changed.
    ClusterIdFilter:
      name: clusterId
      in: query
      required: false
      schema:
        type: string
        format: uuid
      description:
        Optional stable Core Cluster identifier. Category results are limited to that cluster; skill results are
        limited to skills mapped through categories in that cluster.
    CategoryIdFilter:
      name: categoryId
      in: query
      required: false
      schema:
        type: string
        format: uuid
      description:
        Optional stable Skill Category identifier. Skill results are limited to canonical Individual Skills mapped
        to this category.
    LedgerUploadSort:
      name: sort
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/AcademicLedgerUploadSort'
      description: Constrained upload-batch sort. The backend adds uploadId ascending as a stable secondary sort.
    LedgerUploadStatusFilter:
      name: status
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/AcademicLedgerUploadStatus'
      description: Optional upload lifecycle status filter.
    LedgerValidationStatusFilter:
      name: validationStatus
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/AcademicLedgerValidationStatus'
      description: Optional validation lifecycle status filter.
    LedgerSearch:
      name: search
      in: query
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 120
      description: Case-insensitive search over originalFilename only.
    LedgerStagedRowSort:
      name: sort
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/AcademicLedgerStagedRowSort'
      description: Constrained staged-row sort. stagingRowId ascending is applied as a stable secondary sort.
    LedgerStagedRowSearch:
      name: search
      in: query
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 120
      description: Case-insensitive search over student index number, course code, and resolved course title.
    LedgerRowValidationFilter:
      name: validationStatus
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/AcademicLedgerRowValidationStatus'
      description: Optional row validation-status filter.
    RegisteredStudentLevel:
      name: level
      in: query
      required: false
      schema:
        type: integer
        enum:
          - 3
          - 4
      description: Optional mutually exclusive Level 3 or Level 4 filter.
    RegisteredStudentSort:
      name: sort
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/RegisteredStudentSort'
      description:
        Wireframe-approved sort. Null GPA values are ordered last for both GPA directions. studentId ascending
        is applied as a stable secondary sort.
    RegisteredStudentSearch:
      name: search
      in: query
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 120
      description: Case-insensitive search over fullName, indexNumber, universityEmail, and academicBatch.
    AcademicRecordSort:
      name: sort
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/AcademicRecordSort'
      description: Constrained official academic-record sort with academicRecordId ascending as a stable secondary sort.
    AcademicRecordSearch:
      name: search
      in: query
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 120
      description: Case-insensitive search over courseCode and courseTitle.
    CourseCodeFilter:
      name: courseCode
      in: query
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 30
        pattern: ^[A-Za-z0-9._-]+$
      description: Optional exact canonical subject/course-code filter.
    StudentIdFilter:
      name: studentId
      in: query
      required: false
      schema:
        type: string
        format: uuid
      description: Optional stable Student identifier for global committed-record inspection.
    CompanySort:
      name: sort
      in: query
      schema:
        $ref: '#/components/schemas/CompanySort'
      description: Constrained company ordering with companyId ascending as a stable secondary order.
    CompanyIdFilter:
      name: companyId
      in: query
      schema:
        type:
          - string
          - 'null'
        format: uuid
      description: Restrict internship requests or shortlists to one company.
    InternshipRequestSort:
      name: sort
      in: query
      schema:
        $ref: '#/components/schemas/InternshipRequestSort'
      description: Constrained request ordering with requestId ascending as a stable secondary order.
    CandidateSort:
      name: sort
      in: query
      schema:
        $ref: '#/components/schemas/CandidateSort'
      description: Constrained deterministic candidate ordering with studentId ascending as a stable secondary order.
    ShortlistSort:
      name: sort
      in: query
      schema:
        $ref: '#/components/schemas/ShortlistSort'
      description: Constrained shortlist ordering with shortlistId ascending as a stable secondary order.
    ShortlistStatusFilter:
      name: status
      in: query
      schema:
        oneOf:
          - $ref: '#/components/schemas/ShortlistStatus'
          - type: 'null'
      description: Optional shortlist lifecycle filter.
    CandidatePage:
      name: candidatePage
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Zero-based candidate page within shortlist details.
    CandidateSize:
      name: candidateSize
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Candidate page size within shortlist details.
    CandidateSearch:
      name: candidateSearch
      in: query
      schema:
        type:
          - string
          - 'null'
        minLength: 1
        maxLength: 120
      description: Search shortlist candidates by full name or index number.
  responses:
    Error400:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error401:
      description: Authentication required or invalid token.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error403:
      description: Access denied.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error404:
      description: Resource not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error409:
      description: Conflict.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error412:
      description: Precondition failed or version conflict.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error415:
      description: Unsupported media type.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error422:
      description: Validation failed.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error429:
      description: Too many requests.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error500:
      description: Internal server error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error503:
      description: Service unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error413:
      description: Payload too large.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    Error428:
      description: Precondition required.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    DuplicateDeclaredSkill409:
      description: The Student has already declared the selected canonical taxonomy skill.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            duplicateDeclaredSkill:
              summary: Duplicate declared skill
              value:
                type: https://uor-cv-system/errors/declared-skill-duplicate
                title: Declared skill already exists
                status: 409
                code: DECLARED_SKILL_DUPLICATE
                message: React is already present in the Student declared-skill list.
                correlationId: req-20260716-0409
                details:
                  skillId: 11111111-1111-4111-8111-111111111111
    InvalidProjectDateRange422:
      description: Project validation failed because endDate is before startDate.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            invalidProjectDateRange:
              summary: Invalid project date range
              value:
                type: https://uor-cv-system/errors/project-date-range-invalid
                title: Project date range is invalid
                status: 422
                code: PROJECT_DATE_RANGE_INVALID
                message: endDate must not be before startDate.
                correlationId: req-20260716-0422
                fieldErrors:
                  - field: endDate
                    code: INVALID_DATE_RANGE
                    message: endDate must not be before startDate.
    StaleProjectVersion412:
      description: The supplied project entity version is stale.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            staleProjectVersion:
              summary: Stale project update
              value:
                type: https://uor-cv-system/errors/version-conflict
                title: Project version conflict
                status: 412
                code: VERSION_CONFLICT
                message: The project changed after it was loaded. Refresh and retry with the latest version.
                correlationId: req-20260716-0412
                details:
                  projectId: 660e8400-e29b-41d4-a716-446655440001
                  submittedVersion: 2
                  currentVersion: 3
    MissingIfMatch428:
      description: The required If-Match entity-version header is missing.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            missingIfMatch:
              summary: Missing optimistic-concurrency precondition
              value:
                type: https://uor-cv-system/errors/precondition-required
                title: Precondition required
                status: 428
                code: IF_MATCH_REQUIRED
                message: Supply the latest quoted entity version in the If-Match header.
                correlationId: req-20260716-0428
    InvalidCvConfiguration422:
      description: The CV preview configuration is structurally valid but semantically invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            invalidCvConfiguration:
              summary: Invalid CV configuration
              value:
                type: https://uor-cv-system/errors/cv-configuration-invalid
                title: CV configuration is invalid
                status: 422
                code: CV_CONFIGURATION_INVALID
                message: One or more selected records cannot be included in this CV preview.
                correlationId: req-20260721-0422
    CvPreviewExpired409:
      description: The preview exists but expired or was invalidated before it could be saved.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            cvPreviewExpired:
              summary: CV preview expired
              value:
                type: https://uor-cv-system/errors/cv-preview-expired
                title: CV preview expired
                status: 409
                code: CV_PREVIEW_EXPIRED
                message: Generate a new preview before saving the CV.
                correlationId: req-20260721-0409
                details:
                  previewId: 70000000-0000-4000-8000-000000000001
    StaleCv412:
      description: The active CV revision changed before this replacement request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://uor-cv-system/errors/stale-version
            title: Precondition failed
            status: 412
            code: STALE_VERSION
            message: The saved CV changed in another request.
            correlationId: req-20260718-0412
    CvPreconditionRequired428:
      description: The required first-create or replacement conditional header is missing.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://uor-cv-system/errors/precondition-required
            title: Precondition required
            status: 428
            code: PRECONDITION_REQUIRED
            message: A current conditional request header is required.
            correlationId: req-20260718-0428
    CvGenerationFailed503:
      description: The backend-controlled LaTeX/PDF generation service could not complete the requested operation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            cvGenerationFailed:
              summary: CV generation failed
              value:
                type: https://uor-cv-system/errors/cv-generation-failed
                title: CV generation unavailable
                status: 503
                code: CV_GENERATION_FAILED
                message: The CV could not be generated at this time.
                correlationId: req-20260721-0503
                details: {}
    NoSavedCv404:
      description: No active saved CV exists for the authenticated Student.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            noSavedCv:
              summary: No saved CV
              value:
                type: https://uor-cv-system/errors/cv-not-saved
                title: No saved CV is available
                status: 404
                code: CV_NOT_SAVED
                message: Save the CV before downloading it.
                correlationId: req-20260721-0404
                details: {}
    CvFileUnavailable503:
      description: The saved CV metadata exists but its generated PDF is temporarily unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            cvFileUnavailable:
              summary: CV PDF unavailable
              value:
                type: https://uor-cv-system/errors/cv-file-unavailable
                title: CV PDF unavailable
                status: 503
                code: CV_FILE_UNAVAILABLE
                message: The saved CV PDF cannot be downloaded at this time.
                correlationId: req-20260721-1503
                details: {}
    AcademicDataUnavailable503:
      description: The committed academic ledger service is temporarily unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            academicDataUnavailable:
              summary: Academic data unavailable
              value:
                type: https://uor-cv-system/errors/academic-data-unavailable
                title: Academic data unavailable
                status: 503
                code: ACADEMIC_DATA_UNAVAILABLE
                message: Official academic data cannot be loaded at this time.
                correlationId: req-20260721-2503
                details: {}
    AdminDashboardUnavailable503:
      description: Admin dashboard metrics are temporarily unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            dashboardUnavailable:
              summary: Dashboard metrics unavailable
              value:
                type: https://uor-cv-system/errors/admin-dashboard-unavailable
                title: Admin dashboard unavailable
                status: 503
                code: ADMIN_DASHBOARD_UNAVAILABLE
                message: Admin dashboard metrics cannot be loaded at this time.
                correlationId: req-20260719-1503
    LedgerFileTooLarge413:
      description: The ledger file exceeds the frozen 5 MiB maximum.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ledgerFileTooLarge:
              summary: Ledger file too large
              value:
                type: https://uor-cv-system/errors/ledger-file-too-large
                title: Academic ledger file is too large
                status: 413
                code: LEDGER_FILE_TOO_LARGE
                message: Upload a CSV file no larger than 5 MiB.
                correlationId: req-20260719-1413
                details:
                  maxSizeBytes: 5242880
    LedgerUnsupportedMediaType415:
      description: Only UTF-8 text/csv with a .csv filename is accepted.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            unsupportedLedgerMedia:
              summary: Unsupported ledger media type
              value:
                type: https://uor-cv-system/errors/ledger-media-type-unsupported
                title: Unsupported academic ledger format
                status: 415
                code: LEDGER_MEDIA_TYPE_UNSUPPORTED
                message: Upload a UTF-8 CSV file with media type text/csv.
                correlationId: req-20260719-1415
                details:
                  acceptedMediaType: text/csv
                  acceptedExtension: .csv
    LedgerParseFailed422:
      description: The CSV is readable as a file but cannot be parsed under the frozen ledger column contract.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ledgerParseFailed:
              summary: Ledger parse failed
              value:
                type: https://uor-cv-system/errors/ledger-parse-failed
                title: Academic ledger could not be parsed
                status: 422
                code: LEDGER_PARSE_FAILED
                message: The CSV header or one or more rows do not match the approved academic-ledger format.
                correlationId: req-20260719-1422
                details:
                  expectedHeaders:
                    - student_index_number
                    - course_code
                    - credits
                    - letter_grade
                    - semester
                    - academic_year
                    - attempt_number
                    - result_status
    LedgerDuplicateUpload409:
      description: Identical content already exists in an active or committed upload batch.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            duplicateLedgerUpload:
              summary: Duplicate ledger upload
              value:
                type: https://uor-cv-system/errors/ledger-duplicate-upload
                title: Duplicate academic ledger upload
                status: 409
                code: LEDGER_DUPLICATE_UPLOAD
                message: Identical academic ledger content already exists in an active or committed batch.
                correlationId: req-20260719-1409
                details:
                  existingUploadId: 30000000-0000-4000-8000-000000000001
    LedgerBatchNotFound404:
      description: The addressed ledger upload batch does not exist.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ledgerBatchNotFound:
              summary: Ledger batch not found
              value:
                type: https://uor-cv-system/errors/ledger-upload-not-found
                title: Academic ledger upload not found
                status: 404
                code: LEDGER_UPLOAD_NOT_FOUND
                message: No academic ledger upload exists for the supplied identifier.
                correlationId: req-20260719-1404
    LedgerNotReady409:
      description: The upload batch is not in a state that exposes the requested staged or validation data.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ledgerNotReady:
              summary: Ledger batch not ready
              value:
                type: https://uor-cv-system/errors/ledger-not-ready
                title: Academic ledger batch is not ready
                status: 409
                code: LEDGER_NOT_READY
                message: Wait for parsing and staging to complete before requesting this resource.
                correlationId: req-20260719-2409
                details:
                  currentStatus: PROCESSING
    LedgerCommitState409:
      description: The batch is not ready, is already committed, or another commit owns the state lock.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            notReadyToCommit:
              summary: Not ready to commit
              value:
                type: https://uor-cv-system/errors/ledger-not-ready-to-commit
                title: Academic ledger is not ready to commit
                status: 409
                code: LEDGER_NOT_READY_TO_COMMIT
                message: Only a READY_TO_COMMIT upload batch can be committed.
                correlationId: req-20260719-3409
                details:
                  currentStatus: STAGED
            alreadyCommitted:
              summary: Already committed
              value:
                type: https://uor-cv-system/errors/ledger-already-committed
                title: Academic ledger is already committed
                status: 409
                code: LEDGER_ALREADY_COMMITTED
                message: The upload batch has already been committed and cannot be committed again.
                correlationId: req-20260719-3410
                details:
                  currentStatus: COMMITTED
            concurrentCommit:
              summary: Concurrent commit conflict
              value:
                type: https://uor-cv-system/errors/ledger-commit-conflict
                title: Academic ledger commit conflict
                status: 409
                code: LEDGER_COMMIT_CONFLICT
                message: Another request is currently committing this upload batch.
                correlationId: req-20260719-3411
                details:
                  currentStatus: COMMITTING
    LedgerValidationFailed422:
      description: The batch failed semantic validation and cannot be committed.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ledgerValidationFailed:
              summary: Ledger validation failed
              value:
                type: https://uor-cv-system/errors/ledger-validation-failed
                title: Academic ledger validation failed
                status: 422
                code: LEDGER_VALIDATION_FAILED
                message: Resolve the invalid rows in the source file and upload a corrected batch.
                correlationId: req-20260719-3422
                details:
                  invalidRows: 2
    LedgerCommitFailed500:
      description: The atomic commit transaction failed and was fully rolled back.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ledgerCommitFailed:
              summary: Ledger commit failed
              value:
                type: https://uor-cv-system/errors/ledger-commit-failed
                title: Academic ledger commit failed
                status: 500
                code: LEDGER_COMMIT_FAILED
                message: No academic records were committed. The batch remains ready for a safe retry.
                correlationId: req-20260719-3500
                details:
                  transactionRolledBack: true
    RegisteredStudentNotFound404:
      description: The addressed registered Student does not exist or is unavailable to this Admin context.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            studentNotFound:
              summary: Registered Student not found
              value:
                type: https://uor-cv-system/errors/registered-student-not-found
                title: Registered Student not found
                status: 404
                code: REGISTERED_STUDENT_NOT_FOUND
                message: No registered Student exists for the supplied identifier.
                correlationId: req-20260719-4404
    CompanyNotFound404:
      description: Company not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            company_not_found:
              summary: Company not found
              value:
                type: https://uor-cv-system/errors/company-not-found
                title: Company not found
                status: 404
                code: COMPANY_NOT_FOUND
                message: The requested company metadata record does not exist.
                correlationId: req-20260719-0001
    DuplicateCompany409:
      description: Duplicate company name.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            duplicate_company:
              summary: Company already exists
              value:
                type: https://uor-cv-system/errors/duplicate-company
                title: Company already exists
                status: 409
                code: DUPLICATE_COMPANY
                message: A company with the same normalized name already exists.
                correlationId: req-20260719-0001
    InternshipRequestNotFound404:
      description: Internship request not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            internship_request_not_found:
              summary: Internship request not found
              value:
                type: https://uor-cv-system/errors/internship-request-not-found
                title: Internship request not found
                status: 404
                code: INTERNSHIP_REQUEST_NOT_FOUND
                message: The requested internship request does not exist.
                correlationId: req-20260719-0001
    DuplicateRequiredSkill409:
      description: Duplicate required skill.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            duplicate_required_skill:
              summary: Required skill already exists
              value:
                type: https://uor-cv-system/errors/duplicate-required-skill
                title: Required skill already exists
                status: 409
                code: DUPLICATE_REQUIRED_SKILL
                message: The skill is already required by this internship request.
                correlationId: req-20260719-0001
    InvalidTaxonomySkill422:
      description: Invalid taxonomy skill.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            invalid_taxonomy_skill:
              summary: Invalid skill
              value:
                type: https://uor-cv-system/errors/invalid-taxonomy-skill
                title: Invalid skill
                status: 422
                code: INVALID_TAXONOMY_SKILL
                message: One or more skills are missing, inactive, or not part of the developer-managed taxonomy.
                correlationId: req-20260719-0001
    FilterRunNotFound404:
      description: Filter run not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            filter_run_not_found:
              summary: Filter run not found
              value:
                type: https://uor-cv-system/errors/filter-run-not-found
                title: Filter run not found
                status: 404
                code: FILTER_RUN_NOT_FOUND
                message: The filtering run does not exist.
                correlationId: req-20260719-0001
    FilterCriteria422:
      description: Invalid filtering criteria.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            invalid_filter_criteria:
              summary: Invalid filtering criteria
              value:
                type: https://uor-cv-system/errors/invalid-filter-criteria
                title: Invalid filtering criteria
                status: 422
                code: INVALID_FILTER_CRITERIA
                message: The GPA range or selected runtime skills are invalid.
                correlationId: req-20260719-0001
    FilterDependencyUnavailable503:
      description: Filtering dependency unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            filter_dependency_unavailable:
              summary: Filtering data unavailable
              value:
                type: https://uor-cv-system/errors/filter-dependency-unavailable
                title: Filtering data unavailable
                status: 503
                code: FILTER_DEPENDENCY_UNAVAILABLE
                message: Committed academic or declared-skill data is temporarily unavailable.
                correlationId: req-20260719-0001
    ShortlistNotFound404:
      description: Shortlist not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            shortlist_not_found:
              summary: Shortlist not found
              value:
                type: https://uor-cv-system/errors/shortlist-not-found
                title: Shortlist not found
                status: 404
                code: SHORTLIST_NOT_FOUND
                message: The requested shortlist does not exist.
                correlationId: req-20260719-0001
    ShortlistState409:
      description: Shortlist state conflict.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            shortlist_state_conflict:
              summary: Shortlist state conflict
              value:
                type: https://uor-cv-system/errors/shortlist-state-conflict
                title: Shortlist state conflict
                status: 409
                code: SHORTLIST_STATE_CONFLICT
                message: The operation is not allowed after finalization or a shortlist already exists for the request.
                correlationId: req-20260719-0001
    ShortlistGuidanceAcknowledgement409:
      description: Guidance acknowledgement required.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            shortlist_guidance_acknowledgement_required:
              summary: Guidance acknowledgement required
              value:
                type: https://uor-cv-system/errors/shortlist-guidance-acknowledgement-required
                title: Guidance acknowledgement required
                status: 409
                code: SHORTLIST_GUIDANCE_ACKNOWLEDGEMENT_REQUIRED
                message: The selected count exceeds guidance. Acknowledge the non-blocking warning and retry.
                correlationId: req-20260719-0001
    ExportJobNotFound404:
      description: Export job not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            export_job_not_found:
              summary: Export job not found
              value:
                type: https://uor-cv-system/errors/export-job-not-found
                title: Export job not found
                status: 404
                code: EXPORT_JOB_NOT_FOUND
                message: The requested export job does not exist.
                correlationId: req-20260719-0001
    ExportNotReady409:
      description: Export is not ready.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            export_not_ready:
              summary: Export not ready
              value:
                type: https://uor-cv-system/errors/export-not-ready
                title: Export not ready
                status: 409
                code: EXPORT_NOT_READY
                message: The export job has not completed successfully.
                correlationId: req-20260719-0001
    ExportFileUnavailable503:
      description: Export file unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            export_file_unavailable:
              summary: Export file unavailable
              value:
                type: https://uor-cv-system/errors/export-file-unavailable
                title: Export file unavailable
                status: 503
                code: EXPORT_FILE_UNAVAILABLE
                message: The generated export file is temporarily unavailable.
                correlationId: req-20260719-0001
  schemas:
    AcademicLedgerCommitRequest:
      type: object
      additionalProperties: false
      required:
        - confirm
      properties:
        confirm:
          type: boolean
          const: true
          description: Explicit acknowledgement of the atomic official-data commit.
    AcademicLedgerCommitResponse:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - status
        - committedRecords
        - affectedStudents
        - recalculatedGpaCount
        - committedAt
      properties:
        uploadId:
          type: string
          format: uuid
          readOnly: true
        status:
          type: string
          const: COMMITTED
          readOnly: true
        committedRecords:
          type: integer
          minimum: 0
          readOnly: true
        affectedStudents:
          type: integer
          minimum: 0
          readOnly: true
        recalculatedGpaCount:
          type: integer
          minimum: 0
          readOnly: true
        committedAt:
          type: string
          format: date-time
          readOnly: true
      examples:
        - uploadId: 30000000-0000-4000-8000-000000000001
          status: COMMITTED
          committedRecords: 240
          affectedStudents: 60
          recalculatedGpaCount: 60
          committedAt: '2026-07-19T08:20:00Z'
    AcademicLedgerUploadRequest:
      type: object
      additionalProperties: false
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          contentMediaType: text/csv
          description: UTF-8 CSV using the exact canonical headers defined by info.x-academic-ledger-file-contract.
          x-max-size-bytes: 5242880
          x-allowed-file-extensions:
            - .csv
      description: Multipart upload containing exactly one approved official academic-ledger CSV file.
    AcademicLedgerUploadResponse:
      $ref: '#/components/schemas/AcademicLedgerUploadDetailResponse'
    AcademicLedgerValidationResultResponse:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - validationStatus
        - valid
        - totalRows
        - validRows
        - invalidRows
        - errors
      properties:
        uploadId:
          type: string
          format: uuid
          readOnly: true
        validationStatus:
          $ref: '#/components/schemas/AcademicLedgerValidationStatus'
        valid:
          type: boolean
          readOnly: true
        totalRows:
          type: integer
          minimum: 0
          readOnly: true
        validRows:
          type: integer
          minimum: 0
          readOnly: true
        invalidRows:
          type: integer
          minimum: 0
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/AcademicLedgerValidationErrorResponse'
          readOnly: true
      description:
        Validation summary. totalRows must equal validRows plus invalidRows. valid is true only when validationStatus
        is PASSED and invalidRows is zero.
      examples:
        - uploadId: 30000000-0000-4000-8000-000000000001
          validationStatus: PASSED
          valid: true
          totalRows: 240
          validRows: 240
          invalidRows: 0
          errors: []
        - uploadId: 30000000-0000-4000-8000-000000000002
          validationStatus: FAILED
          valid: false
          totalRows: 240
          validRows: 238
          invalidRows: 2
          errors:
            - rowNumber: 17
              field: student_index_number
              code: STUDENT_NOT_FOUND
              message: No eligible Student matches the supplied index number.
              severity: ERROR
              rejectedValue: SC/2099/99999
              relatedRowNumber: null
            - rowNumber: 29
              field: course_code
              code: COURSE_NOT_FOUND
              message: The supplied course code is not present in the canonical subject catalogue.
              severity: ERROR
              rejectedValue: CSC9999
              relatedRowNumber: null
    ActivityResponse:
      type: object
      additionalProperties: false
      required:
        - id
        - activityName
        - roleTitle
        - startDate
        - endDate
        - description
        - cvInclude
        - version
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        activityName:
          type: string
          minLength: 1
          maxLength: 200
        roleTitle:
          type: string
          minLength: 1
          maxLength: 150
        startDate:
          type:
            - string
            - 'null'
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: Optional end date; when both dates are present, it must not precede startDate.
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
        version:
          type: integer
          minimum: 0
          readOnly: true
          description: Optimistic-lock entity version used in If-Match.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    AdminDashboardMetricsResponse:
      type: object
      additionalProperties: false
      required:
        - totalStudents
        - registeredStudents
        - internshipRequestsCreated
        - lastUpdatedAt
      properties:
        totalStudents:
          type: integer
          minimum: 0
          readOnly: true
          description: Total initialized eligible Student records.
        registeredStudents:
          type: integer
          minimum: 0
          readOnly: true
          description: Students with activated registered accounts.
        internshipRequestsCreated:
          type: integer
          minimum: 0
          readOnly: true
          description: Persisted internship request count.
        lastUpdatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Time at which the metrics snapshot was produced.
      examples:
        - totalStudents: 142
          registeredStudents: 134
          internshipRequestsCreated: 12
          lastUpdatedAt: '2026-07-19T08:30:00Z'
      description:
        Live persisted or computed Admin dashboard metrics. Example counts are illustrative, never authoritative
        constants.
    AdminLoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
          writeOnly: true
    AdminStudentDetailResponse:
      type: object
      additionalProperties: false
      required:
        - student
        - profile
        - cvSupportingData
        - latestCv
      properties:
        student:
          $ref: '#/components/schemas/StudentSummaryResponse'
        profile:
          $ref: '#/components/schemas/StudentProfileResponse'
        cvSupportingData:
          $ref: '#/components/schemas/AdminStudentCvSupportingDataResponse'
        latestCv:
          $ref: '#/components/schemas/AdminLatestCvResponse'
      description:
        Read-only deep-dive summary. Declared skills, projects, and committed academic records remain separate
        paged resources.
    AuthTokenResponse:
      type: object
      additionalProperties: false
      required:
        - accessToken
        - tokenType
        - expiresInSeconds
        - user
      properties:
        accessToken:
          type: string
          minLength: 1
        tokenType:
          type: string
          const: Bearer
        expiresInSeconds:
          type: integer
          minimum: 1
        user:
          $ref: '#/components/schemas/CurrentUserResponse'
    AwardResponse:
      type: object
      additionalProperties: false
      required:
        - id
        - title
        - issuer
        - awardDate
        - description
        - cvInclude
        - version
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        title:
          type: string
          minLength: 1
          maxLength: 200
        issuer:
          type: string
          minLength: 1
          maxLength: 200
        awardDate:
          type: string
          format: date
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
        version:
          type: integer
          minimum: 0
          readOnly: true
          description: Optimistic-lock entity version used in If-Match.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    CandidateFilteringRunRequest:
      $ref: '#/components/schemas/CandidateFilteringCriteriaRequest'
    CandidateFilteringRunResponse:
      type: object
      additionalProperties: false
      required:
        - filterRunId
        - request
        - criteria
        - candidateCount
        - createdAt
      properties:
        filterRunId:
          type: string
          format: uuid
        request:
          $ref: '#/components/schemas/InternshipRequestSummaryResponse'
        criteria:
          $ref: '#/components/schemas/CandidateFilteringCriteriaResponse'
        candidateCount:
          type: integer
          minimum: 0
        createdAt:
          type: string
          format: date-time
      description:
        Persisted sanitized filtering-run metadata. Candidate rows are recomputed from current committed data when
        retrieved.
    CertificateResponse:
      type: object
      additionalProperties: false
      required:
        - id
        - title
        - issuer
        - issueDate
        - credentialUrl
        - cvInclude
        - evidence
        - version
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        title:
          type: string
          minLength: 1
          maxLength: 200
        issuer:
          type: string
          minLength: 1
          maxLength: 200
        issueDate:
          type: string
          format: date
        credentialUrl:
          type:
            - string
            - 'null'
          format: uri
        cvInclude:
          type: boolean
          default: true
        evidence:
          anyOf:
            - $ref: '#/components/schemas/FileAssetResponse'
            - type: 'null'
          readOnly: true
        version:
          type: integer
          minimum: 0
          readOnly: true
          description: Optimistic-lock entity version used in If-Match.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    CompanyRequest:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        websiteUrl:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 500
        contactPerson:
          type:
            - string
            - 'null'
          maxLength: 150
        contactEmail:
          type:
            - string
            - 'null'
          format: email
          maxLength: 254
        contactPhone:
          type:
            - string
            - 'null'
          maxLength: 30
        notes:
          type:
            - string
            - 'null'
          maxLength: 4000
      examples:
        - name: Example Technologies
          websiteUrl: https://example.com
          contactPerson: HR Coordinator
          contactEmail: hr@example.com
          contactPhone: +94 11 234 5678
          notes: null
    CompanyResponse:
      type: object
      additionalProperties: false
      required:
        - companyId
        - name
        - websiteUrl
        - contactPerson
        - contactEmail
        - contactPhone
        - notes
        - version
        - createdAt
        - updatedAt
      properties:
        companyId:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 200
        websiteUrl:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 500
        contactPerson:
          type:
            - string
            - 'null'
          maxLength: 150
        contactEmail:
          type:
            - string
            - 'null'
          format: email
          maxLength: 254
        contactPhone:
          type:
            - string
            - 'null'
          maxLength: 30
        notes:
          type:
            - string
            - 'null'
          maxLength: 4000
        version:
          type: integer
          minimum: 0
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
      description: Admin-managed external-company metadata only. No company account or authentication fields exist.
    ContactLinkResponse:
      type: object
      additionalProperties: false
      required:
        - id
        - label
        - url
        - displayOrder
        - cvInclude
        - version
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        label:
          type: string
          minLength: 1
          maxLength: 60
          description: Display label such as LinkedIn, GitHub, Portfolio, or Personal Website.
        url:
          type: string
          format: uri
        displayOrder:
          type: integer
          minimum: 0
          default: 0
        cvInclude:
          type: boolean
          default: true
        version:
          type: integer
          minimum: 0
          readOnly: true
          description: Optimistic-lock entity version used in If-Match.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    CurrentUserResponse:
      type: object
      additionalProperties: false
      required:
        - userId
        - email
        - primaryRole
        - roles
      properties:
        userId:
          type: string
          format: uuid
        email:
          type: string
          format: email
          maxLength: 254
        displayName:
          type:
            - string
            - 'null'
        primaryRole:
          $ref: '#/components/schemas/AccountType'
        roles:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AccountType'
    CvFreshnessResponse:
      type: object
      additionalProperties: false
      required:
        - status
        - changedAreas
        - cvId
        - savedAt
        - evaluatedAt
        - message
      properties:
        status:
          $ref: '#/components/schemas/CvFreshnessStatus'
        changedAreas:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/CvSourceArea'
          description: Changed source areas. Empty for NOT_SAVED and CURRENT; non-empty for OUTDATED.
        cvId:
          type:
            - string
            - 'null'
          format: uuid
          readOnly: true
          description: Active saved CV identifier, or null when status is NOT_SAVED.
        savedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Latest save timestamp, or null when status is NOT_SAVED.
        evaluatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp at which freshness was evaluated.
        message:
          type: string
          minLength: 1
          description: Informational display message; clients must use status and changedAreas for logic.
      description: Typed CV source-freshness result; it never represents an Admin review state.
      examples:
        - status: NOT_SAVED
          changedAreas: []
          cvId: null
          savedAt: null
          evaluatedAt: '2026-07-21T08:00:00Z'
          message: No saved CV exists yet.
        - status: CURRENT
          changedAreas: []
          cvId: 50000000-0000-4000-8000-000000000001
          savedAt: '2026-07-21T07:30:00Z'
          evaluatedAt: '2026-07-21T08:00:00Z'
          message: The latest saved CV matches current source data.
        - status: OUTDATED
          changedAreas:
            - PROFILE
          cvId: 50000000-0000-4000-8000-000000000001
          savedAt: '2026-07-21T07:30:00Z'
          evaluatedAt: '2026-07-21T08:00:00Z'
          message: Profile data changed after the latest CV was saved.
        - status: OUTDATED
          changedAreas:
            - DECLARED_SKILLS
            - PROJECTS
          cvId: 50000000-0000-4000-8000-000000000001
          savedAt: '2026-07-21T07:30:00Z'
          evaluatedAt: '2026-07-21T08:00:00Z'
          message: Declared skills or projects changed after the latest CV was saved.
    CvPreviewRequest:
      type: object
      additionalProperties: false
      required:
        - includedExperienceIds
        - includedProjectIds
        - includedCertificateIds
        - includedAwardIds
        - includedActivityIds
      properties:
        includedExperienceIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
        includedProjectIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
        includedCertificateIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
        includedAwardIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
        includedActivityIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
      description:
        Student-controlled record selections. Empty lists omit their section. The backend validates ownership and
        applies the fixed default structural order.
    CvPreviewResponse:
      type: object
      additionalProperties: false
      required:
        - previewId
        - htmlPreview
        - freshness
        - configuration
        - generatedAt
        - expiresAt
      properties:
        previewId:
          type: string
          format: uuid
          readOnly: true
        htmlPreview:
          type: string
          minLength: 1
          readOnly: true
          description: Backend-generated sanitized HTML fragment rendered only through the approved frontend sanitizing boundary.
        freshness:
          $ref: '#/components/schemas/CvFreshnessResponse'
        configuration:
          $ref: '#/components/schemas/CvPreviewConfigurationResponse'
        generatedAt:
          type: string
          format: date-time
          readOnly: true
        expiresAt:
          type: string
          format: date-time
          readOnly: true
      description: Expiring preview snapshot. Generated LaTeX remains internal and is never exposed by this API.
    CvSaveRequest:
      type: object
      additionalProperties: false
      required:
        - previewId
      properties:
        previewId:
          type: string
          format: uuid
      description: Saves the exact unexpired owner-scoped preview as the Student's single active CV.
    CvResponse:
      type: object
      additionalProperties: false
      required:
        - cvId
        - revision
        - createdAt
        - generatedAt
        - savedAt
        - downloadUrl
        - freshnessStatus
        - configuration
        - pdfFile
      properties:
        cvId:
          type: string
          format: uuid
          readOnly: true
        revision:
          type: integer
          minimum: 1
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        generatedAt:
          type: string
          format: date-time
          readOnly: true
        savedAt:
          type: string
          format: date-time
          readOnly: true
        downloadUrl:
          type: string
          pattern: ^/me/cv/download$
          readOnly: true
        freshnessStatus:
          type: string
          enum:
            - CURRENT
            - OUTDATED
          readOnly: true
        configuration:
          $ref: '#/components/schemas/CvPreviewConfigurationResponse'
        pdfFile:
          $ref: '#/components/schemas/GeneratedFileMetadataResponse'
      description: The Student's single active saved CV. Revision is an optimistic-concurrency token, not a history number.
    DeclaredSkillCreateRequest:
      type: object
      additionalProperties: false
      required:
        - skillId
        - competencyLevel
      properties:
        skillId:
          type: string
          format: uuid
          description:
            Stable identifier of an existing active/selectable Individual Skill from the developer-managed taxonomy.
            Free-form skill creation is not permitted.
        competencyLevel:
          type: string
          enum:
            - BEGINNER
            - INTERMEDIATE
            - ADVANCED
      examples:
        - skillId: 11111111-1111-4111-8111-111111111111
          competencyLevel: INTERMEDIATE
    DeclaredSkillUpdateRequest:
      type: object
      additionalProperties: false
      required:
        - competencyLevel
      properties:
        competencyLevel:
          type: string
          enum:
            - BEGINNER
            - INTERMEDIATE
            - ADVANCED
      description:
        Competency-only partial update. The declared skill taxonomy reference cannot be changed through this PATCH;
        remove the declaration and create a new one instead.
      examples:
        - competencyLevel: ADVANCED
    DeclaredSkillResponse:
      type: object
      additionalProperties: false
      required:
        - declaredSkillId
        - skillId
        - skillName
        - competencyLevel
        - version
        - createdAt
        - updatedAt
      properties:
        declaredSkillId:
          type: string
          format: uuid
          readOnly: true
        skillId:
          type: string
          format: uuid
          readOnly: true
        skillName:
          type: string
          minLength: 1
          readOnly: true
        competencyLevel:
          type: string
          enum:
            - BEGINNER
            - INTERMEDIATE
            - ADVANCED
        version:
          type: integer
          minimum: 0
          readOnly: true
          description: Optimistic-lock entity version used in If-Match.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
      description:
        Student-owned declared skill selected from the developer-managed taxonomy. It has no verification, endorsement,
        scoring, or Admin-approval state.
      examples:
        - declaredSkillId: 550e8400-e29b-41d4-a716-446655440001
          skillId: 11111111-1111-4111-8111-111111111111
          skillName: React
          competencyLevel: INTERMEDIATE
          version: 3
          createdAt: '2026-07-16T08:30:00Z'
          updatedAt: '2026-07-16T09:15:00Z'
    ExperienceResponse:
      type: object
      additionalProperties: false
      required:
        - id
        - organization
        - positionTitle
        - location
        - startDate
        - endDate
        - currentRole
        - description
        - cvInclude
        - version
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        organization:
          type: string
          minLength: 1
          maxLength: 200
        positionTitle:
          type: string
          minLength: 1
          maxLength: 150
        location:
          type:
            - string
            - 'null'
        startDate:
          type: string
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: Null for a current role; otherwise it must not precede startDate.
        currentRole:
          type: boolean
          default: false
          description: True when the position is ongoing; endDate must then be null.
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
        version:
          type: integer
          minimum: 0
          readOnly: true
          description: Optimistic-lock entity version used in If-Match.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    ExportCreateRequest:
      oneOf:
        - $ref: '#/components/schemas/ShortlistSummaryExportCreateRequest'
        - $ref: '#/components/schemas/BulkCvExportCreateRequest'
    ExportJobResponse:
      type: object
      additionalProperties: false
      required:
        - exportJobId
        - shortlistId
        - exportType
        - format
        - status
        - totalCandidateCount
        - includedFileCount
        - missingCvCount
        - missingCvStudents
        - warnings
        - downloadReady
        - downloadUrl
        - createdAt
        - startedAt
        - completedAt
        - expiresAt
        - failureCode
        - failureMessage
      properties:
        exportJobId:
          type: string
          format: uuid
        shortlistId:
          type: string
          format: uuid
        exportType:
          $ref: '#/components/schemas/ExportType'
        format:
          $ref: '#/components/schemas/ExportFormat'
        status:
          $ref: '#/components/schemas/ExportJobStatus'
        totalCandidateCount:
          type: integer
          minimum: 0
        includedFileCount:
          type: integer
          minimum: 0
        missingCvCount:
          type: integer
          minimum: 0
        missingCvStudents:
          type: array
          items:
            $ref: '#/components/schemas/MissingCvStudentResponse'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ExportWarningResponse'
        downloadReady:
          type: boolean
        downloadUrl:
          type:
            - string
            - 'null'
          pattern: ^/admin/exports/[0-9a-fA-F-]{36}/(?:bulk-cvs/)?download$
        createdAt:
          type: string
          format: date-time
        startedAt:
          type:
            - string
            - 'null'
          format: date-time
        completedAt:
          type:
            - string
            - 'null'
          format: date-time
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        failureCode:
          type:
            - string
            - 'null'
          maxLength: 100
        failureMessage:
          type:
            - string
            - 'null'
          maxLength: 500
      description: Partial bulk-CV export may complete with warnings. If zero CV files are available, the job fails with NO_CV_FILES_AVAILABLE.
    FieldError:
      type: object
      additionalProperties: false
      required:
        - field
        - code
        - message
      properties:
        field:
          type: string
          minLength: 1
        code:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
    GpaSummaryResponse:
      type: object
      additionalProperties: false
      required:
        - studentId
        - status
        - computerScienceGpa
        - totalCredits
        - calculatedAt
        - source
      properties:
        studentId:
          type: string
          format: uuid
          readOnly: true
          description: Authenticated Student whose official GPA is represented.
        status:
          $ref: '#/components/schemas/GpaAvailabilityStatus'
        computerScienceGpa:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 4
          multipleOf: 0.01
          description: Official Computer Science GPA, or null when no committed academic records are available.
        totalCredits:
          type:
            - number
            - 'null'
          minimum: 0
          multipleOf: 0.1
          description: Total committed credits included in the GPA calculation, or null when unavailable.
        calculatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: GPA calculation timestamp, or null when status is NOT_AVAILABLE.
        source:
          oneOf:
            - $ref: '#/components/schemas/AcademicRecordSourceResponse'
            - type: 'null'
          description: Typed committed-ledger source metadata, or null when status is NOT_AVAILABLE.
      description:
        Official Computer Science GPA derived only from committed academic records. NOT_AVAILABLE is an ordinary
        successful empty state and is not returned as 404.
      examples:
        - studentId: 30000000-0000-4000-8000-000000000001
          status: AVAILABLE
          computerScienceGpa: 3.75
          totalCredits: 42.0
          calculatedAt: '2026-07-20T09:35:00Z'
          source:
            sourceUploadId: 40000000-0000-4000-8000-000000000001
            committedAt: '2026-07-20T09:30:00Z'
        - studentId: 30000000-0000-4000-8000-000000000002
          status: NOT_AVAILABLE
          computerScienceGpa: null
          totalCredits: null
          calculatedAt: null
          source: null
    InternshipRequestCreateRequest:
      type: object
      additionalProperties: false
      required:
        - companyId
        - title
        - requiredSkills
      properties:
        companyId:
          type: string
          format: uuid
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type:
            - string
            - 'null'
          maxLength: 10000
        shortlistGuidanceValue:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 10000
          description: Advisory value only; never a hard finalization limit.
        requiredSkills:
          type: array
          items:
            $ref: '#/components/schemas/InternshipRequiredSkillRequest'
          uniqueItems: true
          maxItems: 100
      description: Creates request metadata and the complete required-skill set atomically. No GPA criteria are permitted.
    InternshipRequestResponse:
      type: object
      additionalProperties: false
      required:
        - requestId
        - company
        - title
        - description
        - shortlistGuidanceValue
        - requiredSkills
        - version
        - createdAt
        - updatedAt
      properties:
        requestId:
          type: string
          format: uuid
          readOnly: true
        company:
          $ref: '#/components/schemas/CompanyResponse'
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type:
            - string
            - 'null'
          maxLength: 10000
        shortlistGuidanceValue:
          type:
            - integer
            - 'null'
          minimum: 0
        requiredSkills:
          type: array
          items:
            $ref: '#/components/schemas/InternshipRequiredSkillResponse'
        version:
          type: integer
          minimum: 0
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
      description: Admin-managed request. GPA is never stored in this resource; the request remains editable until deleted.
    InternshipRequestUpdateRequest:
      type: object
      additionalProperties: false
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type:
            - string
            - 'null'
          maxLength: 10000
        shortlistGuidanceValue:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 10000
          description: Advisory value only; never a hard finalization limit.
        requiredSkills:
          type: array
          items:
            $ref: '#/components/schemas/InternshipRequiredSkillRequest'
          uniqueItems: true
          maxItems: 100
          description: When present, atomically replaces the full required-skill set.
      minProperties: 1
      description: Partial request update. Required skills are unchanged when omitted and fully replaced when present.
    InternshipRequiredSkillRequest:
      type: object
      additionalProperties: false
      required:
        - skillId
      properties:
        skillId:
          type: string
          format: uuid
    InternshipRequiredSkillResponse:
      type: object
      additionalProperties: false
      required:
        - requiredSkillId
        - skillId
        - skillName
      properties:
        requiredSkillId:
          type: string
          format: uuid
          readOnly: true
        skillId:
          type: string
          format: uuid
          readOnly: true
        skillName:
          type: string
          minLength: 1
          readOnly: true
    OperationResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        correlationId:
          type: string
    OtpResendResponse:
      type: object
      additionalProperties: false
      required:
        - message
        - expiresInSeconds
      properties:
        message:
          type: string
        expiresInSeconds:
          type: integer
          minimum: 1
    OtpVerifyRequest:
      type: object
      required:
        - otpCode
      properties:
        otpCode:
          type: string
          minLength: 6
          maxLength: 6
          writeOnly: true
    OtpVerifyResponse:
      type: object
      additionalProperties: false
      required:
        - verified
      properties:
        verified:
          type: boolean
          const: true
    PageMetadata:
      type: object
      required:
        - page
        - size
        - totalElements
        - totalPages
        - sort
      properties:
        page:
          type: integer
          minimum: 0
        size:
          type: integer
          minimum: 1
          maximum: 100
        totalElements:
          type: integer
          minimum: 0
        totalPages:
          type: integer
          minimum: 0
        sort:
          type: string
          minLength: 1
          maxLength: 120
      additionalProperties: false
    PagedAcademicLedgerUploadResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AcademicLedgerUploadSummaryResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
      examples:
        - items:
            - uploadId: 30000000-0000-4000-8000-000000000001
              originalFilename: computer-science-results-2025-2026.csv
              contentType: text/csv
              fileSizeBytes: 84216
              uploadStatus: READY_TO_COMMIT
              validationStatus: PASSED
              totalRows: 240
              validRows: 240
              invalidRows: 0
              uploadedAt: '2026-07-19T08:00:00Z'
              committedAt: null
              failureSummary: null
          page:
            page: 0
            size: 20
            totalElements: 1
            totalPages: 1
            sort: uploadedAt,desc
        - items: []
          page:
            page: 0
            size: 20
            totalElements: 0
            totalPages: 0
            sort: uploadedAt,desc
    PagedAcademicRecordResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AcademicRecordResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
      description: Typed page of official committed academic results.
      examples:
        - items:
            - academicRecordId: 10000000-0000-4000-8000-000000000001
              subjectId: 20000000-0000-4000-8000-000000000001
              courseCode: CSC3112
              courseTitle: Web Technologies
              credits: 4.0
              letterGrade: A-
              gradePoint: 3.7
              semester: Semester 1
              academicYear: 2025/2026
              attemptNumber: 1
              resultStatus: PASSED
              committedAt: '2026-07-20T09:30:00Z'
            - academicRecordId: 10000000-0000-4000-8000-000000000002
              subjectId: 20000000-0000-4000-8000-000000000002
              courseCode: CSC3122
              courseTitle: Software Engineering
              credits: 3.0
              letterGrade: A
              gradePoint: 4.0
              semester: Semester 1
              academicYear: 2025/2026
              attemptNumber: 1
              resultStatus: PASSED
              committedAt: '2026-07-20T09:30:00Z'
          page:
            page: 0
            size: 20
            totalElements: 2
            totalPages: 1
            sort: academicYear,desc
        - items: []
          page:
            page: 0
            size: 20
            totalElements: 0
            totalPages: 0
            sort: academicYear,desc
    PagedActivityResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ActivityResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedAuditEventResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedAwardResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AwardResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedCandidateFilteringCandidateResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CandidateFilteringCandidateResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedCertificateResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CertificateResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedCompanyResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CompanyResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedContactLinkResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ContactLinkResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedDeclaredSkillResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DeclaredSkillResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
      examples:
        - items:
            - declaredSkillId: 550e8400-e29b-41d4-a716-446655440001
              skillId: 11111111-1111-4111-8111-111111111111
              skillName: React
              competencyLevel: INTERMEDIATE
              version: 3
              createdAt: '2026-07-16T08:30:00Z'
              updatedAt: '2026-07-16T09:15:00Z'
          page:
            page: 0
            size: 20
            totalElements: 1
            totalPages: 1
            sort: skillName,asc
    PagedExperienceResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExperienceResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedIndividualSkillResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/IndividualSkillResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedInternshipRequestResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/InternshipRequestResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedInternshipRequiredSkillResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/InternshipRequiredSkillResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedProjectResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProjectResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
      examples:
        - items:
            - projectId: 660e8400-e29b-41d4-a716-446655440001
              title: Accessible Internship Portal
              description: A responsive portfolio project for managing structured internship application data.
              repositoryUrl: https://github.com/example/accessible-internship-portal
              demoUrl: null
              startDate: '2026-01-10'
              endDate: '2026-05-15'
              skills:
                - skillId: 11111111-1111-4111-8111-111111111111
                  name: React
                  description: Component-based frontend library.
                - skillId: 22222222-2222-4222-8222-222222222222
                  name: TypeScript
                  description: null
              includeInCv: true
              version: 2
              createdAt: '2026-07-16T08:00:00Z'
              updatedAt: '2026-07-16T09:45:00Z'
          page:
            page: 0
            size: 20
            totalElements: 1
            totalPages: 1
            sort: updatedAt,desc
    PagedShortlistResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ShortlistResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedSkillCategoryResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SkillCategoryResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedSkillClusterResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SkillClusterResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PagedStudentSummaryResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StudentSummaryResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
      examples:
        - items:
            - studentId: 40000000-0000-4000-8000-000000000001
              indexNumber: SC/2022/12865
              fullName: K. Kavindu Lakshan
              universityEmail: sc202212865@dcs.ruh.ac.lk
              degreeProgram: B.Sc. in Computer Science
              academicBatch: '2022'
              currentLevel: 3
              officialGpa: 3.7
            - studentId: 40000000-0000-4000-8000-000000000002
              indexNumber: SC/2021/11834
              fullName: Y. D. Lahiru Gunasekara
              universityEmail: sc202111834@dcs.ruh.ac.lk
              degreeProgram: B.Sc. in Computer Science
              academicBatch: '2021'
              currentLevel: 4
              officialGpa: null
          page:
            page: 0
            size: 20
            totalElements: 2
            totalPages: 1
            sort: fullName,asc
        - items: []
          page:
            page: 0
            size: 20
            totalElements: 0
            totalPages: 0
            sort: fullName,asc
    PasswordCreateRequest:
      type: object
      required:
        - newPassword
        - confirmPassword
      properties:
        newPassword:
          type: string
          format: password
          writeOnly: true
        confirmPassword:
          type: string
          format: password
          writeOnly: true
    PasswordResetResponse:
      type: object
      additionalProperties: false
      required:
        - resetId
        - message
        - expiresInSeconds
      properties:
        resetId:
          type: string
          format: uuid
          description:
            Opaque reset-flow identifier returned for every syntactically valid request. Its presence does not
            confirm that an eligible account exists.
        message:
          type: string
          example: If the account is eligible, a One-Time Password has been sent.
        expiresInSeconds:
          type: integer
          minimum: 1
          example: 300
    PasswordResetStartRequest:
      type: object
      additionalProperties: false
      required:
        - accountType
        - email
      properties:
        accountType:
          $ref: '#/components/schemas/AccountType'
        email:
          type: string
          format: email
          maxLength: 254
          description: University email for Student or provisioned email for Department Admin.
    ProblemDetails:
      type: object
      required:
        - type
        - title
        - status
        - code
        - message
        - correlationId
      properties:
        type:
          type: string
          format: uri
          examples:
            - https://uor-cv-system/errors/validation-failed
        title:
          type: string
          examples:
            - Validation failed
        status:
          type: integer
          examples:
            - 422
        code:
          type: string
          examples:
            - VALIDATION_FAILED
        message:
          type: string
          examples:
            - One or more fields are invalid.
        correlationId:
          type: string
          examples:
            - req-20260630-0001
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
        details:
          type: object
          additionalProperties: true
      additionalProperties: false
    ProjectCreateRequest:
      type: object
      additionalProperties: false
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type:
            - string
            - 'null'
        repositoryUrl:
          type:
            - string
            - 'null'
          format: uri
        demoUrl:
          type:
            - string
            - 'null'
          format: uri
        startDate:
          type:
            - string
            - 'null'
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: When both dates are supplied, endDate must not be before startDate.
        skillIds:
          type: array
          uniqueItems: true
          items:
            type: string
            format: uuid
          description:
            Canonical Individual Skill identifiers from the developer-managed taxonomy. Technologies are not accepted
            as free-text values.
          default: []
        includeInCv:
          type: boolean
          default: true
      description:
        Create a Student-owned portfolio project. The project and all project-skill mappings are committed as one
        transaction. If both dates are present, endDate must not precede startDate.
      examples:
        - title: Accessible Internship Portal
          description: A responsive portfolio project for managing structured internship application data.
          repositoryUrl: https://github.com/example/accessible-internship-portal
          demoUrl: null
          startDate: '2026-01-10'
          endDate: '2026-05-15'
          skillIds:
            - 11111111-1111-4111-8111-111111111111
            - 22222222-2222-4222-8222-222222222222
          includeInCv: true
    ProjectUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type:
            - string
            - 'null'
        repositoryUrl:
          type:
            - string
            - 'null'
          format: uri
        demoUrl:
          type:
            - string
            - 'null'
          format: uri
        startDate:
          type:
            - string
            - 'null'
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: When both dates are supplied, endDate must not be before startDate.
        skillIds:
          type: array
          uniqueItems: true
          items:
            type: string
            format: uuid
          description:
            Canonical Individual Skill identifiers from the developer-managed taxonomy. Technologies are not accepted
            as free-text values.
        includeInCv:
          type: boolean
      description:
        True partial PATCH. Omitted properties remain unchanged. Null clears only nullable properties. An empty
        skillIds array removes all project-skill mappings. The project and mappings update atomically.
      examples:
        - description: Updated project summary with improved accessibility and validation coverage.
          demoUrl: https://example.test/accessible-internship-portal
          includeInCv: true
    ProjectSkillResponse:
      type: object
      additionalProperties: false
      required:
        - skillId
        - name
      properties:
        skillId:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          minLength: 1
        description:
          type:
            - string
            - 'null'
      description: Project-owned view of one normalized taxonomy skill; wire fields remain unchanged.
    ProjectResponse:
      type: object
      additionalProperties: false
      required:
        - projectId
        - title
        - description
        - repositoryUrl
        - demoUrl
        - startDate
        - endDate
        - skills
        - includeInCv
        - version
        - createdAt
        - updatedAt
      properties:
        projectId:
          type: string
          format: uuid
          readOnly: true
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type:
            - string
            - 'null'
        repositoryUrl:
          type:
            - string
            - 'null'
          format: uri
        demoUrl:
          type:
            - string
            - 'null'
          format: uri
        startDate:
          type:
            - string
            - 'null'
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: When both dates are present, endDate is not before startDate.
        skills:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ProjectSkillResponse'
          description: Normalized taxonomy skills linked to this portfolio project.
        includeInCv:
          type: boolean
        version:
          type: integer
          minimum: 0
          readOnly: true
          description: Optimistic-lock entity version used in If-Match.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
      description:
        Student-owned portfolio-only project. It carries no approval, verification, reviewer, eligibility, filtering,
        score, rank, or automated-selection state.
      examples:
        - projectId: 660e8400-e29b-41d4-a716-446655440001
          title: Accessible Internship Portal
          description: A responsive portfolio project for managing structured internship application data.
          repositoryUrl: https://github.com/example/accessible-internship-portal
          demoUrl: null
          startDate: '2026-01-10'
          endDate: '2026-05-15'
          skills:
            - skillId: 11111111-1111-4111-8111-111111111111
              name: React
              description: Component-based frontend library.
            - skillId: 22222222-2222-4222-8222-222222222222
              name: TypeScript
              description: null
          includeInCv: true
          version: 2
          createdAt: '2026-07-16T08:00:00Z'
          updatedAt: '2026-07-16T09:45:00Z'
    ShortlistCandidateRequest:
      type: object
      additionalProperties: false
      required:
        - studentIds
      properties:
        studentIds:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          maxItems: 100
          uniqueItems: true
        note:
          type:
            - string
            - 'null'
          maxLength: 1000
      description: Manual batch addition. Already-present candidates are reported, not duplicated.
    ShortlistCreateRequest:
      type: object
      additionalProperties: false
      required:
        - requestId
      properties:
        requestId:
          type: string
          format: uuid
        filterRunId:
          type:
            - string
            - 'null'
          format: uuid
        name:
          type:
            - string
            - 'null'
          maxLength: 200
      description:
        Creates the single Version 1 shortlist for an internship request. Candidate selection remains an explicit
        manual mutation.
    ShortlistFinalizeRequest:
      type: object
      additionalProperties: false
      required:
        - acknowledgeGuidanceWarning
      properties:
        acknowledgeGuidanceWarning:
          type: boolean
        finalizationNote:
          type:
            - string
            - 'null'
          maxLength: 1000
    ShortlistFinalizeResponse:
      type: object
      additionalProperties: false
      required:
        - shortlistId
        - status
        - selectedCandidateCount
        - guidanceValue
        - guidanceExceeded
        - guidanceAcknowledged
        - version
        - finalizedAt
      properties:
        shortlistId:
          type: string
          format: uuid
        status:
          type: string
          const: FINALIZED
        selectedCandidateCount:
          type: integer
          minimum: 1
        guidanceValue:
          type:
            - integer
            - 'null'
          minimum: 0
        guidanceExceeded:
          type: boolean
        guidanceAcknowledged:
          type: boolean
        version:
          type: integer
          minimum: 0
        finalizedAt:
          type: string
          format: date-time
    ShortlistResponse:
      type: object
      additionalProperties: false
      required:
        - shortlistId
        - request
        - filterRunId
        - name
        - status
        - guidanceValue
        - selectedCandidateCount
        - guidanceExceeded
        - guidanceWarning
        - version
        - createdAt
        - updatedAt
        - finalizedAt
      properties:
        shortlistId:
          type: string
          format: uuid
        request:
          $ref: '#/components/schemas/InternshipRequestSummaryResponse'
        filterRunId:
          type:
            - string
            - 'null'
          format: uuid
        name:
          type:
            - string
            - 'null'
          maxLength: 200
        status:
          $ref: '#/components/schemas/ShortlistStatus'
        guidanceValue:
          type:
            - integer
            - 'null'
          minimum: 0
        selectedCandidateCount:
          type: integer
          minimum: 0
        guidanceExceeded:
          type: boolean
        guidanceWarning:
          type:
            - string
            - 'null'
          maxLength: 500
        version:
          type: integer
          minimum: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        finalizedAt:
          type:
            - string
            - 'null'
          format: date-time
    SkillTaxonomyResponse:
      type: object
      additionalProperties: false
      required:
        - clusters
      properties:
        clusters:
          type: array
          items:
            $ref: '#/components/schemas/SkillClusterResponse'
      description:
        Developer-managed Core Cluster -> Skill Category -> Individual Skill tree. A cross-mapped Individual Skill
        may appear under multiple categories but keeps the same canonical skillId.
    StudentLoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
          writeOnly: true
    StudentProfileResponse:
      type: object
      additionalProperties: false
      required:
        - studentId
        - fullName
        - indexNumber
        - universityEmail
        - degreeProgramme
        - studentLevel
        - cohortYear
        - personalEmail
        - headline
        - summary
        - phone
        - location
        - profilePhoto
        - version
        - updatedAt
        - cvSourceUpdatedAt
      properties:
        studentId:
          type: string
          format: uuid
          readOnly: true
        fullName:
          type: string
          minLength: 1
          maxLength: 150
          description: Editable display/profile name; not an identity-matching key.
        indexNumber:
          type: string
          minLength: 1
          maxLength: 30
          readOnly: true
          description: Immutable Student identity value.
        universityEmail:
          type: string
          format: email
          maxLength: 254
          readOnly: true
          description: Immutable university identity email.
        degreeProgramme:
          type: string
          readOnly: true
          description: Read-only degree programme label displayed in the Student Profile academic context.
        studentLevel:
          type: integer
          enum:
            - 3
            - 4
          readOnly: true
        cohortYear:
          type:
            - integer
            - 'null'
          readOnly: true
          description: Read-only batch/cohort year when available.
        personalEmail:
          type:
            - string
            - 'null'
          format: email
          maxLength: 254
          description: Optional personal contact email; distinct from immutable universityEmail.
        headline:
          type:
            - string
            - 'null'
          maxLength: 200
          description: Optional professional headline or objective title.
        summary:
          type:
            - string
            - 'null'
          description: Optional professional profile summary or objective.
        phone:
          type:
            - string
            - 'null'
          maxLength: 30
          description: Optional Student contact phone number.
        location:
          type:
            - string
            - 'null'
          maxLength: 150
          description: Optional general city/state or location text.
        profilePhoto:
          anyOf:
            - $ref: '#/components/schemas/FileAssetResponse'
            - type: 'null'
          readOnly: true
        version:
          type: integer
          minimum: 0
          readOnly: true
          description: Optimistic-lock entity version used in If-Match.
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        cvSourceUpdatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Latest CV-source freshness timestamp after profile-related changes.
    StudentProfileUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        fullName:
          type: string
          minLength: 1
          maxLength: 150
        personalEmail:
          type:
            - string
            - 'null'
          format: email
          maxLength: 254
        headline:
          type:
            - string
            - 'null'
          maxLength: 200
        summary:
          type:
            - string
            - 'null'
        phone:
          type:
            - string
            - 'null'
          maxLength: 30
        location:
          type:
            - string
            - 'null'
          maxLength: 150
      description:
        Partial update of editable profile fields only. Immutable identity and academic fields are rejected as
        unknown properties.
    StudentVerificationResponse:
      type: object
      properties:
        verificationId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - OTP_SENT
            - VERIFICATION_FAILED
        message:
          type: string
        expiresAt:
          type: string
          format: date-time
    StudentVerificationStartRequest:
      type: object
      required:
        - fullName
        - indexNumber
        - universityEmail
      properties:
        fullName:
          type: string
        indexNumber:
          type: string
        universityEmail:
          type: string
          format: email
    AuditEventResponse:
      type: object
      properties:
        auditEventId:
          type: string
          format: uuid
        actorRole:
          type: string
        action:
          type: string
        resourceType:
          type: string
        createdAt:
          type: string
          format: date-time
        correlationId:
          type: string
    AccountType:
      type: string
      enum:
        - STUDENT
        - ADMIN
      description: Supported authenticated account type for the locked Version 1 scope.
    StudentSummaryResponse:
      type: object
      additionalProperties: false
      required:
        - studentId
        - indexNumber
        - fullName
        - universityEmail
        - degreeProgram
        - academicBatch
        - currentLevel
        - officialGpa
      properties:
        studentId:
          type: string
          format: uuid
          readOnly: true
        indexNumber:
          type: string
          minLength: 1
          maxLength: 40
          readOnly: true
        fullName:
          type: string
          minLength: 1
          maxLength: 200
          readOnly: true
        universityEmail:
          type: string
          format: email
          maxLength: 254
          readOnly: true
        degreeProgram:
          type: string
          minLength: 1
          maxLength: 160
          readOnly: true
        academicBatch:
          type: string
          pattern: ^[0-9]{4}$
          readOnly: true
          description: Cohort entry year used by the approved roster search.
        currentLevel:
          type: integer
          enum:
            - 3
            - 4
          readOnly: true
        officialGpa:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 4
          multipleOf: 0.01
          readOnly: true
          description: Latest committed official Computer Science GPA; null when unavailable.
    IndividualSkillResponse:
      type: object
      additionalProperties: false
      required:
        - skillId
        - name
      properties:
        skillId:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          minLength: 1
        description:
          type:
            - string
            - 'null'
      description:
        Canonical developer-managed Individual Skill. The same skillId is reused for every category mapping; cross-mapped
        skills are not duplicated.
    SkillCategoryResponse:
      type: object
      additionalProperties: false
      required:
        - categoryId
        - name
      properties:
        categoryId:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          minLength: 1
        description:
          type:
            - string
            - 'null'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/IndividualSkillResponse'
      description: Developer-managed Skill Category within one Core Cluster.
    SkillClusterResponse:
      type: object
      additionalProperties: false
      required:
        - clusterId
        - name
      properties:
        clusterId:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          minLength: 1
        description:
          type:
            - string
            - 'null'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/SkillCategoryResponse'
      description: Developer-managed top-level Core Cluster.
    CandidateFilteringCandidateResponse:
      type: object
      additionalProperties: false
      required:
        - studentId
        - indexNumber
        - fullName
        - officialGpa
        - gpaAvailabilityStatus
        - matchingDeclaredSkills
        - declaredSkillCount
        - hasLatestSavedCv
        - hasExistingActiveShortlist
        - existingActiveShortlistCount
      properties:
        studentId:
          type: string
          format: uuid
        indexNumber:
          type: string
          minLength: 1
          maxLength: 30
        fullName:
          type: string
          minLength: 1
          maxLength: 150
        officialGpa:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 4
          multipleOf: 0.01
          description:
            Latest committed official Computer Science GPA. Candidates without GPA are excluded whenever a GPA
            bound is active.
        gpaAvailabilityStatus:
          $ref: '#/components/schemas/GpaAvailabilityStatus'
        matchingDeclaredSkills:
          type: array
          items:
            $ref: '#/components/schemas/DeclaredSkillResponse'
        declaredSkillCount:
          type: integer
          minimum: 0
        hasLatestSavedCv:
          type: boolean
        hasExistingActiveShortlist:
          type: boolean
          description: Factual non-blocking decision-support indicator.
        existingActiveShortlistCount:
          type: integer
          minimum: 0
      description: Deterministic filter match. It contains no score, rank, weight, probability, recommendation, or match percentage.
    StudentDashboardMetricsResponse:
      type: object
      additionalProperties: false
      required:
        - projectCount
        - shortlistedInternshipCount
        - declaredSkillCount
        - officialCumulativeGpa
        - lastUpdatedAt
      properties:
        projectCount:
          type: integer
          minimum: 0
          description: Count of Student-owned portfolio project records.
        shortlistedInternshipCount:
          type: integer
          minimum: 0
          description: Count of internships for which the Student is present in an Admin-managed shortlist.
        declaredSkillCount:
          type: integer
          minimum: 0
          description: Count of the Student’s declared-skill records.
        officialCumulativeGpa:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 4
          multipleOf: 0.01
          description: Official cumulative/Computer Science GPA derived from committed academic data, or null when unavailable.
        lastUpdatedAt:
          type: string
          format: date-time
          description: Timestamp at which the returned summary was calculated.
      examples:
        - projectCount: 3
          shortlistedInternshipCount: 1
          declaredSkillCount: 8
          officialCumulativeGpa: 3.42
          lastUpdatedAt: '2026-07-15T04:30:00Z'
    FileAssetResponse:
      type: object
      additionalProperties: false
      required:
        - fileId
        - fileName
        - mimeType
        - fileSizeBytes
        - url
        - createdAt
      properties:
        fileId:
          type: string
          format: uuid
          readOnly: true
        fileName:
          type: string
          maxLength: 255
          readOnly: true
        mimeType:
          type: string
          maxLength: 120
          readOnly: true
        fileSizeBytes:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
        url:
          type: string
          format: uri
          readOnly: true
          description: Authorized file URL; may be time-limited.
        createdAt:
          type: string
          format: date-time
          readOnly: true
    FileUploadConstraint:
      type: object
      additionalProperties: false
      required:
        - allowedMimeTypes
        - allowedExtensions
        - maxSizeBytes
      properties:
        allowedMimeTypes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
        allowedExtensions:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            pattern: ^\.[A-Za-z0-9]+$
        maxSizeBytes:
          type: integer
          format: int64
          minimum: 1
    ProfileUploadPolicyResponse:
      type: object
      additionalProperties: false
      required:
        - profilePhoto
        - certificateEvidence
      properties:
        profilePhoto:
          allOf:
            - $ref: '#/components/schemas/FileUploadConstraint'
          description: Current server-controlled profile-photo upload policy.
        certificateEvidence:
          allOf:
            - $ref: '#/components/schemas/FileUploadConstraint'
          description: Current server-controlled certificate-evidence upload policy.
    ContactLinkCreateRequest:
      type: object
      additionalProperties: false
      required:
        - label
        - url
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 60
          description: Display label such as LinkedIn, GitHub, Portfolio, or Personal Website.
        url:
          type: string
          format: uri
        displayOrder:
          type: integer
          minimum: 0
          default: 0
        cvInclude:
          type: boolean
          default: true
    ContactLinkUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 60
          description: Display label such as LinkedIn, GitHub, Portfolio, or Personal Website.
        url:
          type: string
          format: uri
        displayOrder:
          type: integer
          minimum: 0
          default: 0
        cvInclude:
          type: boolean
          default: true
    CertificateCreateRequest:
      type: object
      additionalProperties: false
      required:
        - title
        - issuer
        - issueDate
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        issuer:
          type: string
          minLength: 1
          maxLength: 200
        issueDate:
          type: string
          format: date
        credentialUrl:
          type:
            - string
            - 'null'
          format: uri
        cvInclude:
          type: boolean
          default: true
    CertificateUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        issuer:
          type: string
          minLength: 1
          maxLength: 200
        issueDate:
          type: string
          format: date
        credentialUrl:
          type:
            - string
            - 'null'
          format: uri
        cvInclude:
          type: boolean
          default: true
    AwardCreateRequest:
      type: object
      additionalProperties: false
      required:
        - title
        - issuer
        - awardDate
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        issuer:
          type: string
          minLength: 1
          maxLength: 200
        awardDate:
          type: string
          format: date
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
    AwardUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        issuer:
          type: string
          minLength: 1
          maxLength: 200
        awardDate:
          type: string
          format: date
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
    ActivityCreateRequest:
      type: object
      additionalProperties: false
      required:
        - activityName
        - roleTitle
      properties:
        activityName:
          type: string
          minLength: 1
          maxLength: 200
        roleTitle:
          type: string
          minLength: 1
          maxLength: 150
        startDate:
          type:
            - string
            - 'null'
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: Optional end date; when both dates are present, it must not precede startDate.
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
    ActivityUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        activityName:
          type: string
          minLength: 1
          maxLength: 200
        roleTitle:
          type: string
          minLength: 1
          maxLength: 150
        startDate:
          type:
            - string
            - 'null'
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: Optional end date; when both dates are present, it must not precede startDate.
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
    ExperienceCreateRequest:
      type: object
      additionalProperties: false
      required:
        - organization
        - positionTitle
        - startDate
        - currentRole
      properties:
        organization:
          type: string
          minLength: 1
          maxLength: 200
        positionTitle:
          type: string
          minLength: 1
          maxLength: 150
        location:
          type:
            - string
            - 'null'
        startDate:
          type: string
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: Null for a current role; otherwise it must not precede startDate.
        currentRole:
          type: boolean
          default: false
          description: True when the position is ongoing; endDate must then be null.
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
      allOf:
        - if:
            properties:
              currentRole:
                const: true
            required:
              - currentRole
          then:
            properties:
              endDate:
                type: 'null'
        - if:
            properties:
              currentRole:
                const: false
            required:
              - currentRole
          then:
            required:
              - endDate
    ExperienceUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        organization:
          type: string
          minLength: 1
          maxLength: 200
        positionTitle:
          type: string
          minLength: 1
          maxLength: 150
        location:
          type:
            - string
            - 'null'
        startDate:
          type: string
          format: date
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: Null for a current role; otherwise it must not precede startDate.
        currentRole:
          type: boolean
          default: false
          description: True when the position is ongoing; endDate must then be null.
        description:
          type:
            - string
            - 'null'
        cvInclude:
          type: boolean
          default: true
      allOf:
        - if:
            properties:
              currentRole:
                const: true
            required:
              - currentRole
          then:
            properties:
              endDate:
                type: 'null'
    GpaAvailabilityStatus:
      type: string
      description: Availability of the official Computer Science GPA derived from committed academic records.
      enum:
        - AVAILABLE
        - NOT_AVAILABLE
    CvFreshnessStatus:
      type: string
      description:
        Freshness of the active saved CV relative to current structured source data. NOT_SAVED means no saved CV
        exists; CURRENT means the saved CV matches current source data; OUTDATED means one or more approved source areas changed
        after the latest save.
      enum:
        - NOT_SAVED
        - CURRENT
        - OUTDATED
    CvSourceArea:
      type: string
      description: Approved high-level source area that can make the latest saved CV outdated.
      enum:
        - PROFILE
        - DECLARED_SKILLS
        - PROJECTS
        - ACADEMIC_RECORDS
    AcademicRecordResponse:
      type: object
      additionalProperties: false
      required:
        - academicRecordId
        - subjectId
        - courseCode
        - courseTitle
        - credits
        - letterGrade
        - gradePoint
        - semester
        - academicYear
        - attemptNumber
        - resultStatus
        - committedAt
      properties:
        academicRecordId:
          type: string
          format: uuid
          readOnly: true
          description: Stable identifier of the committed official Student grade record.
        subjectId:
          type: string
          format: uuid
          readOnly: true
          description: Stable identifier of the canonical academic subject.
        courseCode:
          type: string
          minLength: 1
          maxLength: 30
          description: Official subject/course code.
        courseTitle:
          type: string
          minLength: 1
          maxLength: 250
          description: Official subject/course title.
        credits:
          type: number
          minimum: 0
          multipleOf: 0.1
          description: Official credit value committed for this result.
        letterGrade:
          type: string
          minLength: 1
          maxLength: 5
          description: Official letter grade from the committed ledger.
        gradePoint:
          type: number
          minimum: 0
          maximum: 4
          multipleOf: 0.01
          description: Official grade-point value from the committed ledger.
        semester:
          type: string
          minLength: 1
          maxLength: 80
          description: Official semester/period label.
        academicYear:
          type: string
          minLength: 1
          maxLength: 30
          description: Official academic-year label.
        attemptNumber:
          type: integer
          minimum: 1
          description: Attempt number retained by the official ledger.
        resultStatus:
          type: string
          minLength: 1
          maxLength: 30
          description: Official result status supplied by the committed ledger.
        committedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp at which the record became official committed data.
      description:
        One official committed academic result. Students can read only their own records and cannot mutate this
        DTO.
      examples:
        - academicRecordId: 10000000-0000-4000-8000-000000000001
          subjectId: 20000000-0000-4000-8000-000000000001
          courseCode: CSC3112
          courseTitle: Web Technologies
          credits: 4.0
          letterGrade: A-
          gradePoint: 3.7
          semester: Semester 1
          academicYear: 2025/2026
          attemptNumber: 1
          resultStatus: PASSED
          committedAt: '2026-07-20T09:30:00Z'
    AcademicRecordSourceResponse:
      type: object
      additionalProperties: false
      required:
        - sourceUploadId
        - committedAt
      properties:
        sourceUploadId:
          type: string
          format: uuid
          readOnly: true
          description: Latest committed academic-ledger upload used for the GPA summary.
        committedAt:
          type: string
          format: date-time
          readOnly: true
          description: Commit timestamp of the source ledger upload.
      description: Minimal safe source metadata for an available official GPA.
    CvPreviewConfigurationResponse:
      type: object
      additionalProperties: false
      required:
        - includedExperienceIds
        - includedProjectIds
        - includedCertificateIds
        - includedAwardIds
        - includedActivityIds
      properties:
        includedExperienceIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
        includedProjectIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
        includedCertificateIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
        includedAwardIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
        includedActivityIds:
          $ref: '#/components/schemas/CvSelectedRecordIds'
      description: Immutable inclusion snapshot applied using the backend's fixed default section order.
    CvSelectedRecordIds:
      type: array
      maxItems: 100
      uniqueItems: true
      items:
        type: string
        format: uuid
      description: Sorted, unique identifiers for Student-owned records selected for one CV section.
    GeneratedFileMetadataResponse:
      type: object
      additionalProperties: false
      required:
        - fileName
        - mediaType
        - fileSizeBytes
        - generatedAt
      properties:
        fileName:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[A-Za-z0-9._-]+\.pdf$
          readOnly: true
          description: Sanitized PDF filename with no path separators.
        mediaType:
          type: string
          enum:
            - application/pdf
          readOnly: true
        fileSizeBytes:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
        generatedAt:
          type: string
          format: date-time
          readOnly: true
      description: Safe generated PDF metadata; no local path, storage key, or credential is exposed.
    AcademicLedgerUploadStatus:
      type: string
      enum:
        - RECEIVED
        - PROCESSING
        - STAGED
        - READY_TO_COMMIT
        - COMMITTING
        - COMMITTED
        - VALIDATION_FAILED
        - PROCESSING_FAILED
      description:
        Upload-batch lifecycle. Commit is permitted only in READY_TO_COMMIT. COMMITTED, VALIDATION_FAILED, and
        PROCESSING_FAILED are terminal for the batch. A failed commit transaction returns the batch to READY_TO_COMMIT.
      x-state-transitions:
        RECEIVED:
          - PROCESSING
        PROCESSING:
          - STAGED
          - PROCESSING_FAILED
        STAGED:
          - READY_TO_COMMIT
          - VALIDATION_FAILED
        READY_TO_COMMIT:
          - COMMITTING
        COMMITTING:
          - COMMITTED
          - READY_TO_COMMIT
        COMMITTED: []
        VALIDATION_FAILED: []
        PROCESSING_FAILED: []
    AcademicLedgerValidationStatus:
      type: string
      enum:
        - NOT_STARTED
        - IN_PROGRESS
        - PASSED
        - FAILED
      description: Validation lifecycle independent of the upload-processing lifecycle.
      x-state-transitions:
        NOT_STARTED:
          - IN_PROGRESS
        IN_PROGRESS:
          - PASSED
          - FAILED
        PASSED: []
        FAILED: []
    AcademicLedgerRowValidationStatus:
      type: string
      enum:
        - VALID
        - WARNING
        - INVALID
      description: Normalized staged-row validation outcome.
    AcademicLedgerValidationSeverity:
      type: string
      enum:
        - ERROR
        - WARNING
    AcademicLedgerUploadSort:
      type: string
      enum:
        - uploadedAt,desc
        - uploadedAt,asc
        - originalFilename,asc
        - status,asc
        - status,desc
      default: uploadedAt,desc
    AcademicLedgerStagedRowSort:
      type: string
      enum:
        - rowNumber,asc
        - rowNumber,desc
        - studentIndexNumber,asc
        - courseCode,asc
        - validationStatus,asc
      default: rowNumber,asc
    RegisteredStudentSort:
      type: string
      enum:
        - fullName,asc
        - officialGpa,desc
        - officialGpa,asc
        - indexNumber,asc
      default: fullName,asc
    AcademicRecordSort:
      type: string
      enum:
        - academicYear,desc
        - courseCode,asc
        - semester,asc
        - gradePoint,desc
      default: academicYear,desc
    AcademicLedgerUploadSummaryResponse:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - originalFilename
        - contentType
        - fileSizeBytes
        - uploadStatus
        - validationStatus
        - totalRows
        - validRows
        - invalidRows
        - uploadedAt
        - committedAt
        - failureSummary
      properties:
        uploadId:
          type: string
          format: uuid
          readOnly: true
        originalFilename:
          type: string
          minLength: 1
          maxLength: 255
          readOnly: true
        contentType:
          type: string
          const: text/csv
          readOnly: true
        fileSizeBytes:
          type: integer
          minimum: 1
          maximum: 5242880
          readOnly: true
        uploadStatus:
          $ref: '#/components/schemas/AcademicLedgerUploadStatus'
        validationStatus:
          $ref: '#/components/schemas/AcademicLedgerValidationStatus'
        totalRows:
          type: integer
          minimum: 0
          readOnly: true
        validRows:
          type: integer
          minimum: 0
          readOnly: true
        invalidRows:
          type: integer
          minimum: 0
          readOnly: true
        uploadedAt:
          type: string
          format: date-time
          readOnly: true
        committedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
        failureSummary:
          type:
            - string
            - 'null'
          maxLength: 500
          readOnly: true
          description: Sanitized batch-level failure summary without internal exception data.
      examples:
        - uploadId: 30000000-0000-4000-8000-000000000001
          originalFilename: computer-science-results-2025-2026.csv
          contentType: text/csv
          fileSizeBytes: 84216
          uploadStatus: READY_TO_COMMIT
          validationStatus: PASSED
          totalRows: 240
          validRows: 240
          invalidRows: 0
          uploadedAt: '2026-07-19T08:00:00Z'
          committedAt: null
          failureSummary: null
    AcademicLedgerUploadDetailResponse:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - originalFilename
        - contentType
        - fileSizeBytes
        - uploadStatus
        - validationStatus
        - totalRows
        - validRows
        - invalidRows
        - uploadedAt
        - committedAt
        - failureSummary
        - statusMessage
        - nextPollAfterSeconds
      properties:
        uploadId:
          type: string
          format: uuid
          readOnly: true
        originalFilename:
          type: string
          minLength: 1
          maxLength: 255
          readOnly: true
        contentType:
          type: string
          const: text/csv
          readOnly: true
        fileSizeBytes:
          type: integer
          minimum: 1
          maximum: 5242880
          readOnly: true
        uploadStatus:
          $ref: '#/components/schemas/AcademicLedgerUploadStatus'
        validationStatus:
          $ref: '#/components/schemas/AcademicLedgerValidationStatus'
        totalRows:
          type: integer
          minimum: 0
          readOnly: true
        validRows:
          type: integer
          minimum: 0
          readOnly: true
        invalidRows:
          type: integer
          minimum: 0
          readOnly: true
        uploadedAt:
          type: string
          format: date-time
          readOnly: true
        committedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
        failureSummary:
          type:
            - string
            - 'null'
          maxLength: 500
          readOnly: true
        statusMessage:
          type: string
          minLength: 1
          maxLength: 300
          readOnly: true
        nextPollAfterSeconds:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 30
          readOnly: true
          description: Polling hint only for RECEIVED, PROCESSING, STAGED, or COMMITTING.
      examples:
        - uploadId: 30000000-0000-4000-8000-000000000001
          originalFilename: computer-science-results-2025-2026.csv
          contentType: text/csv
          fileSizeBytes: 84216
          uploadStatus: PROCESSING
          validationStatus: NOT_STARTED
          totalRows: 0
          validRows: 0
          invalidRows: 0
          uploadedAt: '2026-07-19T08:00:00Z'
          committedAt: null
          failureSummary: null
          statusMessage: The CSV file is being parsed and staged.
          nextPollAfterSeconds: 2
        - uploadId: 30000000-0000-4000-8000-000000000001
          originalFilename: computer-science-results-2025-2026.csv
          contentType: text/csv
          fileSizeBytes: 84216
          uploadStatus: READY_TO_COMMIT
          validationStatus: PASSED
          totalRows: 240
          validRows: 240
          invalidRows: 0
          uploadedAt: '2026-07-19T08:00:00Z'
          committedAt: null
          failureSummary: null
          statusMessage: All staged rows passed validation and the batch is ready to commit.
          nextPollAfterSeconds: null
    AcademicLedgerValidationErrorResponse:
      type: object
      additionalProperties: false
      required:
        - rowNumber
        - field
        - code
        - message
        - severity
        - rejectedValue
        - relatedRowNumber
      properties:
        rowNumber:
          type: integer
          minimum: 1
          readOnly: true
        field:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 80
          readOnly: true
        code:
          type: string
          pattern: ^[A-Z][A-Z0-9_]{2,63}$
          readOnly: true
        message:
          type: string
          minLength: 1
          maxLength: 300
          readOnly: true
        severity:
          $ref: '#/components/schemas/AcademicLedgerValidationSeverity'
        rejectedValue:
          type:
            - string
            - 'null'
          maxLength: 120
          readOnly: true
          description: Sanitized and truncated value; never contains secrets or unrestricted raw row data.
        relatedRowNumber:
          type:
            - integer
            - 'null'
          minimum: 1
          readOnly: true
    AcademicLedgerStagedRowResponse:
      type: object
      additionalProperties: false
      required:
        - stagingRowId
        - uploadId
        - rowNumber
        - studentIndexNumber
        - studentId
        - courseCode
        - courseTitle
        - credits
        - letterGrade
        - gradePoint
        - semester
        - academicYear
        - attemptNumber
        - resultStatus
        - validationStatus
        - validationErrors
      properties:
        stagingRowId:
          type: string
          format: uuid
          readOnly: true
        uploadId:
          type: string
          format: uuid
          readOnly: true
        rowNumber:
          type: integer
          minimum: 2
          readOnly: true
          description: Physical CSV row number; row 1 is the required header.
        studentIndexNumber:
          type: string
          minLength: 1
          maxLength: 40
          readOnly: true
        studentId:
          type:
            - string
            - 'null'
          format: uuid
          readOnly: true
          description: Resolved Student identifier; null when identity validation failed.
        courseCode:
          type: string
          minLength: 1
          maxLength: 30
          readOnly: true
        courseTitle:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 250
          readOnly: true
          description: Resolved canonical subject title; null when course validation failed.
        credits:
          type: number
          exclusiveMinimum: 0
          maximum: 30
          multipleOf: 0.1
          readOnly: true
        letterGrade:
          type: string
          minLength: 1
          maxLength: 5
          readOnly: true
        gradePoint:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 4
          multipleOf: 0.01
          readOnly: true
          description: Backend-derived grade point; null when the grade cannot be resolved.
        semester:
          type: string
          minLength: 1
          maxLength: 80
          readOnly: true
        academicYear:
          type: string
          pattern: ^[0-9]{4}/[0-9]{4}$
          readOnly: true
        attemptNumber:
          type: integer
          minimum: 1
          maximum: 20
          readOnly: true
        resultStatus:
          type: string
          minLength: 1
          maxLength: 30
          readOnly: true
        validationStatus:
          $ref: '#/components/schemas/AcademicLedgerRowValidationStatus'
        validationErrors:
          type: array
          items:
            $ref: '#/components/schemas/AcademicLedgerValidationErrorResponse'
          readOnly: true
      description:
        Normalized read-only staging row. It is not official academic data and cannot be edited through Version
        1 APIs.
    PagedAcademicLedgerStagedRowResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AcademicLedgerStagedRowResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
      examples:
        - items:
            - stagingRowId: 31000000-0000-4000-8000-000000000001
              uploadId: 30000000-0000-4000-8000-000000000001
              rowNumber: 2
              studentIndexNumber: SC/2022/12865
              studentId: 40000000-0000-4000-8000-000000000001
              courseCode: CSC3112
              courseTitle: Web Technologies
              credits: 4.0
              letterGrade: A-
              gradePoint: 3.7
              semester: Semester 1
              academicYear: 2025/2026
              attemptNumber: 1
              resultStatus: PASSED
              validationStatus: VALID
              validationErrors: []
            - stagingRowId: 31000000-0000-4000-8000-000000000002
              uploadId: 30000000-0000-4000-8000-000000000001
              rowNumber: 3
              studentIndexNumber: SC/2099/99999
              studentId: null
              courseCode: CSC3112
              courseTitle: Web Technologies
              credits: 4.0
              letterGrade: A
              gradePoint: 4.0
              semester: Semester 1
              academicYear: 2025/2026
              attemptNumber: 1
              resultStatus: PASSED
              validationStatus: INVALID
              validationErrors:
                - rowNumber: 3
                  field: student_index_number
                  code: STUDENT_NOT_FOUND
                  message: No eligible Student matches the supplied index number.
                  severity: ERROR
                  rejectedValue: SC/2099/99999
                  relatedRowNumber: null
          page:
            page: 0
            size: 20
            totalElements: 2
            totalPages: 1
            sort: rowNumber,asc
        - items: []
          page:
            page: 0
            size: 20
            totalElements: 0
            totalPages: 0
            sort: rowNumber,asc
    CompetencyLevel:
      type: string
      enum:
        - BEGINNER
        - INTERMEDIATE
        - ADVANCED
    CompanySort:
      type: string
      enum:
        - name,asc
        - name,desc
        - updatedAt,desc
    InternshipRequestSort:
      type: string
      enum:
        - createdAt,desc
        - title,asc
        - companyName,asc
    CandidateSort:
      type: string
      enum:
        - officialGpa,desc
        - officialGpa,asc
        - fullName,asc
        - indexNumber,asc
    ShortlistSort:
      type: string
      enum:
        - updatedAt,desc
        - createdAt,desc
        - companyName,asc
        - roleTitle,asc
    FilterSkillMatchMode:
      type: string
      enum:
        - AND
        - OR
    ShortlistStatus:
      type: string
      enum:
        - DRAFT
        - FINALIZED
    ExportJobStatus:
      type: string
      enum:
        - QUEUED
        - PROCESSING
        - COMPLETED
        - FAILED
        - CANCELLED
    ExportType:
      type: string
      enum:
        - SHORTLIST_SUMMARY_CSV
        - BULK_LATEST_CV_ZIP
    ExportFormat:
      type: string
      enum:
        - CSV
        - ZIP
    AdminLatestCvAvailabilityStatus:
      type: string
      enum:
        - AVAILABLE
        - NOT_SAVED
    AdminLatestCvResponse:
      type: object
      additionalProperties: false
      required:
        - availability
        - cvId
        - revision
        - generatedAt
        - savedAt
        - freshnessStatus
        - fileName
        - fileSizeBytes
        - downloadUrl
      properties:
        availability:
          $ref: '#/components/schemas/AdminLatestCvAvailabilityStatus'
        cvId:
          type:
            - string
            - 'null'
          format: uuid
          readOnly: true
        revision:
          type:
            - integer
            - 'null'
          minimum: 1
          readOnly: true
        generatedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
        savedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
        freshnessStatus:
          oneOf:
            - type: string
              enum:
                - CURRENT
                - OUTDATED
            - type: 'null'
          readOnly: true
        fileName:
          type:
            - string
            - 'null'
          pattern: ^[A-Za-z0-9._-]+\.pdf$
          readOnly: true
        fileSizeBytes:
          type:
            - integer
            - 'null'
          minimum: 1
          readOnly: true
        downloadUrl:
          type:
            - string
            - 'null'
          pattern: ^/admin/students/[0-9a-fA-F-]{36}/latest-cv/download$
          readOnly: true
      description: Read-only latest saved CV availability. NOT_SAVED is not a review/submission state.
      examples:
        - availability: AVAILABLE
          cvId: 550e8400-e29b-41d4-a716-446655440000
          revision: 3
          generatedAt: '2026-07-19T08:30:00Z'
          savedAt: '2026-07-19T08:31:00Z'
          freshnessStatus: CURRENT
          fileName: ICT_2022_001_CV.pdf
          fileSizeBytes: 184320
          downloadUrl: /admin/students/550e8400-e29b-41d4-a716-446655440010/latest-cv/download
    AdminStudentCvSupportingDataResponse:
      type: object
      additionalProperties: false
      required:
        - experiences
        - certificates
        - awards
        - activities
      properties:
        experiences:
          type: array
          items:
            $ref: '#/components/schemas/ExperienceResponse'
        certificates:
          type: array
          items:
            $ref: '#/components/schemas/CertificateResponse'
        awards:
          type: array
          items:
            $ref: '#/components/schemas/AwardResponse'
        activities:
          type: array
          items:
            $ref: '#/components/schemas/ActivityResponse'
      description: Read-only Student CV-supporting records. Admin mutation is not supported.
    CompanyUpdateRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        websiteUrl:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 500
        contactPerson:
          type:
            - string
            - 'null'
          maxLength: 150
        contactEmail:
          type:
            - string
            - 'null'
          format: email
          maxLength: 254
        contactPhone:
          type:
            - string
            - 'null'
          maxLength: 30
        notes:
          type:
            - string
            - 'null'
          maxLength: 4000
      minProperties: 1
    InternshipRequestSummaryResponse:
      type: object
      additionalProperties: false
      required:
        - requestId
        - companyId
        - companyName
        - title
        - shortlistGuidanceValue
      properties:
        requestId:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        companyName:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        shortlistGuidanceValue:
          type:
            - integer
            - 'null'
          minimum: 0
    CandidateFilteringCriteriaRequest:
      type: object
      additionalProperties: false
      required:
        - requestId
        - skillMatchMode
      properties:
        requestId:
          type: string
          format: uuid
        runtimeGpaLowerBound:
          type: number
          minimum: 0
          maximum: 4
          multipleOf: 0.01
        runtimeGpaUpperBound:
          type: number
          minimum: 0
          maximum: 4
          multipleOf: 0.01
        requestSkillIds:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
          maxItems: 100
          default: []
        additionalSkillIds:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
          maxItems: 100
          default: []
        skillMatchMode:
          $ref: '#/components/schemas/FilterSkillMatchMode'
      description:
        Runtime-only deterministic criteria. Lower bound must not exceed upper bound. GPA is not copied to the
        request.
    CandidateFilteringCriteriaResponse:
      type: object
      additionalProperties: false
      required:
        - requestId
        - runtimeGpaLowerBound
        - runtimeGpaUpperBound
        - requestSkillIds
        - additionalSkillIds
        - skillMatchMode
      properties:
        requestId:
          type: string
          format: uuid
        runtimeGpaLowerBound:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 4
          multipleOf: 0.01
        runtimeGpaUpperBound:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 4
          multipleOf: 0.01
        requestSkillIds:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        additionalSkillIds:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        skillMatchMode:
          $ref: '#/components/schemas/FilterSkillMatchMode'
    ShortlistCandidateResponse:
      type: object
      additionalProperties: false
      required:
        - studentId
        - indexNumber
        - fullName
        - officialGpa
        - gpaAvailabilityStatus
        - hasLatestSavedCv
        - hasExistingActiveShortlist
        - existingActiveShortlistCount
        - selectedAt
        - selectionNote
      properties:
        studentId:
          type: string
          format: uuid
        indexNumber:
          type: string
        fullName:
          type: string
        officialGpa:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 4
          multipleOf: 0.01
        gpaAvailabilityStatus:
          $ref: '#/components/schemas/GpaAvailabilityStatus'
        hasLatestSavedCv:
          type: boolean
        hasExistingActiveShortlist:
          type: boolean
        existingActiveShortlistCount:
          type: integer
          minimum: 0
        selectedAt:
          type: string
          format: date-time
        selectionNote:
          type:
            - string
            - 'null'
          maxLength: 1000
    PagedShortlistCandidateResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ShortlistCandidateResponse'
        page:
          $ref: '#/components/schemas/PageMetadata'
    ShortlistDetailResponse:
      type: object
      additionalProperties: false
      required:
        - shortlist
        - candidates
      properties:
        shortlist:
          $ref: '#/components/schemas/ShortlistResponse'
        candidates:
          $ref: '#/components/schemas/PagedShortlistCandidateResponse'
    ShortlistCandidateMutationResponse:
      type: object
      additionalProperties: false
      required:
        - shortlistId
        - addedCount
        - alreadyPresentCount
        - removedCount
        - selectedCandidateCount
        - guidanceExceeded
        - version
      properties:
        shortlistId:
          type: string
          format: uuid
        addedCount:
          type: integer
          minimum: 0
        alreadyPresentCount:
          type: integer
          minimum: 0
        removedCount:
          type: integer
          minimum: 0
        selectedCandidateCount:
          type: integer
          minimum: 0
        guidanceExceeded:
          type: boolean
        version:
          type: integer
          minimum: 0
    ShortlistSummaryExportCreateRequest:
      type: object
      additionalProperties: false
      required:
        - format
      properties:
        format:
          type: string
          const: CSV
      description: Requests an asynchronous final shortlist summary CSV export.
    BulkCvExportCreateRequest:
      type: object
      additionalProperties: false
      required:
        - format
      properties:
        format:
          type: string
          const: ZIP
      description: Requests an asynchronous ZIP containing available latest-saved ATS-compliant PDF CVs.
    MissingCvStudentResponse:
      type: object
      additionalProperties: false
      required:
        - studentId
        - indexNumber
        - fullName
      properties:
        studentId:
          type: string
          format: uuid
        indexNumber:
          type: string
        fullName:
          type: string
    ExportWarningResponse:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - MISSING_CVS
            - PARTIAL_EXPORT
        message:
          type: string
          maxLength: 500
  examples:
    ValidationFailed:
      value:
        type: https://uor-cv-system/errors/validation-failed
        title: Validation failed
        status: 422
        code: VALIDATION_FAILED
        message: One or more fields are invalid.
        correlationId: req-20260630-0001
        fieldErrors:
          - field: universityEmail
            code: INVALID_EMAIL_FORMAT
            message: University email format is invalid.
  headers:
    Location:
      description: Canonical URL of the accepted upload-batch status resource.
      schema:
        type: string
        format: uri-reference
    RetryAfterSeconds:
      description: Minimum seconds before polling the upload-batch status resource again.
      schema:
        type: integer
        minimum: 1
        maximum: 30
    EntityTag:
      description: Quoted integer entity version used with If-Match for optimistic concurrency.
      required: true
      schema:
        type: string
        pattern: ^"[0-9]+"$
        examples:
          - '"3"'
    ContentDispositionPdf:
      description: Safe PDF attachment filename.
      required: true
      schema:
        type: string
        pattern: ^attachment; filename="[A-Za-z0-9._-]+\.pdf"$
    ContentDispositionCsv:
      description: Safe CSV attachment filename.
      required: true
      schema:
        type: string
        pattern: ^attachment; filename="[A-Za-z0-9._-]+\.csv"$
    ContentDispositionZip:
      description: Safe ZIP attachment filename.
      required: true
      schema:
        type: string
        pattern: ^attachment; filename="[A-Za-z0-9._-]+\.zip"$
    CacheControlNoStore:
      description: Sensitive downloads are never cached.
      required: true
      schema:
        type: string
        const: no-store