Open mbaudis opened 1 year ago
I agree that meta is overly verbose, I'd be happy for all of it to be optional.
Much of the bulk of the v2 spec seems aimed at full-response beacons, so those of us working with counts run up against the occasional odd requirement:
returnedSchemas
isn't particularly meaningful, since no actual schema is returned, requestedGranularity
, the only meaningful option would be to downgrade to boolean, which users can do themselves by reading the required field responseSummary.exists
.... and so on.
The rationale behind the verbosity:
On the returnedGranularity, the rationale is similar;
In summary, the goals are:
Having said so, some of the points need improvement, and the returnedSchema in boolean or count responses could be one of them.
Beacon v2 responses are very chatty & require many parameters in their
meta
elements which only serve verification purposes (e.g. that the beacon could interpret the query ...). This, however, makes it rather hard to demonstrate the simplicity of especially v2 Boolean and count responses. Below is the minimal response example for a variant query which I've used in the documentation - all parameters are required:Not necessary:
receivedRequestSummary.apiVersion
,receivedRequestSummary.requestedSchemas
,requestedGranularity
are known by the client and the beacon's returned values are stated separatelyreceivedRequestSummary.pagination
doesn't make sense for Boolean and count responses since it is for record paginationMaybe, but:
receivedRequestSummary.requestedSchemas
andreturnedSchemas
basically point to the requirement of having a schema for the entity. However, when e.g. doing the basic "beacon from a VCF" - which at least for SNVs is well understood - there is no inherent variant schema to point to, based on the source data.Helpful for debugging:
receivedRequestSummary.requestParameters
So while it is obviously beneficial to have a full framework + default/alternative model implementation, the current use of required parameters makes it overly complex & scary for resource owners wanting to add a "v1-style" beacon (and thereby enriching the landscape for aggregators etc.). Minimal response IMO (and
receivedRequestSummary
is an edge case here since it won't be interpreted, mostly):Discuss!