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

[Tom-Shorter]

The /filtering_terms endpoint has been expanded to include the infoResponse wrapper to conform with all other endpoints.

Query filters are now of three types:

• ontologyFilters
• alphaNumericFilters
• customFilters

An OntologyResource object has been included in this specification. This object is included as a way of providing information about an ontology which is described externally to the beacon and/or dataset, such as HPO or MeSH. The OntologyResource is based off of the Phenopackets resource object specifications.

A new endpoint, un-related to filters has been proposed for completeness - /datasets/{id}, this is due to /datasets/{id}/filtering_terms being created as a new filters related endpoint which describes filters used by datasets identified by {id}. The contents of /datasets/{id} has been set as a subset of the contents of /datasets where only information relating to the dataset as identified by {id} is displayed.

The existence of /datasets/{id} is not required for the rest of the specification to function correctly and the contents of the endpoint can be freely modified as desired, what is detailed below is a suggestion only as having /datasets and /datasets/{id}/filtering_terms but not including a definition of /datasets/{id} seems incomplete and could cause confusion when implementing.

[Tom-Shorter]

With cohorts being an area of interest for beaco it might be worth considering the need for an endpoint such as /cohorts/{id}/filtering_terms as well.

[sdelatorrep]

Nice work, @Tom-Shorter, I've just done some small comments :)

[mbaudis]

AFAIK good. Adds complexity, but most is optional. Adds implementation work :-)

[sdelatorrep]

Hi @Tom-Shorter! I think everything is fine, but there are conflicts with branch develop. I tried to solve them, but I'm a bit confused with some, so I think it's better if you do it yourself. Thanks!

[Tom-Shorter]

Hi @Tom-Shorter! I think everything is fine, but there are conflicts with branch develop. I tried to solve them, but I'm a bit confused with some, so I think it's better if you do it yourself. Thanks!

Sorry @sdelatorrep, I must have missed the notification email about your comment, I believe I've fixed all of the conflicts now.

[jrambla]

@Tom-Shorter
Hi!
I could be mistaken, but I've spotted 3 potential errors in the resulting YAML.

• Line 138 is an incorrect reference. "DatasetResponse" doesn't exist
• Line 2830 is an unfinished entry "filteringTerms:"
• Line 2878 is incorrectly indented

Also.
Line 1254 should be "anyOf" instead of "oneOf". The latter requires that only 1 schema matches the tested document, and, in the current models, "OntologyFilter" and "CustomFilter" are having the same schema, based on "required". Therefore the validator is unable to discriminate and it throws an error.

[Tom-Shorter]

Thanks @jrambla, I believe those problems should now be fixed (swagger hub doesn't seem to be working ATM but other online validators show no problems)

I'll have to speak with Tim about the two filter types, I don't think there is a way to update the required parameters without enforcing either similarity or descendant term matching, both of which should be optional

[Tom-Shorter]

Hi @jrambla

Those problems should be resolved, includeDescendantTerms is now a required parameter, along with id, for the ontology filter