Merge pull request #169 from ga4gh-beacon/main

Updating develop branch from last urgent fixes to main
ga4gh-beacon · Oct 8, 2024 · 56ff359 · 56ff359
2 parents efec4c3 + 5ea17fb
commit 56ff359
Show file tree

Hide file tree

Showing 21 changed files with 206 additions and 463 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -34,7 +34,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
  * Fixed `POST`queries for `g_variant` (w/ examples)
- * Removed 'json' references inside the yaml version (PR [#43] (https://github.com/ga4gh-beacon/beacon-v2/pull/43))
+ * Removed 'json' references inside the yaml version (PR [#43](https://github.com/ga4gh-beacon/beacon-v2/pull/43))
+ * added missing `type: object` to `ResultsetInstance` (PR [#82](https://github.com/ga4gh-beacon/beacon-v2/pull/82))
 
 ### Deprecated
 

diff --git a/README.md b/README.md
@@ -28,7 +28,29 @@ As with other schema projects, here we separate between the schema source files
 
 There is a set of tools in [`/bin`](./bin/) to facilitate the conversion. ATM, after editing `...yaml` schema files somewhere in the `/src` tree, a (local) run of `bin/yamlerRunner.sh` - which re-generates the `....json` files in the `/json` tree) has to be performed before pushing changes.
 
-### Changes
+### Changelog
+
+## 2.1.0
+
+*Released, July, 19, 2024*
+
+* Relocated TypedQuantity required to proper level of the schema for complexValue
+* Added end and start entities for ageRange and iso8601duration for age
+* Filtering terms scopes changed from string to array of strings
+
+## 2.0.1
+
+*Released July, 16, 2024*
+
+* Replaced ENSGLOSSARY for SO ontology family in documentation examples
+* Moved CURIE to beaconCommonComponents
+* Created filtering terms entity
+* Removed validation directories
+* Several fixes to entity types, typos and other non-breaking changes
+
+## 2.0.0
+
+*Released June, 21, 2022*
 
 * change notes with respect to the repository & documentation are now in [docs.genomebeacons.org](https://docs.genomebeacons.org/changes-todo/)
 * NOTE: on 2022-06-20 the previous development repositories have been archived:

diff --git a/docs/variant-queries.md b/docs/variant-queries.md
@@ -374,18 +374,19 @@ values to underlying genomic variations had not been precisely defined.
 
 This table is maintained in parallel with the [hCNV community documentation](https://cnvar.org/resources/CNV-annotation-standards/#cnv-term-use-comparison-in-computational-fileschema-formats).
 
-| [EFO](https://www.ebi.ac.uk/efo/EFO_0030063) | Beacon | [VCF](https://samtools.github.io/hts-specs/) | SO       | GA4GH [VRS](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber) &rArr;<br/>[VRS proposal](https://github.com/ga4gh/vrs/issues/404)[^1] | Notes |
+| [EFO](http://www.ebi.ac.uk/efo/EFO_0030063) | Beacon | [VCF](https://samtools.github.io/hts-specs/) | SO       | GA4GH [VRS](https://vrs.ga4gh.org/en/latest/terms_and_model.html#copynumberchange)[^1] | Notes |
 | ------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| <nobr>[`EFO:0030070`](https://www.ebi.ac.uk/efo/EFO_0030070)</nobr> copy number gain | `DUP`[^2] or<br/><nobr>[`EFO:0030070`](https://www.ebi.ac.uk/efo/EFO_0030070)</nobr> | `DUP`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001742`](https://www.sequenceontology.org/browser/current_release/term/SO:0001742) copy_number_gain | [`low-level gain`](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber) (implicit) &rArr; [`EFO:0030070`](https://www.ebi.ac.uk/efo/EFO_0030070) copy&nbsp;number&nbsp;gain  | a sequence alteration whereby the copy number of a given genomic region is greater than the reference sequence |
-| [`EFO:0030071`](https://www.ebi.ac.uk/efo/EFO_0030071) low-level copy number gain| `DUP`[^2] or<br/><nobr>[`EFO:0030071`](https://www.ebi.ac.uk/efo/EFO_0030071)</nobr> | `DUP`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001742`](https://www.sequenceontology.org/browser/current_release/term/SO:0001742) copy_number_gain   | [`low-level gain`](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber) &rArr; [`EFO:0030071`](https://www.ebi.ac.uk/efo/EFO_0030071) low-level copy number gain |                                                                                                                             |
-| [`EFO:0030072`](https://www.ebi.ac.uk/efo/EFO_0030072) high-level copy number gain | `DUP`[^2] or<br/><nobr>[`EFO:0030072`](https://www.ebi.ac.uk/efo/EFO_0030072)</nobr> | `DUP`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001742`](https://www.sequenceontology.org/browser/current_release/term/SO:0001742) copy_number_gain | [`high-level gain`](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber) &rArr; [`EFO:0030072`](https://www.ebi.ac.uk/efo/EFO_0030072) high-level copy number gain | commonly but not consistently used for >=5 copies on a bi-allelic genome region                                             |
-| [`EFO:0030073`](https://www.ebi.ac.uk/efo/EFO_0030073) focal genome amplification  | `DUP`[^2] or<br/><nobr>[`EFO:0030073`](https://www.ebi.ac.uk/efo/EFO_0030073)</nobr> | `DUP`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001742`](https://www.sequenceontology.org/browser/current_release/term/SO:0001742) copy_number_gain | [`high-level gain`](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber) &rArr; [`EFO:0030073`](https://www.ebi.ac.uk/efo/EFO_0030073) focal genome amplification  | commonly but not consistently used for >=5 copies on a bi-allelic genome region, of limited size (operationally max. 1-5Mb) |
-| [`EFO:0030067`](https://www.ebi.ac.uk/efo/EFO_0030067) copy number loss            | `DEL`[^2] or<br/><nobr>[`EFO:0030067`](https://www.ebi.ac.uk/efo/EFO_0030067)</nobr> | `DEL`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001743`](https://www.sequenceontology.org/browser/current_release/term/SO:0001743) copy_number_loss | [`partial loss`](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber) (implicit) &rArr; [`EFO:0030067`](https://www.ebi.ac.uk/efo/EFO_0030067) copy number loss            | a sequence alteration whereby the copy number of a given genomic region is smaller than the reference sequence              |
-| [`EFO:0030068`](https://www.ebi.ac.uk/efo/EFO_0030068) low-level copy number loss  | `DEL`[^2] or<br/><nobr>[`EFO:0030068`](https://www.ebi.ac.uk/efo/EFO_0030068)</nobr> | `DEL`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001743`](https://www.sequenceontology.org/browser/current_release/term/SO:0001743) copy_number_loss | [`partial loss`](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber)  &rArr; [`EFO:0030068`](https://www.ebi.ac.uk/efo/EFO_0030068) low-level copy number loss  |                                                                                                                             |
-| [`EFO:0020073`](https://www.ebi.ac.uk/efo/EFO_0020073) high-level copy number loss  | `DEL`[^2] or<br/><nobr>[`EFO:0020073`](https://github.com/EBISPOT/efo/issues/1941)</nobr> | `DEL`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001743`](https://www.sequenceontology.org/browser/current_release/term/SO:0001743) copy_number_loss | [`partial loss`](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber)  &rArr; [`EFO:0020073`](https://github.com/EBISPOT/efo/issues/1941) high-level copy number loss  | a loss of several copies; also used in cases where a complete genomic deletion cannot be asserted |
-| [`EFO:0030069`](https://www.ebi.ac.uk/efo/EFO_0030069) complete genomic deletion   | `DEL`[^2] or<br/><nobr>[`EFO:0030069`](https://www.ebi.ac.uk/efo/EFO_0030069)</nobr> | `DEL`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001743`](https://www.sequenceontology.org/browser/current_release/term/SO:0001743) copy_number_loss | [`complete loss`](https://vrs.ga4gh.org/en/latest/terms_and_model.html#relativecopynumber) &rArr; [`EFO:0030069`](https://www.ebi.ac.uk/efo/EFO_0030069) complete genomic deletion   | complete genomic deletion (e.g. homozygous deletion on a bi-allelic genome region)                                          |
-
-##### Last updated 2023-03-22 by @mbaudis (EFO:0020073)
+| <nobr>[`EFO:0030070`](http://www.ebi.ac.uk/efo/EFO_0030070)</nobr> copy number gain | `DUP`[^2] or<br/><nobr>[`EFO:0030070`](http://www.ebi.ac.uk/efo/EFO_0030070)</nobr> | `DUP`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001742`](http://www.sequenceontology.org/browser/current_release/term/SO:0001742) copy_number_gain | <nobr>[`EFO:0030070`](http://www.ebi.ac.uk/efo/EFO_0030070) gain  | a sequence alteration whereby the copy number of a given genomic region is greater than the reference sequence |
+| [`EFO:0030071`](http://www.ebi.ac.uk/efo/EFO_0030071) low-level copy number gain| `DUP`[^2] or<br/><nobr>[`EFO:0030071`](http://www.ebi.ac.uk/efo/EFO_0030071)</nobr> | `DUP`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001742`](http://www.sequenceontology.org/browser/current_release/term/SO:0001742) copy_number_gain   | <nobr>[`EFO:0030071`](http://www.ebi.ac.uk/efo/EFO_0030071)</nobr> low-level gain |                                                                                                                             |
+| [`EFO:0030072`](http://www.ebi.ac.uk/efo/EFO_0030072) high-level copy number gain | `DUP`[^2] or<br/><nobr>[`EFO:0030072`](http://www.ebi.ac.uk/efo/EFO_0030072)</nobr> | `DUP`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001742`](http://www.sequenceontology.org/browser/current_release/term/SO:0001742) copy_number_gain | <nobr>[`EFO:0030072`](http://www.ebi.ac.uk/efo/EFO_0030072)</nobr> high-level gain | commonly but not consistently used for >=5 copies on a bi-allelic genome region                                             |
+| [`EFO:0030073`](http://www.ebi.ac.uk/efo/EFO_0030073) focal genome amplification  | `DUP`[^2] or<br/><nobr>[`EFO:0030073`](http://www.ebi.ac.uk/efo/EFO_0030073)</nobr> | `DUP`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001742`](http://www.sequenceontology.org/browser/current_release/term/SO:0001742) copy_number_gain | <nobr>[`EFO:0030072`](http://www.ebi.ac.uk/efo/EFO_0030072)</nobr> high-level gain[^4]  | commonly but not consistently used for >=5 copies on a bi-allelic genome region, of limited size (operationally max. 1-5Mb) |
+| [`EFO:0030067`](http://www.ebi.ac.uk/efo/EFO_0030067) copy number loss            | `DEL`[^2] or<br/><nobr>[`EFO:0030067`](http://www.ebi.ac.uk/efo/EFO_0030067)</nobr> | `DEL`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001743`](http://www.sequenceontology.org/browser/current_release/term/SO:0001743) copy_number_loss | <nobr>[`EFO:0030067`](http://www.ebi.ac.uk/efo/EFO_0030067)</nobr> loss            | a sequence alteration whereby the copy number of a given genomic region is smaller than the reference sequence              |
+| [`EFO:0030068`](http://www.ebi.ac.uk/efo/EFO_0030068) low-level copy number loss  | `DEL`[^2] or<br/><nobr>[`EFO:0030068`](http://www.ebi.ac.uk/efo/EFO_0030068)</nobr> | `DEL`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001743`](http://www.sequenceontology.org/browser/current_release/term/SO:0001743) copy_number_loss | <nobr>[`EFO:0030068`](http://www.ebi.ac.uk/efo/EFO_0030068)</nobr> low-level loss  |                                                                                                                             |
+| [`EFO:0020073`](http://www.ebi.ac.uk/efo/EFO_0020073) high-level copy number loss  | `DEL`[^2] or<br/><nobr>[`EFO:0020073`](https://github.com/EBISPOT/efo/issues/1941)</nobr> | `DEL`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001743`](http://www.sequenceontology.org/browser/current_release/term/SO:0001743) copy_number_loss | <nobr>[`EFO:0020073`](https://github.com/EBISPOT/efo/issues/1941)</nobr> high-level loss  | a loss of several copies; also used in cases where a complete genomic deletion cannot be asserted |
+| [`EFO:0030069`](http://www.ebi.ac.uk/efo/EFO_0030069) complete genomic deletion   | `DEL`[^2] or<br/><nobr>[`EFO:0030069`](http://www.ebi.ac.uk/efo/EFO_0030069)</nobr> | `DEL`<br/><nobr>`SVCLAIM=D`[^3]</nobr> | [`SO:0001743`](http://www.sequenceontology.org/browser/current_release/term/SO:0001743) copy_number_loss | <nobr>[`EFO:0030069`](http://www.ebi.ac.uk/efo/EFO_0030069)</nobr> complete genomic loss   | complete genomic deletion (e.g. homozygous deletion on a bi-allelic genome region)                                          |
+
+
+##### Last updated 2023-07-13 to align with 2023-03-22 hCNV documentation (VRS 1.3 adjustment) by @mbaudis
 ##### updated 2023-03-20 by @mbaudis (VRS proposal)
 
 ## Query Parameter Change Log
@@ -417,17 +418,17 @@ recommended for query forms
 	and `alternateBases`
 
 
-[^1]: The VRS annotations refer to the status at v1.2 (2022). The GA4GH VRS team
-is currently (Spring 2023) preparing an updated specification which will introduce
-the new class `CopyNumberChange` ([discussion...](https://github.com/ga4gh/vrs/issues/404#issuecomment-1472599849)) with the use of the EFO terms (including a new term 
-for `high level deletion (EFO:0020073)` in the April 2023 EFO release).
+[^1]: The VRS annotations refer to the status from v1.3 (2022) when 
+the new class `CopyNumberChange` ([discussion...](https://github.com/ga4gh/vrs/issues/404#issuecomment-1472599849))
+with the use of the EFO terms.
 [^2]: While the use of VCF derived (`DUP`, `DEL`) values had been introduced with
 beacon v1, usage of these terms has always been a _recommendation_ rather than an integral part
 of the API. We now encourage the support of more specific terms (particularly EFO)
-by Beacon developers. As example, the Progentix Beacon API [uses EFO terms](https://progenetix.org/search/) but
+by Beacon developers. As example, the Progentix Beacon API [uses EFO terms](http://progenetix.org/search/) but
 provides an internal term expansion for legacy `DUP`, `DEL` support.
 [^3]: VCFv4.4 introduces an `SVCLAIM` field to disambiguate between _in situ_ events (such as
 tandem duplications; known _adjacency_/ _break junction_: `SVCLAIM=J`) and events where e.g. only the
 change in _abundance_ / _read depth_ (`SVCLAIM=D`) has been determined. Both **J** and **D** flags can be combined.
+[^4]: VRS did not adopt the "amplification" term due to possible inconsistencies
 
 
diff --git a/framework/json/common/beaconCommonComponents.json b/framework/json/common/beaconCommonComponents.json
@@ -76,11 +76,10 @@
         },
         "Granularity": {
             "default": "boolean",
-            "description": "Level of detail of the response:\n* `boolean`: returns true/false' responses * `count`: adds the total number of positive results found * `aggregated`: returns summary, aggregated or distribution like responses * `record`: returns details for every row. In cases where a Beacon prefers to return records with fewer than allattributes, different strategies have to be considered w/o adding them to the current design, e.g.:\n    - keeping non-mandatory attributes empty\n    - Beacon to provide a minimal record definition",
+            "description": "Level of detail of the response:\n* `boolean`: returns true/false' responses * `count`: adds the total number of positive results found * `record`: returns details for every row. In cases where a Beacon prefers to return records with fewer than allattributes, different strategies have to be considered w/o adding them to the current design, e.g.:\n    - keeping non-mandatory attributes empty\n    - Beacon to provide a minimal record definition",
             "enum": [
                 "boolean",
                 "count",
-                "aggregated",
                 "record"
             ],
             "type": "string"
@@ -111,15 +110,19 @@
         },
         "HandoverType": {
             "$ref": "./ontologyTerm.json",
-            "description": "Handover type, as an Ontology_term object with CURIE syntax for the `id` value. Use `CUSTOM` for the `id` when no ontology is available.",
+            "description": "Handover type, as an Ontology_term object with CURIE syntax for the `id` value. Use \"CUSTOM:123455\" CURIE-style `id` when no ontology is available.",
             "examples": [
                 {
-                    "id": "EFO:0004157",
-                    "label": "BAM format"
+                    "id": "EDAM:2572",
+                    "label": "BAM"
                 },
                 {
-                    "id": "CUSTOM",
-                    "label": "download genomic variants in .pgxseg file format"
+                    "id": "EDAM:3016",
+                    "label": "VCF"
+                },
+                {
+                    "id": "CUSTOM:pgxseg",
+                    "label": "genomic variants in .pgxseg file format"
                 }
             ]
         },

diff --git a/framework/json/common/validation/beaconCommonComponents.json b/framework/json/common/validation/beaconCommonComponents.json
diff --git a/framework/json/configuration/beaconMapSchema.json b/framework/json/configuration/beaconMapSchema.json
@@ -18,7 +18,7 @@
                 },
                 "filteringTermsUrl": {
                     "description": "Optional. Returns the list of filtering terms that could be applied to this entry type. It is added here for convenience of the Beacon clients, so they don't need to parse the OpenAPI endpoints definition to get that endpoint. Also, in very simple Beacons, that endpoint could be the one of the few implemented, together with \u00b4rootUrl` and \u00b4singleEntryUrl`, in which case the whole map of endpoints is found in the current Map.",
-                    "format": "uri",
+                    "format": "uri-template",
                     "type": "string"
                 },
                 "openAPIEndpointsDefinition": {
@@ -32,7 +32,7 @@
                 },
                 "singleEntryUrl": {
                     "description": "Optional, but recommended. Returns only one instance of this entry, identified by an `id`. It is added here for convenience of the Beacon clients, so they don't need to parse the OpenAPI endpoints definition to get that base endpoint. Also, in very simple Beacons, that endpoint could be the only one implemented, together with \u00b4rootUrl`, in which case the whole map of endpoints is found in the current Map.",
-                    "format": "uri",
+                    "format": "uri-template",
                     "type": "string"
                 }
             },
@@ -50,7 +50,7 @@
                 },
                 "url": {
                     "description": "Endpoint URL",
-                    "format": "uri",
+                    "format": "uri-template",
                     "type": "string"
                 }
             },