refactoring "info" and its links

This PR addresses part of the "deep link to the framework" problems. It: * moves the framework "info" to a separate file * adds another info.yaml / .json to the models in "common" and changes refereces from model schemas to this local version Both steps are complementary; if also going with the separate version in the model we might consider this for e.g. ontologyTerm, too (already a separate file in the framework).
ga4gh-beacon · Nov 15, 2024 · 5c7f5a9 · 5c7f5a9
1 parent 4803e1d
commit 5c7f5a9
Show file tree

Hide file tree

Showing 24 changed files with 45 additions and 40 deletions.
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/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/responses/beaconBooleanResponse.yaml b/framework/src/responses/beaconBooleanResponse.yaml
@@ -17,7 +17,7 @@ properties:
     description: >-
       Additional details that could be of interest. Provided to clearly
       enclose any attribute that is not part of the Beacon specification.
-    $ref: ../common/beaconCommonComponents.yaml#/$defs/Info
+    $ref: ../common/info.yaml
   beaconHandovers:
     description: >-
       List of handovers that apply to the whole response, not to any resultset

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

diff --git a/framework/src/responses/beaconCountResponse.yaml b/framework/src/responses/beaconCountResponse.yaml
@@ -17,7 +17,7 @@ properties:
     description: >-
       Additional details that could be of interest. Provided to clearly
       enclose any attribute that is not part of the Beacon specification.
-    $ref: ../common/beaconCommonComponents.yaml#/$defs/Info
+    $ref: ../common/info.yaml
   beaconHandovers:
     description: >-
       List of handovers that apply to the whole response, not to any resultset

diff --git a/framework/src/responses/beaconResultsetsResponse.yaml b/framework/src/responses/beaconResultsetsResponse.yaml
@@ -15,7 +15,7 @@ properties:
     description: >-
       Additional details that could be of interest. Provided to clearly
       enclose any attribute that is not part of the Beacon specification.
-    $ref: ../common/beaconCommonComponents.yaml#/$defs/Info
+    $ref: ../common/info.yaml
   beaconHandovers:
     description: >-
       List of handovers that apply to the whole response, not to any resultset

diff --git a/framework/src/responses/sections/beaconInfoResults.yaml b/framework/src/responses/sections/beaconInfoResults.yaml
@@ -67,7 +67,7 @@ properties:
   info:
     description: >-
       Additional unspecified metadata about the Beacon service.
-    $ref: ../../common/beaconCommonComponents.yaml#/$defs/Info
+    $ref: ../../common/info.yaml
 $defs:
   BeaconOrganization:
     description: >-
@@ -109,5 +109,5 @@ $defs:
           3986 format).
       info:
         description: Additional unspecified metadata about the host Organization.
-        $ref: ../../common/beaconCommonComponents.yaml#/$defs/Info
+        $ref: ../../common/info.yaml
 additionalProperties: true
