curation-swagger-spec.yaml

---
swagger: '2.0'

# Document metadata
info:
  version: "1.0.0"
  title: Haplotype Frequency Curation Service
  description: Allows to store and return haplotype frequency data

# Describe paths here
paths:
  /hfc/{submissionId}:
    get:
      description: Returns a submission of haplotypes
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id that the haplotype frequencies were submitted under
      responses:
        200:
          description: Returns the data set containing all references
          schema:
            $ref: '#/definitions/HFCurationResponse'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/{submissionId}/haplotypes:
    get:
      description: Returns the list of haplotypes attached to the given submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        200:
          description: Returns the haplotype frequency data
          schema:
            $ref: '#/definitions/HaplotypeFrequencyData'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/{submissionId}/cohort:
    get:
      description: Returns the list of haplotypes attached to the given submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        200:
          description: Returns the cohort data and genotypes if available
          schema:
            $ref: '#/definitions/CohortData'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/{submissionId}/population:
    get:
      description: Returns the population of the given submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        200:
          description: Returns the population
          schema:
            $ref: '#/definitions/PopulationData'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/{submissionId}/labels:
    get:
      description: Returns the labels associated to the submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        200:
          description: Returns label set
          schema:
            $ref: '#/definitions/LabelData'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/{submissionId}/scope:
    get:
      description: Returns the scope of the genotypes used for creating the submitted haplotypes
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        200:
          description: Returns scope set
          schema:
            $ref: '#/definitions/ScopeData'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc:
    post:
      description: |
        Storing of a new Haplotype Frequency set.
      parameters:
        - name: HFCurationRequest
          in: body
          description: Haplotype Frequency Curation Data
          required: true
          schema:
            $ref:  '#/definitions/HFCurationRequest'
      responses:
        # Response code
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/HFCurationResponse'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
    get:
      description: |
        Gets a list of all submission data sets
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/HFCurationListResponse'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/population:
    get:
      description: |
        Get a list of all populations
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/PopulationResponse'
        500:
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/population/{populationId}:
    get:
      description: Returns a population with its attached submissions
      parameters:
        - name: populationId
          in: path
          type: integer
          format: int64
          required: true
          description: The population id
      responses:
        200:
          description: Returns the population including all attached submissions
          schema:
            $ref: '#/definitions/PopulationSubmissionResponse'
        500:
          $ref: '#/responses/Standard500ErrorResponse'

definitions:
  HFCurationListResponse:
    title: HFCurationListResponse
    type: object
    properties:
      HFCurationResponses:
        type: array
        items:
          $ref: '#/definitions/HFCurationResponse'
  HFCurationResponse:
    title: HFCurationResponse
    type: object
    required:
      - SubmissionID
    properties:
      SubmissionID:
        type: integer
        format: int64
        description: Reference to a submission
      PopulationID:
        type: integer
        format: int64
        description: Reference to a population
      CohortID:
        type: integer
        format: "int64"
        description: References a cohort
      MethodSetID:
        type: integer
        format: int64
        description: References a method set
      LabelID:
        type: integer
        format: int64
        description: References a label
      HaplotypeListID:
        type: integer
        format: int64
        description: References a haplotype list
      ScopeID:
        type: integer
        format: int64
        description: References a scope
      AccessID:
        type: integer
        format: "int64"
        description: References a access controls

  PopulationSubmissionResponse:
    title: PopulationSubmissionResponse
    type: object
    properties:
      PopulationSubmissionList:
        type: array
        description: List of populations together with all attached submissions
        items:
          $ref: '#/definitions/PopulationSubmissionData'

  PopulationResponse:
    title: PopulationResponse
    type: object
    properties:
      PopulationList:
        type: array
        description: List of populations
        items:
          $ref: '#/definitions/PopulationData'

  HFCurationRequest:
    title: HFCurationRequest
    type: object
    required:
      - PopulationID
    properties:
      PopulationID:
        type: integer
        format: int64
        description: Reference to a population
      PopulationData:
        $ref: '#/definitions/PopulationData'
      CohortID:
        type: integer
        format: int64
        description: Cohort ID or genotype list
      CohortData:
        $ref: '#/definitions/CohortData'
      MethodSetID:
        type: integer
        format: int64
        description: References a method set
      MethodData:
        $ref: '#/definitions/MethodData'
      LabelID:
        type: integer
        format: int64
        description: References a label
      LabelData:
        $ref: '#/definitions/LabelData'
      HaplotypeFrequencyDataID:
        type: string
        description: References a haplotype list
      HaplotypeFrequencyData:
        $ref: '#/definitions/HaplotypeFrequencyData'
      ScopeID:
        type: integer
        format: int64
        description: References a scope
      ScopeData:
        $ref: '#/definitions/ScopeData'
      AccessID:
        type: integer
        format: "int64"
        description: References a access controls
      AccessData:
        $ref: '#/definitions/AccessData'

  AccessData:
    title: AccessData
    type: object
    required:
      - typeOfAccess
    properties:
      typeOfAccess:
        type: string
        description: There will be a default license if one is not provided
    
  HaplotypeFrequencyData:
    title: HaplotypeFrequencyData
    type: object
    required:
      - HaplotypeFrequencyList
      - License
    properties:
      License:
        $ref: '#/definitions/License'
      ResolutionData:
        $ref: '#/definitions/ResolutionData'
      HaplotypeFrequencyList:
        title: HaplotypeFrequencyList
        type: array
        description: List of HaplotypeFrequencys
        items:
          $ref: '#/definitions/HaplotypeFrequency'
      QualityList:
        type: array
        description: List of Quality
        items:
          $ref: '#/definitions/Quality'


  HaplotypeFrequency:
    title: HaplotypeFrequency
    type: object
    required:
      - haplotypeString
      - frequency
    properties:
      haplotypeString:
        type: string #glstring
        description: GL string describing the haplotype
      frequency: 
        type: number
        format: double
        description: value of frequency
      FrequencyErrorList:
        type: array
        description: List of frequency errors
        items:
          $ref: '#/definitions/FrequencyError'

  Quality:
    title: Quality
    type: object
    required:
      - value
      - typeOfQuality
    properties:
      value:
        type:  number
        format: double
        description: value of quality
      typeOfQuality: 
        type: string
        description: type of quality
        enum:
        - DIV_LAMBDA
        - DIV_50         
        - DIV_50_REL
        - SAM_SIZE
        - SAM_POP
        - DIV_PGD
        - DIV_HEAVY_TAIL
        - RES_TRS_COUNT
        - RES_TRS
        - RES_SHARE_AMBIG
        - RES_MISS_LOCI
        - DEV_HWE
        - ERR_STD
        - ERR_SAMP_80_100
        - SUM_FREQ_GAP
        - ERR_OFFSET
        - LD_MEASURE
        - KFOLD_IMPUTE
        - KFOLD_PRED_ACTUAL
        - KFOLD_N

  ScopeData:
    title: ScopeData
    type: object
    required:
      - ScopeElement
    properties:
      ScopeElement:
        title: ScopeElement
        type: array
        description: Additional Information on genotype
        items:
          $ref: '#/definitions/ScopeElement'

  PopulationSubmissionData:
    title: PopulationSubmissionData
    description: Contains all submissions for a population
    type: object
    required:
      - population
    properties: #this is just a placeholder for now
      population:
        $ref: '#/definitions/PopulationData'
      submissions:
        title: attached submissions
        type: array
        description: submissions that describe the population
        items:
          type: integer
          format: int64

  PopulationData:
    title: PopulationData
    type: object
    required:
      - name
    properties: #this is just a placeholder for now
      id:
        title: id
        type: integer
        format: int64
        description: id of the population
      name:
        title: Name
        type: string
        description: Name of the population

  ScopeElement:
    title: ScopeElement
    type: object
    properties:
      name:
        type: string 
        description: label name
      freeName:
        type: string 
        description: label name
      typeOfScope: 
        type: string
        description: type of label
        enum:
        - gene
        - feature

  MethodData:
    title: MethodData
    type: object
    required:
      - MethodList
    properties:
      MethodList:
        $ref: '#/definitions/MethodList'

  MethodList:
    type: object
    title: MethodList
    properties:
      Method:
        title: Method
        type: array
        description: list of methods
        items:
          $ref: '#/definitions/Method'


  LabelData:
    title: LabelData
    type: object
    required:
      - LabelList
    properties:
      LabelList:
        $ref: '#/definitions/LabelList'

  LabelList:
    type: object
    description: List of labels
    properties:
      Label:
        type: array
        items:
          $ref: '#/definitions/Label'

  Label:
    title: Label
    type: object
    description: List of Genotypes
    properties:
      value:
        type: string 
        description: label name
      typeOfLabel: 
        type: string
        description: type of label

  CohortData:
    title: CohortData #this will also contain meta information about the sample of the population
    type: object
    required:
      - GenotypeList
    properties:
      GenotypeList:
        $ref: '#/definitions/GenotypeList'

  GenotypeList:
    title: GenotypeList
    type: object
    description: List of Genotypes
    properties:
      License:
        $ref: '#/definitions/License'
      Genotype:
        title: Genotype
        type: array
        description: Additional Information on genotype
        items:
          $ref: '#/definitions/Genotype'
  
  Genotype:
    title: Genotype
    type: object
    required:
      - genotypeString
    properties:
      genotypeString:
        type: string
        description: GL string of the genotype
      genotypingMethods:
        title: GenotypingMethods
        type: array
        description: Additional Information on genotype
        items:
          $ref: '#/definitions/GenotypeMethod'

  GenotypeMethod:
    title: GenotypeMethod
    type: object
    description: GenotypeMethod Record
    properties:
      methodLabel:
        type: string
        description: Type of method label
        enum:
        - TYPING_METHOD
        - TYPING_REF
        - TYPING_DATE
        - TYPING_IMGT_VER
        - MIRING_REF
      methodValue:
        type: string
        description: Value of method
      methodComment:
        type: string
        description: Comment on method
      methodReference:
        type: string
        description: To be used to refer to an external source

  License:
    title: License
    type: object
    description: License models, there will be a default license if one is not provided
    required:
      - typeOfLicense
    properties:
      typeOfLicense:
        type: string
        description: Type of creative commons license
        enum:
        - CC0
        - by
        - by-sa
        - by-nd
        - by-nc
        - by-nc-sa
        - by-nc-nd

  Method:
    title: Method
    type: object
    description: Method Record
    properties:
      typeOfMethod:
        type: string
        description: Type of method label
        enum:
        - EM_ALGORITHM
        - EM_VERSION
        - EM_ALG_REF
        - MAC_SERVICE
        - MAC_SER_REF
        - MAC_VERSION
        - ARS_SERVICE
        - ARS_SERV_REF
        - ARS_VERSION
        - HWE_METHOD
        - HWE_REF
        - LD_METHOD
        - LD_METHOD_REF
      methodValue:
        type: string
        description: Value of method
      methodComment:
        type: string
        description: Comment on method
      methodReference:
        type: string
        description: To be used to refer to an external source

  ResolutionData:
    title: ResolutionData
    type: array
    description: List of Method
    items:
      $ref: '#/definitions/ResolutionInfo'
      
  ResolutionInfo:
    title: ResolutionInfo
    properties:
     scopeElement:
       type: string
     resolution:
       type: string
       description: resolution of the data
       enum:
        - G
        - P
        - gNMDP
        - gDKMS
        - 2-Field
        - 4-Field
        - 6-Field
        - 8-Field
        - Serology

  FrequencyError:
    title: FrequencyError
    properties:
     value:
       type: number
       format: double
       description: value of error
     typeOfError:
       type: string
       description: type of error


  Error:
    properties:
     code:
       type: string
     message:
       type: string

responses:
  Standard500ErrorResponse:
    description: An unexpected error ocurred
    schema:
      $ref: '#/definitions/Error'