Skip to content
This repository has been archived by the owner on Jul 18, 2022. It is now read-only.

Expansion of beacon.yaml to include specification for the query filters. #72

Open
wants to merge 7 commits into
base: develop
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
251 changes: 233 additions & 18 deletions beacon.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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/DatasetResponseContent'
/datasets/{id}/variant_interpretations:
post:
description: |
Get the variants interpretations (`VariantInterpretationResponse`) by
Expand Down Expand Up @@ -146,7 +168,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
Expand All @@ -157,7 +179,30 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/InfoResponse'
$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: |
Expand Down Expand Up @@ -1203,18 +1248,85 @@ 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:
anyOf:
- $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.
required:
- id
- includeDescendantTerms
properties:
id:
Tom-Shorter marked this conversation as resolved.
Show resolved Hide resolved
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:
Tom-Shorter marked this conversation as resolved.
Show resolved Hide resolved
description: |
Filter results based on operators and values applied to alphanumeric fields.
type: object
required:
- id
- operator
- value
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:
Tom-Shorter marked this conversation as resolved.
Show resolved Hide resolved
type: object
description: |
Filter results to include records that contain a custom term defined by this Beacon.
required:
- id
properties:
id:
type: string
description: |
Custom filter terms should contain a unique identifier.
example: 'demographic.ethnicity:asian'

RequestDatasets:
description: >-
Expand Down Expand Up @@ -1305,6 +1417,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.
Expand Down Expand Up @@ -1386,6 +1515,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
Expand Down Expand Up @@ -1425,8 +1563,6 @@ components:
$ref: '#/components/schemas/RequestDatasets'
filters:
$ref: '#/components/schemas/Filters'
customFilters:
$ref: '#/components/schemas/CustomFilters'
pagination:
$ref: '#/components/schemas/Pagination'
GenomicVariantFields:
Expand Down Expand Up @@ -1672,7 +1808,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
Expand Down Expand Up @@ -2656,6 +2809,30 @@ components:
default: null
example: "BAM format"


FilteringTermsResponse:
description: |
Filtering terms available in this Beacon.
required:
- meta
- response
properties:
meta:
$ref: '#/components/schemas/FilteringTermsResponseMeta'
response:
$ref: '#/components/schemas/FilteringTermsResponseContent'
FilteringTermsResponseContent:
type: object
properties:
resources:
type: array
items:
$ref: '#/components/schemas/OntologyResource'
filterTerms:
type: array
items:
$ref: '#/components/schemas/FilteringTerm'

FilteringTermResponseContent:
type: object
description: |
Expand All @@ -2669,6 +2846,7 @@ components:
type: integer
minimum: 0
results:

type: array
items:
$ref: '#/components/schemas/FilteringTerm'
Expand All @@ -2679,18 +2857,55 @@ components:
description: |
Entities can be filtered using this term.
required:
- type
- id
properties:
type:
Tom-Shorter marked this conversation as resolved.
Show resolved Hide resolved
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_

OntologyTerm:
type: object
Expand Down