From 7fdf7cc0455b37e74c020aa03a0951b2c6a2dfe3 Mon Sep 17 00:00:00 2001 From: Tom Shorter Date: Wed, 12 May 2021 10:32:54 +0100 Subject: [PATCH 1/6] Update beacon.yaml expansion of beacon.yaml to include the first implementation of the filters scout group suggestion for how to handle filters --- beacon.yaml | 250 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 216 insertions(+), 34 deletions(-) diff --git a/beacon.yaml b/beacon.yaml index d832add..ee21f23 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -114,7 +114,29 @@ paths: application/json: schema: $ref: '#/components/schemas/InfoResponse' - /datasets/{id}/variant_interpretations: + /datasets/{id}: + get: + description: | + Get information about the specified dataset. + operationId: getDataset + tags: + - Informational endpoints + parameters: + - name: id + in: path + description: Dataset ID + required: true + schema: + type: string + responses: + '200': + description: | + Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/InfoResponse' + /datasets/{id}/variant_interpretations: post: description: | Get the variants interpretations by datasetId. @@ -167,7 +189,7 @@ paths: /filtering_terms: get: description: | - Filtering terms available in this Beacon. + Get information about the filtering terms available in this Beacon. operationId: getFilteringTerms tags: - Informational endpoints @@ -179,6 +201,29 @@ paths: application/json: schema: $ref: '#/components/schemas/FilteringTermsResponse' + /datasets/{id}/filtering_terms: + get: + description: | + Get information about the filtering terms available in a dataset. + operationId: getDatasetFilteringTerms + tags: + - Informational endpoints + parameters: + - name: id + in: path + description: Dataset ID + required: true + schema: + type: string + responses: + '200': + description: | + Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/FilteringTermsResponse' + /individuals: post: description: | @@ -1841,18 +1886,76 @@ components: pattern: '^([ACGTN]*)$' Filters: description: | - Ontology based filters. CURIE syntax is encouraged to be used. + Rules for selecting records based upon the field values those records contain. Filters are seperated by the logical AND operator. type: array items: - type: string - example: 'BTO:0000199' - CustomFilters: + oneOf: + - $ref: '#/components/schemas/OntologyFilter' + - $ref: '#/components/schemas/AlphanumericFilter' + - $ref: '#/components/schemas/CustomFilter' + OntologyFilter: + type: object description: | - Custom filters defined by this Beacon. - type: array - items: - type: string - example: 'mydict.aterm:avalue,mydict.aterm2:avalue2' + Filter results to include records that contain a specific ontology term. + properties: + id: + type: string + description: | + Term ID to be queried, using CURIE syntax where possible. + example: 'HP:0002664' + includeDescendantTerms: + type: boolean + default: true + description: | + Define if the Beacon should implement the ontology hierarchy, thus query the descendant terms of `id`. + similarity: + type: string + enum: + - 'exact' + - 'high' + - 'medium' + - 'low' + default: 'exact' + description: | + Allow the Beacon to return results which do not match the filter exactly, but do match to a certain degree of similarity. The Beacon defines the semantic similarity model implemented and how to apply the thresholds of 'high', 'medium' and 'low' similarity. + AlphanumericFilter: + description: | + Filter results based on operators and values applied to alphanumeric fields. + type: object + properties: + id: + type: string + description: | + Field identfier to be queried. + example: 'age' + operator: + type: string + enum: + - '=' + - '<' + - '>' + - '!' + - '>=' + - '<=' + description: | + Defines how the value relates to the field `id`. + default: '=' + example: '>' + value: + type: string + description: | + Alphanumeric search term to be used within the query which can contain wildcard characters (%) to denote any number of unknown characters. Values can be assocatied with units if applicable. + example: 'P70Y' # age syntax as ISO 8601 + CustomFilter: + type: object + description: | + Filter results to include records that contain a custom term defined by this Beacon. + properties: + id: + type: string + description: | + Custom filter terms should contain a unique identifier. + example: 'demographic.ethnicity:asian' RequestDatasets: description: >- @@ -1939,6 +2042,23 @@ components: format the response. type: string example: 'v2.0' + FilteringTermsRequestMeta: + description: | + Requested schemas and versions to be used in the response. + type: object + properties: + requestedSchemas: + type: object + apiVersion: + description: | + Schemas & versions default for this Beacon version will be used to + format the response. + type: string + example: '2.0.0-draft.3' + datasetIds: + type: array + items: + type: string RequestMeta: description: | Requested schemas and versions to be used in the response. @@ -2020,6 +2140,15 @@ components: properties: meta: $ref: '#/components/schemas/InfoRequestMeta' + FilteringTermsRequest: + description: | + Request parameters for information endpoints. + type: object + required: + - meta + properties: + meta: + $ref: '#/components/schemas/FilteringTermsRequestMeta' Request: description: | Search for a genomic region @@ -2059,8 +2188,6 @@ components: $ref: '#/components/schemas/RequestDatasets' filters: $ref: '#/components/schemas/Filters' - customFilters: - $ref: '#/components/schemas/CustomFilters' pagination: $ref: '#/components/schemas/Pagination' GenomicVariantFields: @@ -2284,7 +2411,24 @@ components: $ref: '#/components/schemas/InfoRequest' returnedSchemas: $ref: '#/components/schemas/InfoRequestedSchemas' - + FilteringTermsResponseMeta: + description: | + Meta information about the reponse. + type: object + properties: + beaconId: + description: | + Identifier of the beacon, as defined in `Beacon`. + type: string + apiVersion: + description: >- + Version of the API. If specified, the value must match `apiVersion` + in Beacon + type: string + receivedRequest: + $ref: '#/components/schemas/FilteringTermsRequest' + returnedSchemas: + type: object GenomicVariantResponse: description: | Response of a genomic variant query @@ -2723,6 +2867,7 @@ components: oneOf: - $ref: 'https://raw.githubusercontent.com/ga4gh-beacon/specification-v2-default-schemas/draft.3/default_interactor_schema.yaml#/components/schemas/Interactor' - $ref: '#/components/schemas/AlternativeSchema' + CohortResponse: description: | Response of a query over cohorts. @@ -3175,24 +3320,27 @@ components: example: "BAM format" FilteringTermsResponse: - type: object description: | - Filtering terms available in this Beacon. + Response of a query over Beacon info. Use `InfoResponseContent` when querying the Beacon info endpoints, and `DatasetResponseContent` when querying the datasets endpoint. + type: object required: - - beaconId - - apiVersion - - filteringTerms + - meta + - response properties: - beaconId: - description: | - Identifier of the beacon, as defined in `Beacon`. - type: string - apiVersion: - description: | - Version of the API implemented by this Beacon. - type: string - example: 'v2.0' - filteringTerms: + meta: + $ref: '#/components/schemas/FilteringTermsResponseMeta' + response: + $ref: '#/components/schemas/FilteringTermsResponseContent' + FilteringTermsResponseContent: + type: object + required: + - results + properties: + resources: + type: array + items: + $ref: '#/components/schemas/OntologyResource' + filterTerms: type: array items: $ref: '#/components/schemas/FilteringTerm' @@ -3200,16 +3348,50 @@ components: type: object description: | Entities can be filtered using this term. - required: - - id properties: + type: + type: string + description: | + Either "numeric", "alphanumeric" or ontology/terminology full name. + example: 'Human Phenotype Ontology' id: description: | - CURIE syntax. + The field id in the case of numeric or alphanumeric fields, or the term id in the case of ontology or custom terms. CURIE syntax in the case of an ontology term. type: string - example: 'NCIT:C102872' + example: 'HP:0008773' label: description: | This would be the "preferred Label" in the case of an ontology term. type: string - example: 'Pharyngeal squamous cell carcinoma' + example: 'Aplasia/Hypoplasia of the middle ear' + OntologyResource: + type: object + description: + implementation of phenopackets resource object to describe ontology resources, full documentation found https://phenopackets-schema.readthedocs.io/en/latest/resource.html + required: + - id + properties: + id: + description: OBO ID representing the resource + type: string + example: hp + name: + description: The name of the ontology referred to by the id element + type: string + example: Human Phenotype Ontology + url: + description: Uniform Resource Locator of the resource + type: string + example: http://purl.obolibrary.org/obo/hp.owl + version: + description: The version of the resource or ontology used to make the annotation + type: string + example: 17-06-2019 + nameSpacePrefix: + description: The prefix used in the CURIE of an OntologyClass + type: string + example: HP + iriPrefix: + description: The full Internationalized Resource Identifier (IRI) prefix + type: string + example: http://purl.obolibrary.org/obo/HP_ From d0a8d5383156d042fb31b60cf88da1c3f928c54f Mon Sep 17 00:00:00 2001 From: Tom Shorter Date: Wed, 26 May 2021 14:13:40 +0100 Subject: [PATCH 2/6] Update beacon.yaml --- beacon.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/beacon.yaml b/beacon.yaml index ee21f23..927528b 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -135,7 +135,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/InfoResponse' + $ref: '#/components/schemas/DatasetResponse' /datasets/{id}/variant_interpretations: post: description: | @@ -3321,8 +3321,7 @@ components: FilteringTermsResponse: description: | - Response of a query over Beacon info. Use `InfoResponseContent` when querying the Beacon info endpoints, and `DatasetResponseContent` when querying the datasets endpoint. - type: object + Filtering terms available in this Beacon. required: - meta - response From 5fd06d7b95cfb1f803dc6277b3279966e8b90223 Mon Sep 17 00:00:00 2001 From: Tom Shorter Date: Wed, 26 May 2021 14:17:44 +0100 Subject: [PATCH 3/6] Update beacon.yaml --- beacon.yaml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/beacon.yaml b/beacon.yaml index 927528b..cc74ed9 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -3331,9 +3331,7 @@ components: response: $ref: '#/components/schemas/FilteringTermsResponseContent' FilteringTermsResponseContent: - type: object - required: - - results + type: object properties: resources: type: array From 7c82b90a39c51a00aaec28c89ddbdc89199a23be Mon Sep 17 00:00:00 2001 From: Tom Shorter Date: Wed, 26 May 2021 14:26:28 +0100 Subject: [PATCH 4/6] Update beacon.yaml --- beacon.yaml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/beacon.yaml b/beacon.yaml index cc74ed9..0ffbb53 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -1897,6 +1897,8 @@ components: type: object description: | Filter results to include records that contain a specific ontology term. + required: + - id properties: id: type: string @@ -1922,6 +1924,10 @@ components: description: | Filter results based on operators and values applied to alphanumeric fields. type: object + required: + - id + - operator + - value properties: id: type: string @@ -1950,6 +1956,8 @@ components: type: object description: | Filter results to include records that contain a custom term defined by this Beacon. + required: + - id properties: id: type: string @@ -3345,6 +3353,9 @@ components: type: object description: | Entities can be filtered using this term. + required: + - type + - id properties: type: type: string From 3623405ac515aec7901366eddb60223a6cb0a3e2 Mon Sep 17 00:00:00 2001 From: Tom Shorter Date: Tue, 22 Jun 2021 09:39:11 +0100 Subject: [PATCH 5/6] Update beacon.yaml --- beacon.yaml | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/beacon.yaml b/beacon.yaml index c02593c..cdb510a 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -135,7 +135,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/DatasetResponse' + $ref: '#/components/schemas/DatasetResponseContent' /datasets/{id}/variant_interpretations: post: description: | @@ -1251,7 +1251,7 @@ components: Rules for selecting records based upon the field values those records contain. Filters are seperated by the logical AND operator. type: array items: - oneOf: + anyOf: - $ref: '#/components/schemas/OntologyFilter' - $ref: '#/components/schemas/AlphanumericFilter' - $ref: '#/components/schemas/CustomFilter' @@ -1261,6 +1261,7 @@ components: Filter results to include records that contain a specific ontology term. required: - id + - includeDescendantTerms properties: id: type: string @@ -2828,7 +2829,10 @@ components: items: $ref: '#/components/schemas/OntologyResource' filterTerms: - + type: array + items: + $ref: '#/components/schemas/FilteringTerm' + FilteringTermResponseContent: type: object description: | @@ -2873,9 +2877,8 @@ components: example: 'Aplasia/Hypoplasia of the middle ear' OntologyResource: type: object - description: - implementation of phenopackets resource object to describe ontology resources, full documentation found https://phenopackets-schema.readthedocs.io/en/latest/resource.html - example: 'Pharyngeal squamous cell carcinoma' + description: implementation of phenopackets resource object to describe ontology resources, full documentation found https://phenopackets-schema.readthedocs.io/en/latest/resource.html + example: 'Pharyngeal squamous cell carcinoma' OntologyTerm: type: object From bc99a5883b871b1ed7fdf5840a71f7baae9b9ed5 Mon Sep 17 00:00:00 2001 From: Tom Shorter Date: Wed, 23 Jun 2021 14:10:40 +0100 Subject: [PATCH 6/6] Update beacon.yaml fixed ontologyResource + ontologyTerm objects --- beacon.yaml | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/beacon.yaml b/beacon.yaml index cdb510a..7b28c6c 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -2877,11 +2877,8 @@ components: example: 'Aplasia/Hypoplasia of the middle ear' OntologyResource: type: object - description: implementation of phenopackets resource object to describe ontology resources, full documentation found https://phenopackets-schema.readthedocs.io/en/latest/resource.html - example: 'Pharyngeal squamous cell carcinoma' - - OntologyTerm: - type: object + description: + implementation of phenopackets resource object to describe ontology resources, full documentation found https://phenopackets-schema.readthedocs.io/en/latest/resource.html required: - id properties: @@ -2909,6 +2906,14 @@ components: description: The full Internationalized Resource Identifier (IRI) prefix type: string example: http://purl.obolibrary.org/obo/HP_ + + OntologyTerm: + type: object + required: + - id + properties: + id: + type: string label: type: string DUODataUse: