beacon.yaml

openapi: 3.0.0
servers: []
info:
  version: "1.1.0"
  title: GA4GH Beacon API Specification
  description: >-
    A Beacon is a web service for genetic data sharing that can be queried for information about specific alleles.
  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
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Beacon'
  /query:
    get:
      description: Get response to a beacon query for allele information.
      operationId: getBeaconAlleleResponse
      parameters:
        - name: referenceName
          description: 'Reference name (chromosome). Accepting values 1-22, X, Y, MT.'
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/Chromosome'
        - name: start
          description: |
            Precise start coordinate position, 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 "referenceBases"
            * start and end:
              - special use case for exactly determined structural changes
          in: query
          required: false
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: startMin
          description: |
            Minimum start coordinate
            * startMin + startMax + endMin + endMax
              - for querying imprecise positions (e.g. identifying all structural variants starting anywhere between startMin <-> startMax, and ending anywhere between endMin <-> endMax)
              - single or double sided precise matches can be achieved by setting startMin = startMax XOR endMin = endMax
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: startMax
          description: |
            Maximum start coordinate. See startMin.
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: end
          description: |
            Precise end coordinate (0-based, exclusive). See start.
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: endMin
          description: |
            Minimum end coordinate. See startMin.
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: endMax
          description: |
            Maximum end coordinate. See startMin.
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: referenceBases
          description: >
            Reference bases for this variant (starting from `start`). Accepted
            values: [ACGT]*

            When querying for variants without specific base alterations (e.g.
            imprecise structural variants with separate variant_type as well as
            start_min & end_min ... parameters), the use of a single "N" value
            is required.
          in: query
          required: true
          schema:
            type: string
            pattern: '^([ACGT]+|N)$'
        - name: alternateBases
          description: >
            The bases that appear instead of the reference bases. Accepted
            values: [ACGT]* or N.

            Symbolic ALT alleles (DEL, INS, DUP, INV, CNV, DUP:TANDEM, DEL:ME,
            INS:ME) will be represented in `variantType`.

            Optional: either `alternateBases` or `variantType` is required.
          in: query
          required: false
          schema:
            type: string
            pattern: '^([ACGT]+|N)$'
        - name: variantType
          description: |
            The `variantType` is used to denote e.g. structural variants.

            Examples:
            * DUP: duplication of sequence following `start`; not necessarily in
            situ
            * 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

            Optional: either `alternateBases` or `variantType` is required.
          in: query
          required: false
          schema:
            type: string
          examples:
            dup:
              value: DUP
              summary: duplication of sequence following `start`; not necessarily in
            del:
              value: DEL
              summary: deletion of sequence following `start`
        - name: assemblyId
          description: 'Assembly identifier (GRC notation, e.g. GRCh37).'
          in: query
          required: true
          schema:
            type: string
        - name: mateName
          description: |
            Second chromosome for fusion events. This can be
            * empty (no fusion or unknown partner)
            * identical to `referenceName` (e.g. one side of an inversion)
            * a different chromosome
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Chromosome'
        - name: datasetIds
          description: >-
            Identifiers of datasets, as defined in "BeaconDataset". If this
            field is null/not specified, all datasets should be queried.
          in: query
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: 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.
          in: query
          required: false
          schema:
            type: string
            enum:
              - ALL
              - HIT
              - MISS
              - NONE
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/BeaconAlleleResponse'
        '400':
          description: Bad request (e.g. missing mandatory parameter)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconAlleleResponse'
        '401':
          description: >-
            Unauthorised (e.g. when an unauthenticated user tries to access a
            protected resource)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconAlleleResponse'
        '403':
          description: >-
            Forbidden (e.g. the resource is protected for all users or the user
            is authenticated but s/he is not granted for this resource)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconAlleleResponse'
    post:
      description: Gets response to a beacon query for allele information.
      operationId: postBeaconAlleleResponse
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/BeaconAlleleResponse'
        '400':
          description: Bad request (e.g. missing mandatory parameter)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconAlleleResponse'
        '401':
          description: >-
            Unauthorised (e.g. when an unauthenticated user tries to access a
            protected resource)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconAlleleResponse'
        '403':
          description: >-
            Forbidden (e.g. the resource is protected for all users or the user
            is authenticated but s/he is not granted for this resource)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconAlleleResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeaconAlleleRequest'
        required: true
  /access_levels:
    get:
      description: Get information about the access levels applying to this Beacon. All the parameters described can be combined.
      operationId: getAccessLevels
      parameters:
        - name: fields
          description: 'Comma separated list of field(s) to get the access level.'
          in: query
          required: false
          schema:
            type: string
          example: 
            beaconOrganization, id
        - name: datasetIds
          description: 'Comma separated list of dataset(s) to get the access level.'
          in: query
          required: false
          schema:
            type: string
          example: dataset_1, dataset_2
        - name: level
          description: 'Access level of the field(s) to retrieve.'
          in: query
          required: false
          schema:
            type: string
            enum:
              - PUBLIC
              - REGISTERED
              - CONTROLLED
              - NOT_SUPPORTED
          example: CONTROLLED
        - name: includeFieldDetails
          description: ''
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: displayDatasetDifferences
          description: ''
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLevel'
        '400':
          description: Bad request (e.g. invalid level, field/dataset not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLevel'
components:
  schemas:
    Chromosome:
      description: 'Reference name (chromosome). Accepting values 1-22, X, Y.'
      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'
    Beacon:
      type: object
      required:
        - id
        - name
        - apiVersion
        - 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
        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'
        sampleAlleleRequests:
          description: >-
            Examples of interesting queries, e.g. a few queries demonstrating
            different responses.
          type: array
          items:
            $ref: '#/components/schemas/BeaconAlleleRequest'
        info:
          description: 'Additional unspecified metadata about the Beacon service.'
          type: object
          example:
            additionalInfoKey1: additionalInfoValue1
            additionalInfoKey2: [ additionalInfoValue2, additionalInfoValue3]
    BeaconAlleleRequest:
      description: Allele request as interpreted by the beacon.
      type: object
      required:
        - referenceName
        - referenceBases
        - assemblyId
      properties:
        referenceName:
          $ref: '#/components/schemas/Chromosome'
        start:
          description: |
            Precise start coordinate position, 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 "referenceBases"
            * start and end:
              - special use case for exactly determined structural changes
          type: integer
          format: int64
          minimum: 0
        end:
          description: Precise end coordinate (0-based, exclusive). See start.
          type: integer
        startMin:
          description: |
            Minimum start coordinate
            * startMin + startMax + endMin + endMax
              - for querying imprecise positions (e.g. identifying all structural variants starting anywhere between startMin <-> startMax, and ending anywhere between endMin <-> endMax)
              - single or double sided precise matches can be achieved by setting startMin = startMax XOR endMin = endMax
          type: integer
        startMax:
          description: Maximum start coordinate. See startMin.
          type: integer
        endMin:
          description: Minimum end coordinate. See startMin.
          type: integer
        endMax:
          description: Maximum end coordinate. See startMin.
          type: integer
        referenceBases:
          description: >
            Reference bases for this variant (starting from `start`). Accepted
            values: [ACGT]*
              When querying for variants without specific base alterations (e.g. imprecise structural variants with separate variant_type as well as start_min & end_min ... parameters), the use of a single "N" value is required.
          type: string
          pattern: '^([ACGT]+|N)$'
        alternateBases:
          description: >
            The bases that appear instead of the reference bases. Accepted
            values: [ACGT]* or N.

            Symbolic ALT alleles (DEL, INS, DUP, INV, CNV, DUP:TANDEM, DEL:ME,
            INS:ME) will be represented in `variantType`.

            Optional: either `alternateBases` or `variantType` is required.
          type: string
          pattern: '^([ACGT]+|N)$'
        variantType:
          description: |
            The `variantType` is used to denote e.g. structural variants.

            Examples:
            * DUP: duplication of sequence following `start`; not necessarily in
            situ
            * 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


            Optional: either `alternateBases` or `variantType` is required.
          type: string
        mateName:
          $ref: '#/components/schemas/Chromosome'
        assemblyId:
          description: 'Assembly identifier (GRC notation, e.g. `GRCh37`).'
          type: string
          example: GRCh38
        datasetIds:
          description: >-
            Identifiers of datasets, as defined in `BeaconDataset`. If this
            field is null/not specified, all datasets should be queried.
          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
    BeaconAlleleResponse:
      type: object
      required:
        - beaconId
      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
        exists:
          description: >-
            Indicator of whether the given allele 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
        alleleRequest:
          $ref: '#/components/schemas/BeaconAlleleRequest'
        datasetAlleleResponses:
          description: >-
            Indicator of whether the given allele was  observed in individual
            datasets. This should be non-null if `includeDatasetResponses` in
            the corresponding `BeaconAlleleRequest` is true, and null otherwise.
          type: array
          items:
            $ref: '#/components/schemas/BeaconDatasetAlleleResponse'
        error:
          $ref: '#/components/schemas/BeaconError'
        info:
          description: 'Additional unspecified metadata about the response or its content.'
          type: object
          example:
            additionalInfoKey: additionalInfoValue
        beaconHandover:
          type: array
          items:
            $ref: '#/components/schemas/Handover'
    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:
      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:
      type: object
      required:
        - datasetId
      properties:
        datasetId:
          type: string
          description: not provided
        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
        error:
          $ref: '#/components/schemas/BeaconError'
        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 variants matching the allele request in the dataset.
          minimum: 0
        callCount:
          type: integer
          format: int64
          description: Number of calls matching the allele request in the dataset.
          minimum: 0
        sampleCount:
          type: integer
          format: int64
          description: Number of samples matching the allele request in the dataset
          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:
        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
      required:
        - consentCodeDataUse
        - adamDataUse
      description: Data use conditions ruling this dataset.
      properties:
        consentCodeDataUse:
          $ref: >-
            https://raw.githubusercontent.com/ga4gh/ga4gh-consent-policy/806ea53cffacb2055c3639f0fc9783f0dcd8cb02/consent_code.yaml#/components/schemas/ConsentCodeDataUse
        adamDataUse:
          $ref: >-
            https://raw.githubusercontent.com/ga4gh/ADA-M/v1.0.1/adam.yaml#/components/schemas/Adam
    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"
    AccessLevel:
      type: object
      required:
        - beaconId
        - error
        - fields
        - datasets
      description: 'Get information about the access levels applying to this Beacon.'
      properties:
        beaconId:
          description: 'Identifier of the beacon, as defined in `Beacon`.'
          type: string
        error:
          $ref: '#/components/schemas/BeaconError'
        fields:
          description: 'Access level required for each of the fields in the Beacon spec.'
          type: object
          example:
            beacon: PUBLIC,
            beaconOrganization: {
              id: PUBLIC,
              name: PUBLIC
            }
        datasets:
          description: 'Access level required for each dataset in the Beacon. Only the global access level for the dataset and the differences with the default level for each field (if any) must be described here. '
          type: object
          example:
            dataset_1: CONTROLLED,
            dataset_2: {
              beaconDatasetAlleleResponse: {
                callCount: NOT_SUPPORTED
              }
            }