Question: `defaultSchema.json`, aliases, local $refs ...

[mbaudis]

In the current models one provides a default schema (e.g. for biosample). I struggle a bit with the implementation here:

• In principle, different endpoints could make use of the same schema which has to be defined multiple times then
• the 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)
• the location for the default schemas is defined in the beaconConfiguration, so it IMO doesn't make sense to have them defined by their default location?
• the schemas themselves will have references to components defined locally in ./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 as schemas for everything (with external references for non-Beacon schemas) So is this just me mis-reading the need for a defaultSchema 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 in beaconConfiguration)? 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 ...

[redmitry]

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.

[mbaudis]

@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": []
    },

[mbaudis]

... but also: should then be organized better in model definitions.

[Tom-Shorter]

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.

[redmitry]

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 ...

[jrambla]

My comments on the above questions:

1. The Beacon Framework knows nothing about the models and if they are using any external schema as the default schema. Hence a given model could simply reference to different schemas (SchemaBlocks, Phenopackets, FHIR...) as the defaul schema for a given entry type. As the default schema is the one by default, it must be declared somewhere. Using the documentation would not be enough if we expect to automate some operations in the context of networks and so on.
2. 2. The default schemas must be findable somewhere, indeed just for testing an implementation/document against it. As these are the default schemas for Model v2, we named it like that. It seemed to me a natural (non-irritating) way of naming them. We could have used another organization and another naming, but this was the one chosen at that time. If we agree that all of them should be in a common/central repo and the Model referencing them, that would be also OK. For me that step should happen / had to happen when the schemas are stable enough,
3. As we were expecting that different Beacon instances implement only some entry types (not all), we organized the folders for simple deleting one folder would get rid of most of the stuff for that entry type. Probably, using a common/central schema repo would be equally easy for that purpose (I need to review the details).