Closed mbaudis closed 2 years ago
Correct me if I am wrong. These schemas are for the results found in
beacon-framework-v2/responses/sections/beaconResultsets.json
:
"definitions": {
"ResultsetInstance": {
"properties": {
"results": {
"type": "array",
"items": {
"type": "object"
},
Right?
D.
@redmitry Yes. Shorter version of my question: Is there any need to stick then in models
to the currently demonstrated structure (i.e. biosamples/defaultSchema.json
or is it fine to do whatever, as long as the configuration points to the right schema?
"biosample": {
"id": "biosample",
"name": "Biological Sample",
"ontologyTermForThisType": {
"id": "NCIT:C70699",
"label": "Biospecimen"
},
"partOfSpecification": "Beacon v2.0.0-draft.4",
"description":...",
"defaultSchema": {
"id": "Biosample",
"name": "Progenetix schema for a biological sample",
"referenceToSchemaDefinition": "https://progenetix.org/services/schemas/Biosample",
"schemaVersion": "v2021-03-05"
},
"additionallySupportedSchemas": []
},
... but also: should then be organized better in model definitions.
I'm not sure why beacon points to the default schemas, other API's expect that you have read the docs before using it and the beacon docs can contain all the info that's needed about the default schemas in a much more readable format. If using beacon through a front end then the front end should make clear how it can be used, e.g. descriptions, examples and value types, then displaying this info nicely when requested.
The only use case I can see for declaring your schemas is for alternate schemas where the user might not be familiar with the schemas a beacon uses and would therefore want to look at them. The user wouldn't be likely to query a beacon directly, instead users will use front end interfaces. If we assume that the front end was developed in isolation from a beacon implementation (and not built around the available schemas within a beacon) then the front end would need to know what schemas can be used in a beacon, the default schemas should be available in the front end systems as these are publicly available so only the custom schemas need to be defined by the beacon.
If we made the change to only showing the alternate schemas then beacons which use nothing but the default schemas don't need to make available any schemas, which is much easier for them to do and makes the implementation less frustrating.
Somehow draft-4 avoids using concrete response objects reusing generic BeaconRequestBody
and BeaconResultsetsResponse
.
Note that we still need to define specific RequestParameters (i.e. requestParameters.json). ... by the way the file looks erroneous.
I have a feeling that Beacon implementers expected to provide strict OpenAPI schemas specific for each endpoint defined in each endpoints.json
...
My comments on the above questions:
In the current models one provides a default schema (e.g. for
biosample
). I struggle a bit with the implementation here:defaultSchema
itself is not named for its content which is irritating (but understandable if this would be a required name - but is this so? see below)beaconConfiguration
, so it IMO doesn't make sense to have them defined by their default location?./common
or elsewhere (right now e.g. using absolute references to components in framework ... common, which are neither necessarily stable nor handy; splitting over different repos etc.) it still would be better to have this asschemas
for everything (with external references for non-Beacon schemas) So is this just me mis-reading the need for adefaultSchema
inside of the endpoints collections, and is this in fact flexible (e.g. one can use a separate schema hierarchy - as we do now - and just point to this inbeaconConfiguration
)? Or if the default file is required - is there a way to alias complete schemas in JSON Schema?Apologies if answers seem obvious; not to me right now ...