BeaconAlleleRequest

Still prototyping:
* adding variant query schemas
* testing parameter prototypes to resolve ambiguities such as polymorphic positional parameters (1 or 2 start values etc.)

schemas/BeaconAlleleRequest.yaml

@@ -0,0 +1,39 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://genomebeacons.org/schemas/beacon/BeaconAlleleRequest/v1.0.0
+title: BeaconAlleleRequest
+description: >-
+  `BeaconAlleleRequest` represents the "classic" Beacon request type where
+  a genomic sequence variation is queried by position and sequence (as well as
+  optional reference sequence).
+  Beacon version: v1.0
+  Future considerations: There are some inherited ambiguities
+  * `assemblyId` and `referenceName` should be deprectated in favour of a versioned
+    `sequenceId`
+  * in alignment with VRS future versions should abandon the concept of a reference
+    sequence
+  * the use of `variantType` is not allowed (or should be ignored) when providing
+    an explicit sequence
+type: object
+required:
+  - referenceName
+  - start
+  - alternateBases
+additionalProperties: false
+
+properties:
+  referenceName:
+    $ref: variantRequestParameters.yaml#/$defs/referenceName
+  start:
+    $ref: variantRequestParameters.yaml#/$defs/sequencePosition
+  alternateBases:
+    $ref: variantRequestParameters.yaml#/$defs/sequence
+  referenceBases:
+    $ref: variantRequestParameters.yaml#/$defs/sequence
+  assemblyId:
+    $ref: variantRequestParameters.yaml#/$defs/assemblyId
+
+examples:
+  - referenceName: 17
+    assemblyId: GRCh38
+    start: [61995191]
+    alternateBases: TC

schemas/VariantBracketRequest.yaml

@@ -1,11 +1,18 @@
-"$schema": http://json-schema.org/draft-07/schema#
-"$id": https://beacon-project.io/schemas/beacon/BeaconRangeRequest/v1.1.0
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://genomebeacons.org/schemas/beacon/BeaconRangeRequest/v2.0
 title: VariantBracketRequest
 description: >-
   A request for matching variants by position, with start and end positions falling
   into specified genomic ranges. The typical use case here is the query for similar
   structural variations - particularly CNVs - affecting a genomic region but potentially
   differing in their exact base extents.
+  Beacon version: v2.0
+  Future considerations: There are some inherited ambiguities
+  * `assemblyId` and `referenceName` should be deprectated in favour of a versioned
+    `sequenceId`
+  * the shared use of the `start` and `end` parameters for both base positions and
+    bracket positions is not ideal - here addressed by the `sequenceBracket` type
+    but still existing in parameters
 type: object
 required:
   - referenceName
@@ -15,29 +22,29 @@ additionalProperties: false
 
 properties:
   referenceName:
-    $ref: variantRequestParameters.yaml#/definitions/referenceName
+    $ref: variantRequestParameters.yaml#/$defs/referenceName
 
   start:
     description: >-
-      An array of exact 2 sorted integers for base positions bracketing the
+      An array of exactly 2 sorted integers for base positions bracketing the
       genomic range in which the start of the matched variants has to fall. For
       base exact matches this woyld mean `start[1] = start[0] + 1`.
       TODO: Formal schema for range positions?
-    $ref: variantRequestParameters.yaml#/definitions/start
+    $ref: variantRequestParameters.yaml#/$defs/sequenceBracket
 
   end:
     description: >-
-      An array of exact 2 sorted integers for base positions bracketing the
+      An array of exactly 2 sorted integers for base positions bracketing the
       genomic range in which the end of the matched variants has to fall. For
       base exact matches this woyld mean `end[1] = end[0] + 1`.
       TODO: Formal schema for range positions?
-    $ref: variantRequestParameters.yaml#/definitions/end
+    $ref: variantRequestParameters.yaml#/$defs/sequenceBracket
 
   variantType:
-    $ref: variantRequestParameters.yaml#/definitions/variantType
+    $ref: variantRequestParameters.yaml#/$defs/variantType
 
   assemblyId:
-    $ref: variantRequestParameters.yaml#/definitions/assemblyId
+    $ref: variantRequestParameters.yaml#/$defs/assemblyId
 
 examples:
   - referenceName: refseq:NC_000017.11

schemas/VariantRangeRequest.yaml