diff --git a/models/json/beacon-v2-default-model/analyses/defaultSchema.json b/models/json/beacon-v2-default-model/analyses/defaultSchema.json
@@ -38,7 +38,7 @@
             "type": "string"
         },
         "info": {
-            "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info"
+            "$ref": "../common/info.json"
         },
         "pipelineName": {
             "description": "Analysis pipeline and version if a standardized pipeline was used",

diff --git a/models/json/beacon-v2-default-model/biosamples/defaultSchema.json b/models/json/beacon-v2-default-model/biosamples/defaultSchema.json
@@ -82,7 +82,7 @@
             "type": "string"
         },
         "info": {
-            "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info"
+            "$ref": "../common/info.json"
         },
         "measurements": {
             "description": "List of measurements of the sample.",

diff --git a/models/json/beacon-v2-default-model/datasets/defaultSchema.json b/models/json/beacon-v2-default-model/datasets/defaultSchema.json
@@ -37,7 +37,7 @@
             "type": "string"
         },
         "info": {
-            "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info"
+            "$ref": "../common/info.json"
         },
         "name": {
             "description": "Name of the dataset",

diff --git a/models/json/beacon-v2-default-model/individuals/defaultSchema.json b/models/json/beacon-v2-default-model/individuals/defaultSchema.json
@@ -31,7 +31,7 @@
             "type": "string"
         },
         "info": {
-            "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info"
+            "$ref": "../common/info.json"
         },
         "interventionsOrProcedures": {
             "items": {
@@ -63,7 +63,7 @@
         },
         "sex": {
             "$ref": "../common/commonDefinitions.json#/$defs/Sex",
-            "description": "Sex of the individual. Value from NCIT General Qualifier (NCIT:C27993): 'unknown' (not assessed or not available) (NCIT:C17998), 'female' (NCIT:C16576), or 'male', (NCIT:C20197)."
+            "description": "Sex of the individual. Value from NCIT General Qualifier `NCIT:C27993`:    * `unknown`: not assessed or not availablel `NCIT:C17998` * `female`: `NCIT:C16576)` * `male`: `NCIT:C20197`"
         },
         "treatments": {
             "items": {

diff --git a/models/json/beacon-v2-default-model/runs/defaultSchema.json b/models/json/beacon-v2-default-model/runs/defaultSchema.json
@@ -26,7 +26,7 @@
             "type": "string"
         },
         "info": {
-            "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info"
+            "$ref": "../common/info.json"
         },
         "libraryLayout": {
             "description": "Ontology value for the library layout e.g \"PAIRED\", \"SINGLE\" #todo add Ontology name?",

diff --git a/models/src/beacon-v2-default-model/analyses/defaultSchema.yaml b/models/src/beacon-v2-default-model/analyses/defaultSchema.yaml
@@ -51,7 +51,7 @@ properties:
     examples:
       - GATK4.0
   info:
-    $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info
+    $ref: ../common/info.yaml
 required:
   - id
   - analysisDate

diff --git a/models/src/beacon-v2-default-model/biosamples/defaultSchema.yaml b/models/src/beacon-v2-default-model/biosamples/defaultSchema.yaml
@@ -160,7 +160,7 @@ properties:
     $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
     example: {}
   info:
-    $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info
+    $ref: ../common/info.yaml
 required:
   - id
   - biosampleStatus

diff --git a/models/src/beacon-v2-default-model/datasets/defaultSchema.yaml b/models/src/beacon-v2-default-model/datasets/defaultSchema.yaml
@@ -40,7 +40,7 @@ properties:
     examples:
       - https://example.org/wiki/Main_Page
   info:
-    $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info
+    $ref: ../common/info.yaml
   dataUseConditions:
     description: Data use conditions applying to this dataset.
     $ref: ../common/dataUseConditions.yaml

diff --git a/models/src/beacon-v2-default-model/individuals/defaultSchema.yaml b/models/src/beacon-v2-default-model/individuals/defaultSchema.yaml
@@ -9,9 +9,11 @@ properties:
     type: string
     example: P0001
   sex:
-    description: "Sex of the individual. Value from NCIT General Qualifier (NCIT:C27993):\
-      \ 'unknown' (not assessed or not available) (NCIT:C17998), 'female' (NCIT:C16576),\
-      \ or 'male', (NCIT:C20197)."
+    description: >-
+      Sex of the individual. Value from NCIT General Qualifier `NCIT:C27993`:   
+      * `unknown`: not assessed or not availablel `NCIT:C17998`
+      * `female`: `NCIT:C16576)`
+      * `male`: `NCIT:C20197`
     $ref: ../common/commonDefinitions.yaml#/$defs/Sex
   karyotypicSex:
     description: The chromosomal sex of an individual represented from a selection
@@ -60,7 +62,7 @@ properties:
     items:
       $ref: ../common/exposure.yaml
   info:
-    $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info
+    $ref: ../common/info.yaml
 required:
   - id
   - sex

diff --git a/models/src/beacon-v2-default-model/runs/defaultSchema.yaml b/models/src/beacon-v2-default-model/runs/defaultSchema.yaml
@@ -74,7 +74,7 @@ properties:
       - id: EFO:0010938
         label: large-insert clone DNA microarray
   info:
-    $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/Info
+    $ref: ../common/info.yaml
 required:
   - id
   - biosampleId