Merge branch 'schema-urgent-fixes' into inline-documentation-updates

ga4gh-beacon · Dec 12, 2024 · f70a262 · f70a262
2 parents cd1d460 + 80036dd
commit f70a262
Show file tree

Hide file tree

Showing 34 changed files with 118 additions and 98 deletions.
diff --git a/README.md b/README.md
@@ -33,13 +33,15 @@ There is a set of tools in [`/bin`](./bin/) to facilitate the conversion. ATM, a
 ## 2.1.1
 
 *Released, October, 8, 2024*
+[Beacon-v2.1.1](https://github.com/ga4gh-beacon/beacon-v2/tree/5ea17fbd0d2ba533aa1e85f7271f9a2cc9be6794)
 
 * Changed uri for uri-template in Endpoint.singleEntryUrl
 
 
 ## 2.1.0
 
 *Released, July, 19, 2024*
+[Beacon-v2.1.0](https://github.com/ga4gh-beacon/beacon-v2/tree/16862205c79294fae5473f7fa330bf5929b3b120)
 
 * Relocated TypedQuantity required to proper level of the schema for complexValue
 * Added end and start entities for ageRange and iso8601duration for age
@@ -48,6 +50,7 @@ There is a set of tools in [`/bin`](./bin/) to facilitate the conversion. ATM, a
 ## 2.0.1
 
 *Released July, 16, 2024*
+[Beacon-v2.0.1](https://github.com/ga4gh-beacon/beacon-v2/tree/f6f85c445922831bd398552384593206c86287de)
 
 * Replaced ENSGLOSSARY for SO ontology family in documentation examples
 * Moved CURIE to beaconCommonComponents
@@ -58,6 +61,7 @@ There is a set of tools in [`/bin`](./bin/) to facilitate the conversion. ATM, a
 ## 2.0.0
 
 *Released June, 21, 2022*
+[Beacon-v2.0.0](https://github.com/ga4gh-beacon/beacon-v2/tree/d07ef1626321f7428374a4f68d864dfa5e98370f)
 
 * 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/bin/beacon_yaml2md.pl b/bin/beacon_yaml2md.pl
@@ -729,9 +729,9 @@ sub add_properties_vrs {
     my ( $property, $data ) = @_;
     my %url = (
         'SequenceExpression' =>
-'https://raw.githubusercontent.com/ga4gh/vrs/1.2/schema/vrs.json#/definitions/',
+'https://w3id.org/ga4gh/schema/vrs/1.3/vrs.json#/definitions/',
         'CopyNumber' =>
-'https://raw.githubusercontent.com/ga4gh/vrs/1.2/schema/vrs.json#/definitions/'
+'https://w3id.org/ga4gh/schema/vrs/1.3/vrs.json#/definitions/'
     );
     if ( exists $url{$property} ) {
         $data->{properties} =

diff --git a/bin/deref_schemas/obj/CopyNumber.yaml b/bin/deref_schemas/obj/CopyNumber.yaml
@@ -1,4 +1,4 @@
 ---
 CopyNumber:
-  properties: '[VRS definition for CopyNumber](https://raw.githubusercontent.com/ga4gh/vrs/1.2/schema/vrs.json#/definitions/CopyNumber)'
+  properties: '[VRS definition for CopyNumber](https://w3id.org/ga4gh/schema/vrs/1.3/vrs.json#/definitions/CopyNumber)'
   type: allOf
diff --git a/docs/schemas-md/obj/CopyNumber.md b/docs/schemas-md/obj/CopyNumber.md
@@ -1,3 +1,3 @@
 |Term | Description | Type | Properties | Example | Enum|
 | ---| ---| ---| ---| ---| --- |
-| CopyNumber | NA | allOf | [VRS definition for CopyNumber](https://raw.githubusercontent.com/ga4gh/vrs/1.2/schema/vrs.json#/definitions/CopyNumber) | NA | NA|
+| CopyNumber | NA | allOf | [VRS definition for CopyNumber](https://w3id.org/ga4gh/schema/vrs/1.3/vrs.json#/definitions/CopyNumber) | NA | NA|
diff --git a/framework/json/common/beaconCommonComponents.json b/framework/json/common/beaconCommonComponents.json
@@ -142,10 +142,6 @@
             ],
             "type": "string"
         },
-        "Info": {
-            "description": "Placeholder to allow the Beacon to return any additional information that is necessary or could be of interest in relation to the query or the entry returned. It is recommended to encapsulate additional informations in this attribute instead of directly adding attributes at the same level than the others in order to avoid collision in the names of attributes in future versions of the specification.",
-            "type": "object"
-        },
         "Limit": {
             "default": 10,
             "description": "Size of the page. Use `0` to return all the results or the maximum allowed by the Beacon, if there is any.",

diff --git a/framework/json/common/info.json b/framework/json/common/info.json
@@ -0,0 +1,6 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "description": "Placeholder to allow the Beacon to return any additional information that is necessary or could be of interest in relation to the query or the entry returned. It is recommended to encapsulate additional informations in this attribute instead of directly adding attributes at the same level than the others in order to avoid collision in the names of attributes in future versions of the specification.",
+    "title": "Info",
+    "type": "object"
+}
diff --git a/framework/json/configuration/beaconMapSchema.json b/framework/json/configuration/beaconMapSchema.json
@@ -16,7 +16,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": {
@@ -30,7 +30,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"
                 }
             },
@@ -48,7 +48,7 @@
                 },
                 "url": {
                     "description": "Endpoint URL",
-                    "format": "uri",
+                    "format": "uri-template",
                     "type": "string"
                 }
             },

diff --git a/framework/json/configuration/entryTypeDefinition.json b/framework/json/configuration/entryTypeDefinition.json
@@ -1,14 +1,13 @@
 {
-    "$comment": "TODO: The tagged parts should reference to `common/ontologizedElement.json`. But that configuration fails to validate. Further investigation is required, but should not affect the resulting schema.'",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Definition of an element or entry type including the Beacon v2 required and suggested attributes. This schema purpose is to  describe each type of entities included in a Beacon, hence Beacon clients could have some metadata about such entities.  \nThe `id` attribute is the key that should be used in other parts of the Beacon Model to allow Beacon clients to identify the different parts (e.g. endpoints, filteringTerms, request parameters, etc.) that fully describe an entry type.",
+    "description": "Definition of an element or scope of the element, to describe each type of entry type included in a beacon. The `id` attribute is the key that should be used in other parts of the data model to allow Beacon clients to identify the different parts (e.g. endpoints, filtering terms, request parameters, etc.) that are relvant for an entry type.",
     "properties": {
         "$schema": {
             "$ref": "../common/beaconCommonComponents.json#/$defs/$schema"
         },
         "aCollectionOf": {
-            "description": "If the entry type is a collection of other entry types, (e.g. a Dataset is a collection of Records), then this attribute must list the entry types that could be included. One collection type could be defined as included more than one entry type (e.g. a Dataset could include Individuals or Genomic Variants), in such cases the entries are alternative, meaning that a given instance of this entry type could be of only one of the types (e.g. a given Dataset contains Individuals, while another Dataset could contain Genomic Variants, but not both at once).",
+            "description": "If the entry type is a collection of other entities, (e.g. a Dataset is a collection of Records), then this attribute must list the entities that can be included. One _collection_ can include more than one entry type  (e.g. a Dataset in teh Beacon cdefault model could include Individuals, Biosamples, GenomicVariations, Analyses amnd Runs). In such cases in each individual response (e.g. `resultSetsResponse` of collections of type \"dataset\") will contain entries of a single entry type (e.g. biosamples) even if a dataset may contain records of multiple types.",
             "includedConcepts": {
                 "$ref": "../common/basicElement.json",
                 "type": "array"
@@ -30,13 +29,17 @@
             "type": "string"
         },
         "filteringTerms": {
-            "$comment": "TO DO: Double-check the proper way of referencing a path or relative path. 'format: uri' is throwing validation errors for relative file paths",
-            "description": "Reference to the file with the list of filtering terms that could be used to filter this concept in this instance of Beacon. The referenced file could be used to populate the `filteringTerms`endpoint. Having it independently should allow for updating the list of accepted filtering terms when it is necessary.",
+            "$comment": "TO DO: Evaluate switch this to `url` or a more specific way for allowing URLs and local file paths (is this necessary?).",
+            "description": "Reference to the list of filtering terms that could be used to filter records of this entry type in this beacon.",
             "type": "string"
         },
         "id": {
-            "$comments": "++++++ THIS IS THE START OF THE ontologized element ++++++",
-            "description": "A (unique) identifier of the element.",
+            "description": "A unique identifier of the element.",
+            "examples": [
+                "biosample",
+                "individual",
+                "dataset"
+            ],
             "type": "string"
         },
         "name": {
@@ -47,8 +50,17 @@
             "$ref": "../common/beaconCommonComponents.json#/$defs/NonFilteredQueriesAllowed"
         },
         "ontologyTermForThisType": {
-            "$comments": "++++++ THIS IS THE END OF THE ontologized element ++++++",
-            "$ref": "../common/ontologyTerm.json"
+            "$ref": "../common/ontologyTerm.json",
+            "examples": [
+                {
+                    "id": "EFO:0000542",
+                    "label": "individual"
+                },
+                {
+                    "id": "OBI:0000747",
+                    "label": "material sample"
+                }
+            ]
         },
         "partOfSpecification": {
             "description": "This is label to group together entry types that are part of the same specification.",
@@ -59,7 +71,6 @@
     "required": [
         "id",
         "name",
-        "ontologyTermForThisType",
         "partOfSpecification",
         "defaultSchema"
     ],

diff --git a/framework/json/responses/beaconBooleanResponse.json b/framework/json/responses/beaconBooleanResponse.json
@@ -7,7 +7,7 @@
             "description": "List of handovers that apply to the whole response, not to any resultset or result in particular."
         },
         "info": {
-            "$ref": "../common/beaconCommonComponents.json#/$defs/Info",
+            "$ref": "../common/info.json",
             "description": "Additional details that could be of interest. Provided to clearly enclose any attribute that is not part of the Beacon specification."
         },
         "meta": {

diff --git a/framework/json/responses/beaconCollectionsResponse.json b/framework/json/responses/beaconCollectionsResponse.json
@@ -8,7 +8,7 @@
             "description": "List of handovers that apply to the whole response, not to any resultset or result in particular."
         },
         "info": {
-            "$ref": "../common/beaconCommonComponents.json#/$defs/Info",
+            "$ref": "../common/info.json",
             "description": "Additional details that could be of interest. Provided to clearly enclose any attribute that is not part of the Beacon specification."
         },
         "meta": {

diff --git a/framework/json/responses/beaconCountResponse.json b/framework/json/responses/beaconCountResponse.json
@@ -7,7 +7,7 @@
             "description": "List of handovers that apply to the whole response, not to any resultset or result in particular."
         },
         "info": {
-            "$ref": "../common/beaconCommonComponents.json#/$defs/Info",
+            "$ref": "../common/info.json",
             "description": "Additional details that could be of interest. Provided to clearly enclose any attribute that is not part of the Beacon specification."
         },
         "meta": {

diff --git a/framework/json/responses/beaconResultsetsResponse.json b/framework/json/responses/beaconResultsetsResponse.json
@@ -8,7 +8,7 @@
             "description": "List of handovers that apply to the whole response, not to any resultset or result in particular."
         },
         "info": {
-            "$ref": "../common/beaconCommonComponents.json#/$defs/Info",
+            "$ref": "../common/info.json",
             "description": "Additional details that could be of interest. Provided to clearly enclose any attribute that is not part of the Beacon specification."
         },
         "meta": {

diff --git a/framework/json/responses/sections/beaconInfoResults.json b/framework/json/responses/sections/beaconInfoResults.json
@@ -20,7 +20,7 @@
                     "type": "string"
                 },
                 "info": {
-                    "$ref": "../../common/beaconCommonComponents.json#/$defs/Info",
+                    "$ref": "../../common/info.json",
                     "description": "Additional unspecified metadata about the host Organization."
                 },
                 "logoUrl": {
@@ -86,7 +86,7 @@
             "$ref": "../../common/beaconCommonComponents.json#/$defs/BeaconId"
         },
         "info": {
-            "$ref": "../../common/beaconCommonComponents.json#/$defs/Info",
+            "$ref": "../../common/info.json",
             "description": "Additional unspecified metadata about the Beacon service."
         },
         "name": {

diff --git a/framework/src/common/beaconCommonComponents.yaml b/framework/src/common/beaconCommonComponents.yaml
@@ -212,16 +212,6 @@ $defs:
     minimum: 0
     examples:
       - 123
-  Info:
-    description: >-
-      Placeholder to allow the Beacon to return any additional information that
-      is necessary or could be of interest in relation to the query or the entry
-      returned.
-      It is recommended to encapsulate additional informations in this attribute
-      instead of directly adding attributes at the same level than the others in
-      order to avoid collision in the names of attributes in future versions of
-      the specification.
-    type: object
   ListOfHandovers:
     description: Set of handovers to be added in one section the response.
     type: array

diff --git a/framework/src/common/info.yaml b/framework/src/common/info.yaml
@@ -0,0 +1,11 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Info
+description: >-
+  Placeholder to allow the Beacon to return any additional information that
+  is necessary or could be of interest in relation to the query or the entry
+  returned.
+  It is recommended to encapsulate additional informations in this attribute
+  instead of directly adding attributes at the same level than the others in
+  order to avoid collision in the names of attributes in future versions of
+  the specification.
+type: object
diff --git a/framework/src/configuration/beaconMapSchema.yaml b/framework/src/configuration/beaconMapSchema.yaml
@@ -46,7 +46,7 @@ $defs:
           be the only one implemented, together with ´rootUrl`, in which case the
           whole map of endpoints is found in the current Map.
         type: string
-        format: uri
+        format: uri-template
       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,
@@ -55,7 +55,7 @@ $defs:
           the few implemented, together with ´rootUrl` and ´singleEntryUrl`, in which
           case the whole map of endpoints is found in the current Map.
         type: string
-        format: uri
+        format: uri-template
       endpoints:
         description: Optional. A list describing additional endpoints implemented
           by this Beacon instance for that entry type. Additional details on the endpoint
@@ -74,7 +74,7 @@ $defs:
       url:
         description: Endpoint URL
         type: string
-        format: uri
+        format: uri-template
       returnedEntryType:
         description: Which entry type is returned by querying this endpoint. It MUST
           match one of the entry types defined in the Beacon configuration file (`beaconConfiguration.json`).