beacon.yaml

openapi: 3.0.2
servers: []
info:
  version: "2.0.0-draft.3"
  title: GA4GH Beacon API Specification
  description: >-
    A Beacon is a web service for genetic data sharing that can be queried for 
    information about variants, individuals, biosamples, and other entities.
  contact:
    email: beacon@ga4gh.org
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
externalDocs:
  description: |
    Beacon Project
  url: 'http://beacon-project.io/'
paths:
  /:
    get:
      description: |
        Get information about the beacon
      operationId: getBeacon
      tags:
        - Informational endpoints
      parameters:
        - name: requestedSchema
          description: 'Schema to be used to format the `result` field in the resposne. The response will use Beacon format.'
          in: query
          required: false
          schema:
            type: string
          example: |
            ga4gh-service-info-v1.0
        - name: model
          description: 'Equivalent to `/service-info`. The response will use the same format as the mentioned endpoint.'
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'ga4gh-service-info-v1.0'
      responses:
        '200':
          description: |
            Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InfoResponse'
                  - $ref: 'https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/develop/service-info.yaml#/components/schemas/Service'
  /info:
    get:
      description: |
        Get information about the beacon
      operationId: getBeaconInfo
      tags:
        - Informational endpoints
      parameters:
        - name: requestedSchema
          description: 'Schema to be used to format the `result` field in the resposne. The response will use Beacon format.'
          in: query
          required: false
          schema:
            type: string
          example: |
            ga4gh-service-info-v1.0
        - name: model
          description: 'Equivalent to `/service-info`. The response will use the same format as the mentioned endpoint.'
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'ga4gh-service-info-v1.0'
      responses:
        '200':
          description: |
            Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InfoResponse'
                  - $ref: 'https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/develop/service-info.yaml#/components/schemas/Service'
  /service-info:
    get:
      description: |
        Get information about the beacon using GA4GH ServiceInfo format
      operationId: getBeaconServiceInfo
      tags:
        - Informational endpoints
      responses:
        '200':
          description: |
            Successful operation
          content:
            application/json:
              schema:
                $ref: 'https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/develop/service-info.yaml#/components/schemas/Service'
  /datasets:
    get:
      description: |
        Get information about the datasets available in this Beacon.
      operationId: getDatasets
      tags:
      - Informational endpoints
      responses:
        '200':
          description: |
            Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResponse'
  /datasets/{id}/variant_interpretations:
    post:
      description: |
        Get the variants interpretations (`VariantInterpretationResponse`) by 
        dataset ID.
      operationId: getVariantsInterpretationsByDatasetId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Dataset ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /filtering_terms:
    get:
      description: |
        Filtering terms available in this Beacon.
      operationId: getFilteringTerms
      tags:
        - Informational endpoints
      responses:
        '200':
          description: |
            Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResponse'
  /individuals:
    post:
      description: |
        Get response to a beacon query for individual information 
        (`IndividualResponse`).
      operationId: postIndividualResponse
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /individuals/{id}:
    post:
      description: |
        Get an individual (`IndividualResponse`) by its Id.
      operationId: postIndividualById
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Individual ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /individuals/{id}/biosamples:
    post:
      description: |
        Get biosamples (`BiosampleResponse`) found in this individual.
      operationId: postBiosamplesByIndividualId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Individual ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /individuals/{id}/g_variants:
    post:
      description: |
        Get variants (`GenomicVariantResponse`) that have been stored for this 
        individual.
      operationId: postVariantsByIndividualId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Individual ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /individuals/{id}/cohorts:
    post:
      description: |
        Get cohort(s) (`CohortResponse`) of this individual.
      operationId: postCohortsByIndividual
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Individual ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /individuals/{id}/interactors:
    post:
      description: |
        Get interactor(s) (`InteractorResponse`) of this individual.
      operationId: postInteractorsByIndividual
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Individual ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /biosamples:
    post:
      description: |
        Get response to a beacon query for biosample information 
        (`BiosampleResponse`).
      operationId: postSampleResponse
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /biosamples/{id}:
    post:
      description: |
        Get a biosample (`BiosampleResponse`) by its Id.
      operationId: postBiosampleById
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Biosample ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /biosamples/{id}/individuals:
    post:
      description: |
        Get the individual information (`IndividualResponse`) to whom this 
        biosample belongs to.
      operationId: postInvidigualsByBiosampleId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Biosample ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /biosamples/{id}/g_variants:
    post:
      description: |
        Get the variants (`GenomicVariantResponse`) that have been stored for 
        this biosample.
      operationId: postVariantsByBiosampleId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Biosample ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /biosamples/{id}/runs:
    post:
      description: |
        Get the runs (`RunResponse`) that have been stored for this biosample.
      operationId: postRunsByBiosampleId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Biosample ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /biosamples/{id}/variants_in_sample:  
    post:
      description: |
        Get the variants in sample (`VariantInSampleResponse`) in which this 
        biosample is found.
      operationId: getVariantsInSampleByBiosampleId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Biosample ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /g_variants:
    post:
      description: |
        Any kind of genomic query that wants to query variants 
        (`GenomicVariantResponse`).
      operationId: postGenomicVariant
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /g_variants/{id}:
    post:
      description: |
        Get a variant (`GenomicVariantResponse`) by its Id.
      operationId: getGenomicVariantById
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Variant ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /g_variants/{id}/biosamples:
    post:
      description: |
        Get the biosamples (`BiosampleResponse`) where this variant is found.
      operationId: getBiosamplesByVariantId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Variant ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /g_variants/{id}/individuals:
    post:
      description: |
        Get the individuals (`IndividualResponse`) in which this variant is 
        found.
      operationId: getIndividualsByVariantId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Variant ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /g_variants/{id}/variants_in_sample:
    post:
      description: |
        Get the variants in sample (`VariantInSampleResponse`) in which this 
        variant is found.
      operationId: getVariantsInSampleByVariantId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Variant ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /g_variants/{id}/variant_interpretations:
    post:
      description: |
        Get the variants interpretations (`VariantInterpretationResponse`) by 
        variant ID.
      operationId: getVariantsInterpretationsByVariantId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Variant ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /runs:
    post:
      description: |
        Any kind of genomic query that wants to query runs (`RunResponse`).
      operationId: postRun
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /runs/{id}:
    post:
      description: |
        Get a run (`RunResponse`) by its `id`.
      operationId: postRunById
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Run ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /runs/{id}/biosamples:
    post:
      description: |
        Get the biosamples (`BiosampleResponse`) in which this run is found.
      operationId: postBiosamplesByRunId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Run ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /runs/{id}/analyses:
    post:
      description: |
        Get the analyses (`AnalysisResponse`) in which this run is found.
      operationId: postAnalysesByRunId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Run ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /analyses:
    post:
      description: |
        Any kind of query that wants to query analysis (`AnalysisResponse`).
      operationId: postAnalyses
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /analyses/{id}:
    post:
      description: |
        Get an analysis (`AnalysisResponse`) by its `id`.
      operationId: postAnalysisById
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Analysis ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /analyses/{id}/runs:
    post:
      description: |
        Get the runs (`RunResponse`) in which this analysis is found.
      operationId: postRunsByAnalysisId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Analysis ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /analyses/{id}/variants_in_sample:
    post:
      description: |
        Get the variants in sample (`VariantInSampleResponse`) in which this 
        analysis is found.
      operationId: getVariantsInSampleByAnalysisId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Analysis ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /variants_in_sample:
    post:
      description: |
        Any kind of query that wants to query variants in sample 
        (`VariantInSampleResponse`).
      operationId: postVariantsInSample
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /variants_interpretations:
    post:
      description: |
        Any kind of query that wants to query variant interpretations 
        (`VariantInterpretationResponse`).
      operationId: postVariantInterpretation
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /interactors:
    post:
      description: |
        Any kind of query that wants to query interactors (`InteractorResponse`).
      operationId: postInteractors
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /interactors/{id}:
    post:
      description: |
        Get an interactor (`InteractorResponse`) by its `id`.
      operationId: postInteractorById
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Interactor ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /interactors/{id}/individuals:
    post:
      description: |
        Get the individuals (`IndividualResponse`) in which this interactor is 
        found.
      operationId: postIndividualsByInteractorId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Interactor ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /cohorts:
    post:
      description: |
        Any kind of query that wants to query cohorts (`CohortResponse`).
      operationId: postCohorts
      tags:
        - Endpoints
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /cohorts/{id}:
    post:
      description: |
        Get a cohort (`CohortResponse`) by its `id`.
      operationId: postCohortById
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Cohort ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /cohorts/{id}/individuals:
    post:
      description: |
        Get the individuals (`IndividualResponse`) linked to this cohort.
      operationId: postIndividualsByCohortId
      tags:
        - Endpoints
      parameters:
        - name: id
          in: path
          description: Cohort ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    Success:
      description: |
        Successful operation.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/VariantInterpretationResponse'
              - $ref: '#/components/schemas/IndividualResponse'
              - $ref: '#/components/schemas/BiosampleResponse'
              - $ref: '#/components/schemas/GenomicVariantResponse'
              - $ref: '#/components/schemas/CohortResponse'
              - $ref: '#/components/schemas/RunResponse'
              - $ref: '#/components/schemas/VariantInSampleResponse'
              - $ref: '#/components/schemas/AnalysisResponse'
              - $ref: '#/components/schemas/InteractorResponse'
    BadRequest:
      description: |
        Bad request (e.g. missing mandatory parameter).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/VariantInterpretationResponse'
              - $ref: '#/components/schemas/IndividualResponse'
              - $ref: '#/components/schemas/BiosampleResponse'
              - $ref: '#/components/schemas/GenomicVariantResponse'
              - $ref: '#/components/schemas/CohortResponse'
              - $ref: '#/components/schemas/RunResponse'
              - $ref: '#/components/schemas/VariantInSampleResponse'
              - $ref: '#/components/schemas/AnalysisResponse'
              - $ref: '#/components/schemas/InteractorResponse'
    Unauthorized:
      description: |
        Unauthorised (e.g. when an unauthenticated user tries to access a 
        protected resource).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/VariantInterpretationResponse'
              - $ref: '#/components/schemas/IndividualResponse'
              - $ref: '#/components/schemas/BiosampleResponse'
              - $ref: '#/components/schemas/GenomicVariantResponse'
              - $ref: '#/components/schemas/CohortResponse'
              - $ref: '#/components/schemas/RunResponse'
              - $ref: '#/components/schemas/VariantInSampleResponse'
              - $ref: '#/components/schemas/AnalysisResponse'
              - $ref: '#/components/schemas/InteractorResponse'
    Forbidden:
      description: |
        Forbidden (e.g. the resource is protected for all users or the user
        is authenticated but they are not granted for this resource).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/VariantInterpretationResponse'
              - $ref: '#/components/schemas/IndividualResponse'
              - $ref: '#/components/schemas/BiosampleResponse'
              - $ref: '#/components/schemas/GenomicVariantResponse'
              - $ref: '#/components/schemas/CohortResponse'
              - $ref: '#/components/schemas/RunResponse'
              - $ref: '#/components/schemas/VariantInSampleResponse'
              - $ref: '#/components/schemas/AnalysisResponse'
              - $ref: '#/components/schemas/InteractorResponse'
  schemas:
    Chromosome:
      description: |
        Reference name (chromosome). Accepting values 1-22, X, Y, MT.
      type: string
      enum:
        - '1'
        - '2'
        - '3'
        - '4'
        - '5'
        - '6'
        - '7'
        - '8'
        - '9'
        - '10'
        - '11'
        - '12'
        - '13'
        - '14'
        - '15'
        - '16'
        - '17'
        - '18'
        - '19'
        - '20'
        - '21'
        - '22'
        - 'X'
        - 'Y'
        - 'MT'
    Assembly:
      description: |
        Assembly identifier (GRC notation, e.g. GRCh37).
      type: string
      example: GRCh38
    ReferenceBases:
      description: >
        Reference bases for this variant (starting from `start`).
        * Accepted values: [ACGTN]*.
        * N is a wildcard, that denotes the position of any base, and can be
        used as a standalone base of any type or within a partially known
        sequence. As example, a query of `ANNT` the Ns can take take any form of
        [ACGT] and will match `ANNT`, `ACNT`, `ACCT`, `ACGT` ... and so forth.
        * an *empty value* is used in the case of insertions with the maximally
        trimmed, inserted sequence being indicated in `AlternateBases`
      type: string
      pattern: '^([ACGTN]*)$'
    AlternateBases:
      description: |
        Alternate bases for this variant (starting from `start`).
        * Accepted values: [ACGTN]*.
        * N is a wildcard, that denotes the position of any base, and can be
        used as a standalone base of any type or within a partially known
        sequence. As example, a query of `ANNT` the Ns can take take any form of
        [ACGT] and will match `ANNT`, `ACNT`, `ACCT`, `ACGT` ... and so forth.
        * an *empty value* is used in the case of deletions with the maximally
        trimmed, deleted sequence being indicated in `ReferenceBases`
        * Categorical variant queries, e.g. such *not* being represented through
        sequence & position, make use of the `variantType` parameter.
        * either `alternateBases` or `variantType` is required.
      type: string
      pattern: '^([ACGTN]*)$'
    Filters:
      description: |
        Ontology based filters. CURIE syntax is encouraged to be used.
      type: array
      items:
        type: string
      example: 'BTO:0000199'
    CustomFilters:
      description: |
        Custom filters defined by this Beacon.
      type: array
      items:
        type: string
      example: 'mydict.aterm:avalue,mydict.aterm2:avalue2'

    RequestDatasets:
      description: >-
        Identifiers of datasets, as defined in `BeaconDataset`. If this
        field is null/not specified, all datasets should be queried.
      type: object
      properties:
        datasetIds:
          description: >
            List of dataset Ids to be searched.
          type: array
          items:
            type: string
        includeDatasetResponses:
          description: >-
            Indicator of whether responses for individual datasets
            (`DatasetAlleleResponses`) should be included in the response
            (`BeaconAlleleResponse`) to this request or not. If null (not
            specified), the default value of NONE is assumed.
          type: string
          enum:
            - ALL
            - HIT
            - MISS
            - NONE
    InfoRequestedSchemas:
      description: |
        Format of the response.
      type: object
      properties:
        Info:
          type: string
          example: 'beacon-info-v2.0.0-draft.3'
        Dataset:
          type: string
          example:
            'beacon-dataset-v2.0.0-draft.3'
        FilterTerm:
          type: string
          example:
            'beacon-filtering-term-v2.0.0-draft.3'
    RequestedSchemas:
      description: |
        Format of the responses and version of the Beacon handling this request.
      type: object
      properties:
        VariantIdentification:
          type: string
          example:
            ga4gh-variant-representation-v0.1
        VariantAnnotation:
          type: string
          example: beacon-variant-annotation-draft-2
        Individual:
          type: string
          example: ga4gh-phenopacket-individual-v0.1
        Biosample:
          type: string
          example: ga4gh-schemablocks-biosample-v0.1
        Run:
          type: string
          example: beacon-run-draft-3
        Analysis:
          type: string
          example: beacon-analysis-draft-2
        VariantInSample:
          type: string
          example: beacon-variant-in-sample-draft-3
        VariantInterpretation:
          type: string
          example: beacon-variant-interpretation-draft-2
        Interactor:
          type: string
          example: beacon-interactor-draft-2
        Cohort:
          type: string
          example: beacon-cohort-draft-3
    InfoRequestMeta:
      description: |
        Requested schemas and versions to be used in the response.
      type: object
      properties:
        requestedSchemas:
          $ref: '#/components/schemas/InfoRequestedSchemas'
        apiVersion:
          description: |
            Schemas & versions default for this Beacon version will be used to
            format the response.
          type: string
          example: 'v2.0'
    RequestMeta:
      description: |
        Requested schemas and versions to be used in the response.
      type: object
      properties:
        requestedSchemas:
          $ref: '#/components/schemas/RequestedSchemas'
        apiVersion:
          description: |
            Schemas & versions default for this Beacon version will be used to
            format the response.
          type: string
          example: 'v2.0'

    AlternativeSchema:
      description: |
        Alternative schema for describing this object.
      type: object

    Variant:
      description: |
        Variant description using either the default or an alternative schema.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_variant_identification_schema.yaml#/components/schemas/VariantIdentification'
        - $ref: '#/components/schemas/AlternativeSchema'
    VariantAnnotation:
      description: |
        Default schema for variant annotation
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_variant_annotations_schema.yaml#/components/schemas/VariantAnnotation'
        - $ref: '#/components/schemas/AlternativeSchema'
    VariantReponseResults:
      description: |
        TBD
      properties:
        variant:
          $ref: '#/components/schemas/Variant'
        variantAnnotations:
          $ref: '#/components/schemas/VariantAnnotation'
        variantHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        datasetAlleleRespones:
          type: array
          items:
            $ref: '#/components/schemas/BeaconDatasetAlleleResponse'

    Pagination:
      description: |
        Pagination to apply on the results.
      type: object
      properties:
        skip:
          description: |
            Number of pages to skip.
          type: integer
          minimum: 1
          default: 1
          example: 1
        limit:
          description: |
            Size of the page.

            Use  `0` to return all the results or the maximum allowed by the Beacon, if there is any.
          type: integer
          minimum: 0
          default: 10
          example: 10

    InfoRequest:
      description: |
        Request parameters for information endpoints.
      type: object
      required:
        - meta
      properties:
        meta:
          $ref: '#/components/schemas/InfoRequestMeta'
    Request:
      description: |
        Search for a genomic region
      type: object
      required:
        - meta
        - query
      properties:
        meta:
          $ref: '#/components/schemas/RequestMeta'
        query:
          $ref: '#/components/schemas/RequestQuery'
    RequestQuery:
      description: |
        TBD
      type: object
      properties:
        individual:
          $ref: '#/components/schemas/IndividualFields'
        biosample:
          $ref: '#/components/schemas/BiosampleFields'
        g_variant:
          $ref: '#/components/schemas/GenomicVariantFields'
        run:
          $ref: '#/components/schemas/RunFields'
        analysis:
          $ref: '#/components/schemas/AnalysisFields'
        interactor:
          $ref: '#/components/schemas/InteractorFields'
        variant_in_sample:
          $ref: '#/components/schemas/VariantInSampleFields'
        variant_interpretation:
          $ref: '#/components/schemas/VariantInterpretationFields'
        cohort:
          $ref: '#/components/schemas/CohortFields'
        datasets:
          $ref: '#/components/schemas/RequestDatasets'
        filters:
         $ref: '#/components/schemas/Filters'
        customFilters:
          $ref: '#/components/schemas/CustomFilters'
        pagination:
          $ref: '#/components/schemas/Pagination'
    GenomicVariantFields:
      description: |
        All the required fields to query any kind of variant (e.g. SNP, DUP,
        etc.).
      type: object
      properties:
        id:
          description: |
            Id of the variant to display.
          type: string
        assemblyId:
          $ref: '#/components/schemas/Assembly'
        referenceName:
          $ref: '#/components/schemas/Chromosome'
        start:
          description: |
            Precise or fuzzy start coordinate position(s), allele locus
            (0-based, inclusive).
            * `start` only:
              - for single positions, e.g. the start of a specified sequence
              alteration where the size is given through the specified
              `alternateBases`
              - typical use are queries for SNV and small InDels
              - the use of `start` without an `end` parameter requires the use
              of `alternateBases`

            * `start` and `end`:
              - for searching any variant falling fully or partially within the
              range between `start` and `end` (a.k.a. "range query")
              - additional use of `variantType` OR `alternateBases` can limit the
              scope of the query
              - by convention, partial overlaps of variants with the indicated
              genomic range are accepted; for specific overlap requirements the
              4-parammeter "Bracket Queries" should be employed
            * use of 2 values in both `start` and `end` for constructing a
            "Bracket Query":
              - can be used to match any contiguous genomic interval, e.g. for
              querying imprecise positions
                * identifying all structural variants starting between `start[0]`
                and `start[1]`, and ending between `end[0]` <-> `end[1]`
                * single or double sided precise matches can be achieved by
                setting `start[1]=start[0]+1` and `end[1]=end[0]+1`
          type: array
          items:
            type: integer
            format: int64
            minimum: 0
          minItems: 1
          maxItems: 2
        end:
          description: |
            Precise or bracketing the end of the variants of interest:
            * (0-based, exclusive) - see `start`
            * for bracket queries, provide 2 values (e.g. [111,222]).
          type: array
          items:
            type: integer
            format: int64
            minimum: 1
          minItems: 0
          maxItems: 2
        referenceBases:
          $ref: '#/components/schemas/ReferenceBases'
        alternateBases:
          $ref: '#/components/schemas/AlternateBases'
        variantType:
          description: |
            The `variantType` is used to query variants which are not defined
            through a sequenc of one or more bases using the `alternateBases`
            parameter. Examples here are e.g. structural variants:
            * DUP
              - increased allelic count of material from the genomic region
              between `start` and `end` positions
              - no assumption about the placement of the additional sequences is
              being made (i.e. no _in situ_ requirement as tandem duplications)
            * DEL: deletion of sequence following `start`
            * BND: breakend, i.e. termination of the allele at position
                  `start` or in the `startMin` => `startMax` interval, or fusion
                  of the sequence to distant partner
            Either `alternateBases` or `variantType` is required, with the
            exception of range queries (single `start` and `end` parameters).
          type: string
        mateName:
          $ref: '#/components/schemas/Chromosome'
    IndividualFields:
      description: |
        Fields to filter by individual.
      type: object
      properties:
        id:
          description: |
            Id of the individual to display.
          type: string
    BiosampleFields:
      description: |
        Fields to filter by biosample.
      type: object
      properties:
        id:
          description: |
            Id of the biosample to display.
          type: string
    RunFields:
      description: |
        Fields to filter by run.
      type: object
      properties:
        id:
          description: |
            Id of the run to display.
          type: string
        biosampleId:
          description: |
            `biosampleId` of the run to display.
          type: string
    AnalysisFields:
      description: |
        Fields to filter by analysis.
      type: object
      properties:
        id:
          description: |
            Id of the analysis to display.
          type: string
        runId:
          description: |
            `runId` of the analyses to display.
          type: string
    InteractorFields:
      description: |
        Fields to filter by interactor.
      type: object
      properties:
        id:
          description: |
            Id of the interactor to display.
          type: string
        individualId:
          description: |
            `individualId` of the interactor(s) to display.
          type: string
    VariantInSampleFields:
      description: |
        Fields to filter by variant in sample.
      type: object
      properties:
        variantId:
          description: |
            `variantId` of the variant(s) in sample to display.
          type: string
        analysisId:
          description: |
            `analysisId` of the variant(s) in sample to display.
          type: string
        biosampleId:
          description: |
            `biosampleId` of the variant(s) in sample to display.
          type: string
    VariantInterpretationFields:
      description: |
        Fields to filter by variant interpetation.
      type: object
      properties:
        variantId:
          description: |
            `variantId` of the variant(s) interpretation to display.
          type: string
        datasetId:
          description: |
            `datasetId` of the variant(s) interpretation to display.
          type: string
    CohortFields:
      description: |
        Fields to filter by cohort.
      type: object
      properties:
        id:
          description: |
            `id` of the cohort to display.
          type: string
        individualId:
          description: |
            `individualId` of the cohorts to display.
          type: string
    
    ResponseMeta:
      description: |
        Meta information about the reponse.
      type: object
      properties:
        beaconId:
          description: |
            Identifier of the beacon, as defined in `Beacon`.
          type: string
        apiVersion:
          description: >-
            Version of the API. If specified, the value must match `apiVersion`
            in Beacon
          type: string
        receivedRequest:
          $ref: '#/components/schemas/Request'
        returnedSchemas:
          $ref: '#/components/schemas/RequestedSchemas'
    InfoResponseMeta:
      description: |
        Meta information about the response.
      type: object
      properties:
        beaconId:
          description: |
            Identifier of the beacon, as defined in `Beacon`.
          type: string
        apiVersion:
          description: >-
            Version of the API. If specified, the value must match `apiVersion`
            in Beacon
          type: string
        receivedRequest:
          $ref: '#/components/schemas/InfoRequest'
        returnedSchemas:
          $ref: '#/components/schemas/InfoRequestedSchemas'

    GenomicVariantResponse:
      description: |
        Response of a genomic variant query
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/GenomicVariantResponseContent'

    GenomicVariantResponseContent:
      description: |
        TBD
      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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/VariantReponseResults'
        info:
          type: object
        resultsHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'

    # IndividualRequest:
    #   description: |
    #     TBD
    #   type: object
    #   required:
    #     - meta
    #     - query
    #   properties:
    #     meta:
    #       $ref: '#/components/schemas/RequestMeta'
    #     query:
    #       $ref: '#/components/schemas/RequestQuery'
    IndividualResponse:
      description: |
        Response of a query over individuals.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/IndividualResponseContent'
    IndividualResponseContent:
      description: |
        TBD
      type: object
      required:
        - exists
        - numTotalResults
        - results
      properties:
        exists:
          description: |
            Indicator of whether any individual 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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/IndividualResponseResults'
        info:
          type: object
        resultsHandover:
          $ref: '#/components/schemas/Handover'
        beaconHandover:
          $ref: '#/components/schemas/Handover'
    IndividualResponseResults:
      description: |
        Default schema for describing invididuals.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_individual_schema.yaml#/components/schemas/Individual'
        - $ref: '#/components/schemas/AlternativeSchema'

    # BiosampleRequest:
    #   description: |
    #     TBD
    #   type: object
    #   required:
    #     - meta
    #     - query
    #   properties:
    #     meta:
    #       $ref: '#/components/schemas/RequestMeta'
    #     query:
    #       $ref: '#/components/schemas/RequestQuery'
    BiosampleResponse:
      description: |
        Response of a query over biosamples.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/BiosampleResponseContent'
    BiosampleResponseContent:
      description: |
        TBD
      type: object
      required:
        - exists
        - results
      properties:
        exists:
          description: |
            Indicator of whether any biosample 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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/BiosampleResponseResults'
        info:
          type: object
        resultsHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    BiosampleResponseResults:
      description: |
        Default schema for describing biosamples.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_biosample_schema.yaml#/components/schemas/Biosample'
        - $ref: '#/components/schemas/AlternativeSchema'

    RunResponse:
      description: |
        Response of a query over runs.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/RunResponseContent'
    RunResponseContent:
      description: |
        TBD
      type: object
      required:
        - exists
        - results
      properties:
        exists:
          description: |
            Indicator of whether any run 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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/RunResponseResults'
        info:
          type: object
        resultsHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    RunResponseResults:
      description: |
        Default schema for describing runs.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_run_schema.yaml#/components/schemas/Run'
        - $ref: '#/components/schemas/AlternativeSchema'

    AnalysisResponse:
      description: |
        Response of a query over analyses.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/AnalysisResponseContent'
    AnalysisResponseContent:
      description: |
        TBD
      type: object
      required:
        - exists
        - results
      properties:
        exists:
          description: |
            Indicator of whether any analysis 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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisResponseResults'
        info:
          type: object
        resultsHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    AnalysisResponseResults:
      description: |
        Default schema for describing runs.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_analysis_schema.yaml#/components/schemas/Analysis'
        - $ref: '#/components/schemas/AlternativeSchema'

    VariantInSampleResponse:
      description: |
        Response of a query over variants in sample.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/VariantInSampleResponseContent'
    VariantInSampleResponseContent:
      description: |
        TBD
      type: object
      required:
        - exists
        - results
      properties:
        exists:
          description: |
            Indicator of whether any variant in sample 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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/VariantInSampleResponseResults'
        info:
          type: object
        resultsHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    VariantInSampleResponseResults:
      description: |
        Default schema for describing runs.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_variant_in_sample_schema.yaml#/components/schemas/VariantInSample'
        - $ref: '#/components/schemas/AlternativeSchema'

    VariantInterpretationResponse:
      description: |
        Response of a query over variants in sample.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/VariantInterpretationResponseContent'
    VariantInterpretationResponseContent:
      description: |
        TBD
      type: object
      required:
        - exists
        - results
      properties:
        exists:
          description: |
            Indicator of whether any variant in sample 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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/VariantInterpretationResponseResults'
        info:
          type: object
        resultsHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    VariantInterpretationResponseResults:
      description: |
        Default schema for describing runs.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_variant_interpretation_schema.yaml#/components/schemas/VariantInterpretation'
        - $ref: '#/components/schemas/AlternativeSchema'

    InteractorResponse:
      description: |
        Response of a query over variants in sample.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/InteractorResponseContent'
    InteractorResponseContent:
      description: |
        TBD
      type: object
      required:
        - exists
        - results
      properties:
        exists:
          description: |
            Indicator of whether any variant in sample 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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/InteractorResponseResults'
        info:
          type: object
        resultsHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    InteractorResponseResults:
      description: |
        Default schema for describing runs.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_interactor_schema.yaml#/components/schemas/Interactor'
        - $ref: '#/components/schemas/AlternativeSchema'
    CohortResponse:
      description: |
        Response of a query over cohorts.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        response:
          $ref: '#/components/schemas/CohortResponseContent'
    CohortResponseContent:
      description: |
        TBD
      type: object
      required:
        - exists
        - results
      properties:
        exists:
          description: |
            Indicator of whether any cohort 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
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/CohortResponseResults'
        info:
          type: object
        resultsHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    CohortResponseResults:
      description: |
        Default schema for describing runs.
      type: object
      oneOf:
        - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_cohort_schema.yaml#/components/schemas/Cohort'
        - $ref: '#/components/schemas/AlternativeSchema'
       
    InfoResponse:
      description: |
        Response of a query over Beacon info. 

        Use `InfoResponseContent` when querying the Beacon info endpoints, 
        `DatasetResponseContent` when querying the datasets endpoint, and 
        `FilteringTermResponseContent` when querying the filtering terms 
        endpoint.
      type: object
      required:
        - meta
        - response
      properties:
        meta:
          $ref: '#/components/schemas/InfoResponseMeta'
        response:
          oneOf:
            - $ref: '#/components/schemas/InfoResponseContent'
            - $ref: '#/components/schemas/DatasetResponseContent'
            - $ref: '#/components/schemas/FilteringTermResponseContent'
    InfoResponseContent:
      description: |
        TBD
      type: object
      required:
        - results
      properties:
        error:
          $ref: '#/components/schemas/BeaconError'
        results:
          type: array
          items:
            $ref: '#/components/schemas/InfoResponseResults'
        info:
          type: object
    InfoResponseResults:
      description: |
        Default schema for describing Beacon info.
      type: object
      oneOf:
        - $ref: '#/components/schemas/BeaconInfo'
        - $ref: '#/components/schemas/AlternativeSchema'

    DatasetResponseContent:
      description: |
        TBD
      type: object
      required:
        - results
      properties:
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/BeaconDataset' 
        info:
          type: object

    BeaconInfo:
      description: |
        Metadata describing a beacon instance.
      type: object
      required:
        - id
        - name
        - apiVersion
        - environment
        - organization
        - datasets
      properties:
        id:
          type: string
          description: |
            Unique identifier of the beacon. Use reverse domain name notation.
          example: org.ga4gh.beacon
        name:
          type: string
          description: |
            Name of the beacon.
        apiVersion:
          type: string
          description: Version of the API provided by the beacon.
          example: v0.3
        environment:
          type: string
          description: |
            Environment the service is running in. Use this to distinguish
            between production, development and testing/staging deployments.
          enum:
          - prod
          - test
          - dev
          - staging
          example: dev
        organization:
          $ref: '#/components/schemas/BeaconOrganization'
        description:
          type: string
          description: |
            Description of the beacon.
        version:
          type: string
          description: |
            Version of the beacon.
          example: v0.1
        welcomeUrl:
          type: string
          description: |
            URL to the welcome page for this beacon (RFC 3986 format).
          example: 'http://example.org/wiki/Main_Page'
        alternativeUrl:
          type: string
          description: >-
            Alternative URL to the API, e.g. a restricted version of this beacon
            (RFC 3986 format).
          example: 'http://example.org/wiki/Main_Page'
        createDateTime:
          type: string
          description: |
            The time the beacon was created (ISO 8601 format).
          example: '2012-07-19 or 2017-01-17T20:33:40Z'
        updateDateTime:
          type: string
          description: |
            The time the beacon was updated in (ISO 8601 format).
          example: '2012-07-19 or 2017-01-17T20:33:40Z'
        datasets:
          description: >-
            Dataset(s) served by the beacon.
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/BeaconDataset'
        info:
          description: |
            Additional unspecified metadata about the Beacon service.
          type: object
          example:
            additionalInfoKey1: additionalInfoValue1
            additionalInfoKey2:
                - additionalInfoValue2
                - additionalInfoValue3
    BeaconOrganization:
      description: |
        Organization owning the beacon.
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: |
            Unique identifier of the organization.
        name:
          type: string
          description: |
            Name of the organization.
        description:
          type: string
          description: |
            Description of the organization.
        address:
          type: string
          description: |
            Address of the organization.
        welcomeUrl:
          type: string
          description: |
            URL of the website of the organization (RFC 3986 format).
        contactUrl:
          type: string
          description: >-
            URL with the contact for the beacon operator/maintainer, e.g. link
            to a contact form (RFC 3986 format) or an email (RFC 2368 format).
        logoUrl:
          type: string
          description: >-
            URL to the logo (PNG/JPG/SVG format) of the organization (RFC 3986
            format).
        info:
          description: |
            Additional unspecified metadata about the host Organization.
          type: object
          example:
            additionalInfoKey: additionalInfoValue
    BeaconDataset:
      description: |
        A dataset available in the beacon.
      type: object
      required:
        - id
        - name
        - assemblyId
        - createDateTime
        - updateDateTime
      properties:
        id:
          type: string
          description: |
            Unique identifier of the dataset.
        name:
          type: string
          description: |
            Name of the dataset.
        description:
          type: string
          description: |
            Description of the dataset.
        assemblyId:
          description: |
            Assembly identifier (GRC notation, e.g. `GRCh37`).
          type: string
          example: GRCh38
        createDateTime:
          type: string
          description: |
            The time the dataset was created (ISO 8601 format).
          example: '2012-07-29 or 2017-01-17T20:33:40Z'
        updateDateTime:
          type: string
          description: |
            The time the dataset was updated in (ISO 8601 format).
          example: '2012-07-19 or 2017-01-17T20:33:40Z'
        version:
          type: string
          description: |
            Version of the dataset.
        variantCount:
          type: integer
          format: int64
          description: |
            Total number of variants in the dataset.
          minimum: 0
        callCount:
          type: integer
          format: int64
          description: |
            Total number of calls in the dataset.
          minimum: 0
        sampleCount:
          type: integer
          format: int64
          description: |
            Total number of samples in the dataset.
          minimum: 0
        externalUrl:
          type: string
          description: >-
            URL to an external system providing more dataset information (RFC
            3986 format).
          example: 'http://example.org/wiki/Main_Page'
        info:
          description: |
            Additional unspecified metadata about the dataset.
          type: object
          example:
            additionalInfoKey1:
              - additionalInfoValue1
              - additionalInfoValue2]
            additionalInfoKey2: additionalInfoValue3
        dataUseConditions:
          $ref: '#/components/schemas/DataUseConditions'
    BeaconDatasetAlleleResponse:
      description: |
        Response containing information about an allele in a particular dataset.
      type: object
      required:
        - datasetId
      properties:
        datasetId:
          type: string
          description: |
            `id` of the dataset.
        exists:
          description: >-
            Indicator of whether the given allele was observed in the dataset.
            This should be non-null, unless there was an error, in which case
            `error` has to be non-null.
          type: boolean
        frequency:
          type: number
          description: |
            Frequency of this allele in the dataset. Between 0 and 1, inclusive.
          minimum: 0
          maximum: 1
        variantCount:
          type: integer
          format: int64
          description: |
            Number of times the requested allele has been observed in the
            dataset.
          minimum: 0
        callCount:
          type: integer
          format: int64
          description: |
            Total number of calls in the dataset. Missing calls are not
            included.
          minimum: 0
        sampleCount:
          type: integer
          format: int64
          description: |
            Number of samples in the dataset where the requested allele is
            found.
          minimum: 0
        note:
          type: string
          description: |
            Additional note or description of the response.
        externalUrl:
          type: string
          description: >-
            URL to an external system, such as a secured beacon or a system
            providing more information about a given allele (RFC 3986 format).
        info:
          description: |
            Additional unspecified metadata about the dataset response or its
            content.
          type: object
          example:
            additionalInfoKey1:
              - additionalInfoValue1
              - additionalInfoValue2]
            additionalInfoKey2: additionalInfoValue3
        datasetHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    BeaconError:
      description: >-
        Beacon-specific error. This should be non-null in exceptional situations
        only, in which case `exists` has to be null.
      type: object
      required:
        - errorCode
      properties:
        errorCode:
          type: integer
          format: int32
          example: 'same as HTTP status code'
        errorMessage:
          type: string
    DataUseConditions:
      type: object
      description: |
        Data use conditions ruling this dataset.
      properties:
        consentCodeDataUse:
          $ref: >-
            https://raw.githubusercontent.com/ga4gh/ga4gh-consent-policy/v1.1.0/consent_code.yaml#/components/schemas/ConsentCodeDataUse
        adamDataUse:
          $ref: >-
            https://raw.githubusercontent.com/ga4gh/ADA-M/v1.0.1/adam.yaml#/components/schemas/Adam
        duoDataUse:
          type: array
          items:
            $ref: '#/components/schemas/DUODataUse'
    Handover:
      type: object
      required:
        - handoverType
        - url
      properties:
        handoverType:
          $ref: '#/components/schemas/HandoverType'
        note:
          type: string
          description: |
            An optional text including considerations on the handover link
            provided.
          example: |
            This handover link provides access to a summarized VCF. To access
            the VCF containing the details for each sample filling an
            application is required. See Beacon contact information details.
        url:
          type: string
          description: |
            URL endpoint to where the handover process could progress (in RFC
            3986 format).
          example: |
            "https://api.mygenomeservice.org/handover/9dcc48d7-fc88-11e8-9110-b0c592dbf8c0/"
    HandoverType:
      type: object
      required:
        - id
      description: |
            Handover type, as an Ontology_term object with CURIE syntax for the
            `id` value.
      properties:
        id:
          type: string
          description: >-
            Use `CUSTOM` for the `id` when no ontology is available.
          default: CUSTOM
          example: "EFO:0004157"
        label:
          type: string
          description: >-
            This would be the "preferred Label" in the case of an ontology term.
          default: null
          example: "BAM format"

    FilteringTermResponseContent:
      type: object
      description: |
        Filtering terms available in this Beacon.
      required:
        - results
      properties:
        error:
          $ref: '#/components/schemas/BeaconError'
        numTotalResults:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/FilteringTerm'
        info:
          type: object
    FilteringTerm:
      type: object
      description: |
        Entities can be filtered using this term.
      required:
        - id
      properties:
        id:
          description: |
            CURIE syntax.
          type: string
          example: 'NCIT:C102872'
        label:
          description: |
            This would be the "preferred Label" in the case of an ontology term.
          type: string
          example: 'Pharyngeal squamous cell carcinoma'

    OntologyTerm:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        label:
          type: string
    DUODataUse:
      allOf:
        - description: |
            TBD
        - $ref: '#/components/schemas/OntologyTerm'
        - type: object
          required:
            - id
            - version
          properties:
            version:
              type: string
              example: '17-07-2016'
            modifiers:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/OntologyTerm'
                  - example:
                      - id: 'EFO:0001645'
                      - id: 'EFO:0001655'
        - example:
            - id: 'DUO:0000007'
            - label: 'disease specific research'
            - version: '17-07-2016'