Add ERROR value (issue #254)

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 filter out 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,15 +227,15 @@ paths:
               schema:
                 $ref: '#/components/schemas/BeaconAlleleResponse'
         '401':
-          description: >-
+          description: |
             Unauthorised (e.g. when an unauthenticated user tries to access a
             protected resource)
           content:
             application/json:
               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,41 +404,42 @@ 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:
           description: 'Assembly identifier (GRC notation, e.g. `GRCh37`).'
           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 filter out 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,20 +450,20 @@ 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.
           type: boolean
         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