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: [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. For example a sequence where the first and last bases are known, but the middle portion can exhibit countless variations of [ACGT], or the bases are unknown: ANNT the Ns can take take any form of [ACGT], which makes both ACCT and ATGT (or any other combination) viable sequences. in: query required: true schema: type: string pattern: '^([ACGTN]+)$' - name: alternateBases description: > The bases that appear instead of the reference bases. 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. For example a sequence where the first and last bases are known, but the middle portion can exhibit countless variations of [ACGT], or the bases are unknown: ANNT the Ns can take take any form of [ACGT], which makes both ACCT and ATGT (or any other combination) viable sequences. 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: '^([ACGTN]+)$' - 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 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: [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. For example a sequence where the first and last bases are known, but the middle portion can exhibit countless variations of [ACGT], or the bases are unknown: ANNT the Ns can take take any form of [ACGT], which makes both ACCT and ATGT (or any other combination) viable sequences. type: string pattern: '^([ACGTN]+)$' alternateBases: description: | The bases that appear instead of the reference bases. 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. For example a sequence where the first and last bases are known, but the middle portion can exhibit countless variations of [ACGT], or the bases are unknown: ANNT the Ns can take take any form of [ACGT], which makes both ACCT and ATGT (or any other combination) viable sequences. 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: '^([ACGTN]+)$' 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/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 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"