diff --git a/beacon.yaml b/beacon.yaml index cd5509b9..1c015f0d 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -95,7 +95,7 @@ paths: format: int64 minimum: 0 - name: referenceBases - description: > + description: | Reference bases for this variant (starting from `start`). Accepted values: [ACGT]* @@ -109,7 +109,7 @@ paths: type: string pattern: '^([ACGT]+|N)$' - name: alternateBases - description: > + description: | The bases that appear instead of the reference bases. Accepted values: [ACGT]* or N. @@ -123,7 +123,7 @@ paths: type: string pattern: '^([ACGT]+|N)$' - name: variantType - description: > + description: | The `variantType` is used to denote e.g. structural variants. Examples: @@ -150,7 +150,7 @@ paths: schema: type: string - name: datasetIds - description: >- + description: | Identifiers of datasets, as defined in "BeaconDataset". If this field is null/not specified, all datasets should be queried. in: query @@ -161,11 +161,13 @@ paths: items: type: string - name: includeDatasetResponses - description: > + description: | Indicator of whether responses for individual datasets (datasetAlleleResponses) should be included in the response (BeaconAlleleResponse) to this request or not. + Use ERROR to return the datasets which return an error. + If null (not specified), the default value of NONE is assumed. in: query required: false @@ -175,6 +177,7 @@ paths: - ALL - HIT - MISS + - ERROR - NONE responses: '200': @@ -199,7 +202,7 @@ paths: schema: $ref: '#/components/schemas/BeaconAlleleResponse' '403': - description: >- + 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: @@ -224,7 +227,7 @@ paths: schema: $ref: '#/components/schemas/BeaconAlleleResponse' '401': - description: >- + description: | Unauthorised (e.g. when an unauthenticated user tries to access a protected resource) content: @@ -232,7 +235,7 @@ paths: schema: $ref: '#/components/schemas/BeaconAlleleResponse' '403': - description: >- + 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: @@ -311,7 +314,7 @@ components: example: 'http://example.org/wiki/Main_Page' alternativeUrl: type: string - description: >- + description: | Alternative URL to the API, e.g. a restricted version of this beacon (RFC 3986 format). example: 'http://example.org/wiki/Main_Page' @@ -324,14 +327,14 @@ components: description: The time the beacon was updated in (ISO 8601 format). example: '2012-07-19 or 2017-01-17T20:33:40Z' datasets: - description: >- + description: | Dataset(s) served by the beacon. minItems: 1 type: array items: $ref: '#/components/schemas/BeaconDataset' sampleAlleleRequests: - description: >- + description: | Examples of interesting queries, e.g. a few queries demonstrating different responses. type: array @@ -385,16 +388,14 @@ components: description: Maximum end coordinate. See startMin. type: integer referenceBases: - description: > - Reference bases for this variant (starting from `start`). Accepted - values: [ACGT]* + 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. + 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`. @@ -403,17 +404,14 @@ components: type: string pattern: '^([ACGT]+|N)$' variantType: - description: > + 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: @@ -421,23 +419,27 @@ components: type: string example: GRCh38 datasetIds: - description: >- + 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: >- + 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. + (BeaconAlleleResponse) to this request or not. + + Use ERROR to return the datasets which return an error. + + If null (not specified), the default value of NONE is assumed. type: string enum: - ALL - HIT - MISS + - ERROR - NONE BeaconAlleleResponse: type: object @@ -448,12 +450,12 @@ components: description: 'Identifier of the beacon, as defined in `Beacon`.' type: string apiVersion: - description: >- + description: | Version of the API. If specified, the value must match `apiVersion` in Beacon type: string exists: - description: >- + 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. @@ -461,7 +463,7 @@ components: alleleRequest: $ref: '#/components/schemas/BeaconAlleleRequest' datasetAlleleResponses: - description: >- + 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. @@ -494,12 +496,12 @@ components: description: URL of the website of the organization (RFC 3986 format). contactUrl: type: string - description: >- + 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: >- + description: | URL to the logo (PNG/JPG format) of the organization (RFC 3986 format). info: @@ -557,7 +559,7 @@ components: minimum: 0 externalUrl: type: string - description: >- + description: | URL to an external system providing more dataset information (RFC 3986 format). example: 'http://example.org/wiki/Main_Page' @@ -578,7 +580,7 @@ components: type: string description: not provided exists: - description: >- + 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. @@ -610,7 +612,7 @@ components: description: Additional note or description of the response. externalUrl: type: string - description: >- + 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: @@ -619,7 +621,7 @@ components: example: additionalInfoKey: additionalInfoValue BeaconError: - description: >- + description: | Beacon-specific error. This should be non-null in exceptional situations only, in which case `exists` has to be null. type: object