schema.yml

openapi: 3.0.0
info:
  title: LORIS API
  description: |
    LORIS REST API and Module endpoints.

    ## Server Configuration
    | Type | Configuration | Endpoints |
    | --- | --- | --- |
    | REST API | `setHost("{$baseUrl}/api/{$version}")` | /login, /candidates, /projects, /sites |
    | Module | `setHost($baseUrl)` | /instrument_manager/*, /cbigr_api/script/* |
  contact:
    name: LORIS Development Team
    url: https://github.com/aces/Loris
  license:
    name: GNU Public License, Version 3
    url: https://opensource.org/licenses/GPL-3.0
  version: 0.0.4-dev
servers:
  - url: '{baseUrl}/api/{version}'
    description: REST API endpoints
    variables:
      baseUrl:
        default: https://demo.loris.ca
      version:
        default: v0.0.4-dev
  - url: '{baseUrl}'
    description: Module endpoints (instrument_manager, cbigr_api)
    variables:
      baseUrl:
        default: https://demo.loris.ca
paths:
  /login:
    post:
      tags:
        - Authentication
      summary: Authenticate and obtain JWT token
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Successful authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials

  /candidates:
    get:
      tags:
        - Candidates
      summary: List all candidates
      operationId: getCandidates
      security:
        - BearerAuth: []
      responses:
        '200':
          description: List of candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidatesResponse'
    post:
      tags:
        - Candidates
      summary: Create a new candidate
      operationId: createCandidate
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateCreateRequest'
      responses:
        '201':
          description: Candidate created
        '400':
          description: Invalid request

  /candidates/{candid}:
    get:
      tags:
        - Candidates
      summary: Get candidate details
      operationId: getCandidate
      security:
        - BearerAuth: []
      parameters:
        - name: candid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Candidate details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateObject'
        '404':
          description: Candidate not found

  /candidates/{candid}/{visit}:
    get:
      tags:
        - Visits
      summary: Get visit details
      operationId: getVisit
      security:
        - BearerAuth: []
      parameters:
        - name: candid
          in: path
          required: true
          schema:
            type: string
        - name: visit
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Visit details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitObject'
        '404':
          description: Visit not found
    put:
      tags:
        - Visits
      summary: Create a new visit
      operationId: createVisit
      security:
        - BearerAuth: []
      parameters:
        - name: candid
          in: path
          required: true
          schema:
            type: string
        - name: visit
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisitCreateRequest'
      responses:
        '201':
          description: Visit created
        '400':
          description: Invalid request

  /candidates/{candid}/{visit}/instruments:
    get:
      tags:
        - Instruments
      summary: List instruments for a visit
      operationId: getVisitInstruments
      security:
        - BearerAuth: []
      parameters:
        - name: candid
          in: path
          required: true
          schema:
            type: string
        - name: visit
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of instruments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitInstrumentsResponse'

  /candidates/{candid}/{visit}/instruments/{instrument}:
    get:
      tags:
        - Instruments
      summary: Get instrument data
      operationId: getInstrumentData
      security:
        - BearerAuth: []
      parameters:
        - name: candid
          in: path
          required: true
          schema:
            type: string
        - name: visit
          in: path
          required: true
          schema:
            type: string
        - name: instrument
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Instrument data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentDataResponse'
        '404':
          description: Instrument not found
    put:
      tags:
        - Instruments
      summary: Replace instrument data
      operationId: putInstrumentData
      security:
        - BearerAuth: []
      parameters:
        - name: candid
          in: path
          required: true
          schema:
            type: string
        - name: visit
          in: path
          required: true
          schema:
            type: string
        - name: instrument
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstrumentDataRequest'
      responses:
        '200':
          description: Data replaced
        '400':
          description: Invalid request
    patch:
      tags:
        - Instruments
      summary: Update instrument data
      operationId: patchInstrumentData
      security:
        - BearerAuth: []
      parameters:
        - name: candid
          in: path
          required: true
          schema:
            type: string
        - name: visit
          in: path
          required: true
          schema:
            type: string
        - name: instrument
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstrumentDataRequest'
      responses:
        '200':
          description: Data updated
        '400':
          description: Invalid request

  /projects:
    get:
      tags:
        - Projects
      summary: List projects
      operationId: getProjects
      security:
        - BearerAuth: []
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'

  /projects/{project}:
    get:
      tags:
        - Projects
      summary: Get project details
      operationId: getProject
      security:
        - BearerAuth: []
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'

  /projects/{project}/instruments:
    get:
      tags:
        - Projects
      summary: List project instruments
      operationId: getProjectInstruments
      security:
        - BearerAuth: []
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of instruments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentsResponse'

  /sites:
    get:
      tags:
        - Sites
      summary: List sites
      operationId: getSites
      security:
        - BearerAuth: []
      responses:
        '200':
          description: List of sites
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SitesResponse'

  # ==========================================================================
  # INSTRUMENT MANAGER ENDPOINTS (im3 — explicit parameters)
  # ==========================================================================
  /instrument_manager:
    post:
      tags:
        - InstrumentManager
      summary: Install instrument from a LINST file, a BIDS phenotype sidecar (json), or a REDCap data dictionary (csv). Sends instrument_type field (bids/linst/redcap).
      operationId: installInstrument
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InstrumentManagerForm'
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: string
                    default: "ok"
                    description: Contains the string "ok"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /instrument_manager/instrument_data:
    get:
      tags:
        - InstrumentManager
      summary: Get expected CSV or TSV headers for instrument data upload. Requires format query param (LORIS_CSV/REDCAP_CSV/BIDS_TSV).
      operationId: getInstrumentDataHeaders
      security:
        - BearerAuth: []
      parameters:
        - name: action
          in: query
          description: Either CREATE_SESSIONS or VALIDATE_SESSIONS
          required: true
          schema:
            type: string
            enum:
              - CREATE_SESSIONS
              - VALIDATE_SESSIONS
        - name: format
          in: query
          description: |
            Data format for the returned headers template.
            LORIS_CSV — standard LORIS CSV headers
            REDCAP_CSV — REDCap-style CSV headers (includes redcap_event_name etc.)
            BIDS_TSV — BIDS phenotype TSV headers (cannot be combined with CREATE_SESSIONS)
          required: true
          schema:
            type: string
            enum:
              - LORIS_CSV
              - REDCAP_CSV
              - BIDS_TSV
        - name: instrument
          in: query
          description: Single instrument name
          required: false
          schema:
            type: string
        - name: instruments
          in: query
          description: Multiple instrument names
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: CSV or TSV file with expected headers
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid parameters or invalid combination (BIDS_TSV with CREATE_SESSIONS)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
        - InstrumentManager
      summary: |
        Bulk upload instrument data from CSV or TSV file.
        Sends format (LORIS_CSV/REDCAP_CSV/BIDS_TSV) and strict (true/false) fields.
        Client auto-detects REDCap CSV via redcap_event_name column.
      operationId: uploadInstrumentData
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InstrumentDataForm'
      responses:
        '200':
          description: Validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether or not the insertion was successful
                  message:
                    oneOf:
                      - type: string
                      - type: array
                        items:
                          type: string
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether or not the insertion was successful
                  message:
                    type: string
                    description: Success message
                  idMapping:
                    type: array
                    description: Mapping of candidates' internal to external ID
                    items:
                      type: object
                      properties:
                        ExtStudyID:
                          type: string
                        CandID:
                          type: string
        '400':
          description: Invalid request or invalid combination (BIDS_TSV with CREATE_SESSIONS)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ==========================================================================
  # Script API (CBIGR Module - use base URL without /api/version)
  # ==========================================================================
  /cbigr_api/script/bidsimport:
    post:
      tags:
        - Script
      summary: Import BIDS dataset into LORIS
      description: Executes import_bids_dataset.py to import a BIDS dataset into LORIS.
      operationId: runBidsImport
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BidsImportRequest'
      responses:
        '200':
          description: Script executed (sync mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScriptSyncResponse'
        '202':
          description: Script started (async mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScriptAsyncResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error

  /cbigr_api/script/tarchiveloader:
    post:
      tags:
        - Script
      summary: Load DICOM tarchive into LORIS
      description: Executes tarchiveLoader.pl to process a DICOM archive.
      operationId: runTarchiveLoader
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TarchiveLoaderRequest'
      responses:
        '200':
          description: Script executed (sync mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScriptSyncResponse'
        '202':
          description: Script started (async mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScriptAsyncResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error

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

  schemas:
    LoginRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
        password:
          type: string

    LoginResponse:
      type: object
      properties:
        token:
          type: string

    CandidatesResponse:
      type: object
      properties:
        Candidates:
          type: array
          items:
            $ref: '#/components/schemas/CandidateObject'

    CandidateObject:
      type: object
      properties:
        CandID:
          type: string
        Project:
          type: string
        PSCID:
          type: string
        Site:
          type: string
        EDC:
          type: string
        DoB:
          type: string
        Sex:
          type: string
          enum: [Male, Female, Other]

    CandidateCreateRequest:
      type: object
      properties:
        Candidate:
          $ref: '#/components/schemas/CandidateCreateRequestCandidate'

    CandidateCreateRequestCandidate:
      type: object
      required:
        - Project
        - Site
        - DoB
        - Sex
      properties:
        Project:
          type: string
        Site:
          type: string
        EDC:
          type: string
        DoB:
          type: string
        Sex:
          type: string
          enum: [Male, Female, Other]

    VisitObject:
      type: object
      properties:
        Meta:
          $ref: '#/components/schemas/VisitObjectMeta'
        Stages:
          type: object

    VisitObjectMeta:
      type: object
      properties:
        CandID:
          type: string
        Visit:
          type: string
        Site:
          type: string
        Battery:
          type: string
        Project:
          type: string

    VisitCreateRequest:
      type: object
      properties:
        Meta:
          type: object
          properties:
            CandID:
              type: string
            Visit:
              type: string
            Site:
              type: string
            Battery:
              type: string
            Project:
              type: string

    VisitInstrumentsResponse:
      type: object
      properties:
        Meta:
          type: object
          properties:
            CandID:
              type: string
            Visit:
              type: string
        Instruments:
          type: array
          items:
            type: string

    InstrumentData:
      type: object
      properties:
        Meta:
          $ref: '#/components/schemas/InstrumentDataMeta'
        Data:
          type: object

    InstrumentDataMeta:
      type: object
      properties:
        Instrument:
          type: string
        Visit:
          type: string
        CandID:
          type: string
        DDE:
          type: boolean

    InstrumentDataRequest:
      type: object
      properties:
        Meta:
          $ref: '#/components/schemas/InstrumentDataRequestMeta'
        Data:
          type: object

    InstrumentDataRequestMeta:
      type: object
      properties:
        CandID:
          type: string
        Visit:
          type: string
        Instrument:
          type: string
        DDE:
          type: boolean

    InstrumentDataResponse:
      type: object
      properties:
        Meta:
          $ref: '#/components/schemas/InstrumentDataMeta'
        Data:
          type: object

    InstrumentDataResponseMessage:
      type: object
      properties:
        message:
          type: string

    InstrumentMeta:
      type: object
      properties:
        FullName:
          type: string
        Subgroup:
          type: string
        DoubleDataEntryEnabled:
          type: boolean

    InstrumentsResponse:
      type: object
      properties:
        Meta:
          type: object
          properties:
            Project:
              type: string
        Instruments:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/InstrumentMeta'

    ProjectsResponse:
      type: object
      properties:
        Projects:
          type: array
          items:
            type: string

    ProjectResponse:
      type: object
      properties:
        Meta:
          type: object
          properties:
            Project:
              type: string
        Visits:
          type: array
          items:
            type: string
        Instruments:
          type: array
          items:
            type: string
        Candidates:
          type: array
          items:
            type: string

    Site:
      type: object
      properties:
        Name:
          type: string
        Alias:
          type: string
        MRI_alias:
          type: string

    SitesResponse:
      type: object
      properties:
        Sites:
          type: array
          items:
            $ref: '#/components/schemas/Site'

    ErrorResponse:
      type: object
      properties:
        error:
          type: string

    SuccessResponse:
      type: object
      properties:
        message:
          type: string

    IdMapping:
      type: object
      properties:
        id:
          type: string
        mapping:
          type: string

    # ==========================================================================
    # INSTRUMENT MANAGER SCHEMAS (im3 — explicit parameters)
    # ==========================================================================
    InstrumentDataForm:
      type: object
      required:
        - action
        - format
        - data_file
      properties:
        action:
          type: string
          description: |
            Either CREATE_SESSIONS or VALIDATE_SESSIONS.
            VALIDATE_SESSIONS is used when all sessions already exist.
            Note: BIDS_TSV format cannot be combined with CREATE_SESSIONS.
          enum:
            - CREATE_SESSIONS
            - VALIDATE_SESSIONS
        format:
          type: string
          description: |
            Data format of the uploaded file.
            LORIS_CSV — standard LORIS CSV export
            REDCAP_CSV — REDCap CSV export (contains redcap_event_name column)
            BIDS_TSV — BIDS phenotype TSV (tab-separated)
            Client auto-detects: .tsv → BIDS_TSV, CSV with redcap_event_name → REDCAP_CSV, else → LORIS_CSV
          enum:
            - LORIS_CSV
            - REDCAP_CSV
            - BIDS_TSV
        strict:
          type: boolean
          default: false
          description: |
            Column validation mode.
            true — all template columns must be present in the uploaded file
            false — non-essential columns (e.g. _status, _date suffixes) may be missing
            Pipeline always sends false.
        instrument:
          type: string
          description: Set when a single instrument is selected
        multi-instrument:
          type: string
          description: Set when multiple instruments are selected (JSON array with format [{"value":"instrument1"},{"value":"instrument2"}])
        data_file:
          type: string
          description: CSV or TSV file with instrument data. Headers must match the headers of the set instrument(s).
          format: binary

    InstrumentManagerForm:
      type: object
      required:
        - install_file
        - instrument_type
      properties:
        install_file:
          type: string
          description: |
            Instrument definition file to install.
            Can be a LINST file (.linst), a BIDS JSON sidecar (.json),
            or a CSV file with one or more REDCap data dictionaries (.csv).
          format: binary
        instrument_type:
          type: string
          description: |
            Instrument type — must match the file extension.
            Client auto-detects: .csv → redcap, .linst → linst, .json → bids
          enum:
            - bids
            - linst
            - redcap

    # ==========================================================================
    # Script API Schemas
    # ==========================================================================
    BidsImportRequest:
      type: object
      required:
        - args
      properties:
        args:
          type: object
          required:
            - directory
          properties:
            directory:
              type: string
              description: BIDS directory to parse and insert into LORIS
            profile:
              type: string
              default: database_config.py
            type:
              type: string
              enum: [raw, derivative]
        flags:
          type: array
          items:
            type: string
            enum: [createcandidate, createsession, nobidsvalidation, nocopy, verbose]
        async:
          type: boolean
          default: false

    TarchiveLoaderRequest:
      type: object
      required:
        - args
      properties:
        args:
          type: object
          required:
            - tarchive
          properties:
            tarchive:
              type: string
              description: Full path to DICOM tarchive file
            profile:
              type: string
              default: prod
            upload_id:
              type: integer
            center_name:
              type: string
        flags:
          type: array
          items:
            type: string
            enum: [verbose, glob_location, reckless, force, no_jiv, is_hrrt, no_nifti, no_minc, bypass_extra_checks]
        async:
          type: boolean
          default: false

    ScriptSyncResponse:
      type: object
      properties:
        status:
          type: string
          enum: [success, error]
        code:
          type: integer
        command:
          type: string
        output:
          type: string
        warnings:
          type: array
          items:
            type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ScriptError'
        error_type:
          type: string

    ScriptAsyncResponse:
      type: object
      properties:
        status:
          type: string
        job_id:
          type: string
        pid:
          type: string
        script:
          type: string
        command:
          type: string
        log_file:
          type: string
        tail_cmd:
          type: string

    ScriptError:
      type: object
      properties:
        type:
          type: string
        message:
          type: string

security:
  - BearerAuth: []