ssmp-schema.yml

openapi: "3.0.2"
info:
  title: One-Sided Matching Portal API
  version: "0.5"

paths:
  /variants/match:
    post:
      description: |
        Get variants and related patient information that match a query.
      operationId: getVariants
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Query"
      responses:
        "200":
          description: |
            Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryResponse"
components:
  schemas:
    Callset:
      description: |
        A callset for a variant
      type: object
      properties:
        callsetId:
          description: |
            The ID of the callset
          type: string
        IndividualId:
          description: |
            The ID of the individual
          type: string
        info:
          $ref: "#/components/schemas/CallsetInfo"
    CallsetInfo:
      description: |
        Additional metadata about the callset
      type: object
      example: "TBD"
      properties:
        AD:
          type: number
        DP:
          type: number
        GQ:
          type: number
        QUAL:
          type: number
        zygosity:
          type: string
    Disorder:
      description: |
        Description pending
      type: object
      properties:
        id:
          type: string
        label:
          type: string
    GeneFilters:
      properties:
        geneName:
          type: string
    Individual:
      properties:
        individualId:
          description: |
            Individual identifier (external accession or internal ID).
          type: string
          example: P0001
        familyId:
          type: string
        diseases:
          description: |
            List of disease(s) been diagnosed to the individual, defined by
            disease ICD10 code, optionally other disease ontology ID(s), age of
            onset, stage and the presence of family history.
          type: array
          items:
            allOf:
              - $ref: "https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_individual_schema.yaml#/components/schemas/Disease"
              - type: object
                properties:
                  description:
                    type: string
                  diseaseLabel:
                    type: string
        ethnicity:
          description: |
            Ethnic background of the individual. Value from NCIT Race ontology
            (NCIT:C17049), e.g. NCIT:C126531 (Latin American).
          type: string
          example: "NCIT:C126531"
        geographicOrigin:
          description: |
            Individual's country or region of origin (birthplace or residence
            place regardless of ethnic origin). Value from GAZ Geographic
            Location ontology (GAZ:00000448), e.g. GAZ:00002459 (United States
            of America).
          type: string
          example: "GAZ:00002459"
        info:
          $ref: "#/components/schemas/IndividualInfo"
        phenotypicFeatures:
          type: array
          items:
            allOf:
              - $ref: "https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_individual_schema.yaml#/components/schemas/PhenotypicFeature"
              - type: object
                properties:
                  phenotypeLabel:
                    description: |
                      todo
                    type: string
                    example: "Xxx"
                  observed:
                    description: |
                      Whether the phenotypic feature was observed or not.
                    type: boolean
        sex:
          description: |
            Sex of the individual.
            Value from NCIT General Qualifier (NCIT:C27993) ontology: UNKNOWN
            (not assessed or not available) (NCIT:C17998), FEMALE (NCIT:C46113),
            MALE, (NCIT:C46112) or OTHER SEX (NCIT:C45908).
          type: string
          enum:
            - NCIT:C17998
            - NCIT:C46113
            - NCIT:C46112
            - NCIT:C45908
          example: "NCIT:C17998"
    IndividualInfo:
      type: object
      description: |
        Additional metadata about the individual
      properties:
        diagnosis:
          type: string
        candidateGene:
          type: string
        classifications:
          type: string
        solved:
          type: string
        clinicalStatus:
          type: string
        disorders:
          type: array
          items:
            $ref: "#/components/schemas/Disorder"
    Query:
      description: |
        A request to the variants endpoint
      type: object
      properties:
        variant:
          $ref: "#/components/schemas/VariantFilters"
        gene:
          $ref: "#/components/schemas/GeneFilters"
    QueryResponse:
      description: |
        Description pending
      type: object
      required:
        - exists
        - results
      properties:
        exists:
          description: |
            Indicator of whether any variant was observed in any of the
            datasets queried. This should be non-null, unless there was an
            error, in which case `error` has to be non-null.
          type: boolean
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: "#/components/schemas/VariantResponseResults"
    Variant:
      allOf:
        - $ref: "https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_variant_identification_schema.yaml#/components/schemas/VariantIdentification"
        - type: object
          properties:
            callsets:
              type: array
              items:
                $ref: "#/components/schemas/Callset"
            chromosome:
              type: string
              example: "X"
    VariantFilters:
      description: |
        All the required fields to query any kind of variant (e.g. SNP, DUP,
        etc.).
      type: object
      properties:
        assemblyId:
          description: |
            Assembly identifier (GRC notation, e.g. GRCh37).
          type: string
          example: GRCh38
        maxFrequency:
          description: |
            Maximum Frequency of this allele (must not be larger than 0.05)
          type: number
    VariantResponseResults:
      description: |
        Description pending
      properties:
        variant:
          $ref: "#/components/schemas/Variant"
        individual:
          $ref: "#/components/schemas/Individual"
        contactInfo:
          type: string
          description: Contact information for the record owner
          example: "DrExample@example.ca"
        source:
          type: string
          description: Institution or other origin of this result
          example: "sickkids"