@@ -1,8 +1,19 @@
-"$schema": http://json-schema.org/draft-07/schema#
-"$id": https://beacon-project.io/schemas/beacon/BeaconRangeRequest/v1.1.0
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://genomebeacons.org/schemas/beacon/BeaconRangeRequest/v1.1.0
 title: VariantRangeRequest
 description: >-
-  A request for matching variants in a genomic range.
+  A request for matching variants in a genomic range. This request type requires
+  to provide *exactly* 1 `start` and 1 `end` position, which are both 0-based and
+  define the base range with which variants should be associated. The exact way
+  of variant association (e.g. complete or partial overlap or even proximity) is 
+  being left to the individual implementations and use cases.
+  Beacon version: v2.0
+  Future considerations: There are some inherited ambiguities
+  * `assemblyId` and `referenceName` should be deprectated in favour of a versioned
+    `sequenceId`
+  * the shared use of the `start` and `end` parameters for both base positions and
+    bracket positions is not ideal - here addressed by the `sequencePosition` type
+    but still existing in parameters
 type: object
 required:
   - referenceName
@@ -11,22 +22,17 @@ required:
 
 properties:
   referenceName:
-    $ref: variantRequestParameters.yaml#/definitions/referenceName
-
+    $ref: variantRequestParameters.yaml#/$defs/referenceName
   start:
-    $ref: variantRequestParameters.yaml#/definitions/start
-
+    $ref: variantRequestParameters.yaml#/$defs/sequencePosition
   end:
-    $ref: variantRequestParameters.yaml#/definitions/end
-
+    $ref: variantRequestParameters.yaml#/$defs/sequencePosition
   alternateBases:
-    $ref: variantRequestParameters.yaml#/definitions/alternateBases
-
+    $ref: variantRequestParameters.yaml#/$defs/alternateBases
   variantType:
-    $ref: variantRequestParameters.yaml#/definitions/variantType
-
+    $ref: variantRequestParameters.yaml#/$defs/variantType
   assemblyId:
-    $ref: variantRequestParameters.yaml#/definitions/assemblyId
+    $ref: variantRequestParameters.yaml#/$defs/assemblyId
 
 examples:
   - referenceName: 17

schemas/variantRequestParameters.yaml

@@ -6,7 +6,7 @@ description: >-
   TODO: Variant Scouts => revise (e.g. name & PascalCasing of definitions ...)
 type: object
 
-definitions:
+$defs:
   assemblyId:
     description: >-
       Genomic assembly accession and version as RefSqeq assembly accession
@@ -47,7 +47,7 @@ definitions:
       - "9"
       - NC_012920.1
 
-  start:
+  basePositions:
     description: >-
       Precise or fuzzy start coordinate position(s), allele locus
       (0-based, inclusive).
@@ -81,23 +81,33 @@ definitions:
     minItems: 1
     maxItems: 2
 
-  end:
-    description: >-
-      Precise or bracketing the end of the variants of interest:
-      * (0-based, exclusive) - see `start`
-      * for bracket queries, provide 2 values (e.g. [111,222])."
-      TODO: Variant Scouts => revise (e.g. move documentation to query types) 
+  sequencePosition:
+    description:
+      This is an explicit 1-value version of the `basePositions` generic, for use
+      in e.g. `VariantRangeRequest` or allele requests.
     type: array
     items:
       type: integer
       format: int64
-      minimum: 1
-    minItems: 0
+      minimum: 0
+    minItems: 1
+    maxItems: 1
+
+  sequenceBracket:
+    description:
+      This is an explicit 2-values version of the `basePositions` generic, for use
+      in e.g. `VariantBracketRequest`.
+    type: array
+    items:
+      type: integer
+      format: int64
+      minimum: 0
+    minItems: 2
     maxItems: 2
 
-  alternateBases:
+  sequence:
     description: >-
-      Sequence of bases for this variation (starting from `start`).
+      Sequence of bases for a variation (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. As example,
@@ -108,12 +118,6 @@ definitions:
     type: string
     pattern: ^([ACGTUNRYSWKMBDHV\-\.]*)$
 
-  referenceBases: >-
-      Sequence of bases which have been replaced by the variation (from `start`).
-      The use of characters is equivalent to the `alternateBases` parameter
-    type: string
-    pattern: ^([ACGTUNRYSWKMBDHV\-\.]*)$
-
   variantType:
     description: >-
       The `variantType` is used to query variants which are not defined through