From 5c7f5a9299292ca6248d83ed40cf6c0cafa240ef Mon Sep 17 00:00:00 2001 From: Michael Baudis Date: Fri, 15 Nov 2024 15:45:13 +0900 Subject: [PATCH] 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). --- framework/json/common/beaconCommonComponents.json | 4 ---- framework/json/common/info.json | 6 ++++++ framework/json/responses/beaconBooleanResponse.json | 2 +- .../json/responses/beaconCollectionsResponse.json | 2 +- framework/json/responses/beaconCountResponse.json | 2 +- .../json/responses/beaconResultsetsResponse.json | 2 +- .../json/responses/sections/beaconInfoResults.json | 4 ++-- framework/src/common/beaconCommonComponents.yaml | 10 ---------- framework/src/common/info.yaml | 11 +++++++++++ framework/src/responses/beaconBooleanResponse.yaml | 2 +- .../src/responses/beaconCollectionsResponse.yaml | 2 +- framework/src/responses/beaconCountResponse.yaml | 2 +- framework/src/responses/beaconResultsetsResponse.yaml | 2 +- .../src/responses/sections/beaconInfoResults.yaml | 4 ++-- .../analyses/defaultSchema.json | 2 +- .../biosamples/defaultSchema.json | 2 +- .../datasets/defaultSchema.json | 2 +- .../individuals/defaultSchema.json | 4 ++-- .../beacon-v2-default-model/runs/defaultSchema.json | 2 +- .../analyses/defaultSchema.yaml | 2 +- .../biosamples/defaultSchema.yaml | 2 +- .../datasets/defaultSchema.yaml | 2 +- .../individuals/defaultSchema.yaml | 10 ++++++---- .../beacon-v2-default-model/runs/defaultSchema.yaml | 2 +- 24 files changed, 45 insertions(+), 40 deletions(-) create mode 100644 framework/json/common/info.json create mode 100644 framework/src/common/info.yaml diff --git a/framework/json/common/beaconCommonComponents.json b/framework/json/common/beaconCommonComponents.json index 10ee8912..8c73c107 100644 --- 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 new file mode 100644 index 00000000..69826f5e --- /dev/null +++ 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" +} \ No newline at end of file diff --git a/framework/json/responses/beaconBooleanResponse.json b/framework/json/responses/beaconBooleanResponse.json index 8491ca4b..dc36a6dd 100644 --- 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 index 6728e334..ca8cdb72 100644 --- 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 index 9222ae90..acf4ffcc 100644 --- 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 index 8efe9617..094ed57a 100644 --- 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 index f795b2db..0773b1db 100644 --- 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 index b77fab3c..8af76d1a 100644 --- 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 new file mode 100644 index 00000000..2b29ef3f --- /dev/null +++ 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 index 97811e09..b68dc849 100644 --- 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 index 8b895ce6..93a35702 100644 --- 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 index f083849b..27d1dddb 100644 --- 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 index 11e8b732..39601cbd 100644 --- 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 index 2127e4a1..3c5cbaeb 100644 --- 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 index a082caa7..7def347a 100644 --- 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 index 392f5988..e6eca708 100644 --- 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 index 3efa64e7..51e28141 100644 --- 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 index e5b6876a..7ab94477 100644 --- 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 index 61d090df..e3f4040d 100644 --- 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 index 5c454121..3022bb09 100644 --- 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 index 008c4575..c90eda4d 100644 --- 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 index 7741c570..1747613c 100644 --- 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 index adc28d3e..c9f66d99 100644 --- 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 index 1ba08836..fc7efff9 100644 --- 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