diff --git a/schemas/BeaconAlleleRequest.yaml b/schemas/BeaconAlleleRequest.yaml new file mode 100644 index 0000000..4fd0110 --- /dev/null +++ b/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 diff --git a/schemas/VariantBracketRequest.yaml b/schemas/VariantBracketRequest.yaml index 29ad751..a7460c2 100644 --- a/schemas/VariantBracketRequest.yaml +++ b/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 diff --git a/schemas/VariantRangeRequest.yaml b/schemas/VariantRangeRequest.yaml index 367b7f7..bb3d537 100644 --- a/schemas/VariantRangeRequest.yaml +++ b/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 diff --git a/schemas/variantRequestParameters.yaml b/schemas/variantRequestParameters.yaml index e0b2c1a..9861c78 100644 --- a/schemas/variantRequestParameters.yaml +++ b/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