openapi: 3.0.0 servers: [] info: version: "1.0.1" 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` 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: 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 structured metadata, key-value pairs.' type: array items: $ref: '#/components/schemas/KeyValuePair' 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` Optional: either `alternateBases` or `variantType` is required. type: string 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' 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 format) of the organization (RFC 3986 format). info: description: 'Additional structured metadata, key-value pairs.' type: array items: $ref: '#/components/schemas/KeyValuePair' 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 structured metadata, key-value pairs.' type: array items: $ref: '#/components/schemas/KeyValuePair' 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 structured metadata, key-value pairs.' type: array items: $ref: '#/components/schemas/KeyValuePair' 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 KeyValuePair: type: object required: - key - value properties: key: type: string value: 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: '#/components/schemas/AdamDataUse' AdamDataUse: type: object required: - header - profile - terms - metaConditions properties: header: $ref: >- https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Header profile: $ref: >- https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Profile terms: $ref: >- https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Terms metaConditions: $ref: >- https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/MetaConditions