Generic Resultsets

[redmitry]

This commit open a possibility to redefine the Resultset content (e.g. specify that the message content is a 'biosamples' object).

[redmitry]

This commit doesn't break the specification, but enforce JSON Schema 2020-12 usage (which is already in the spec.).

Default resultsEntryType is still JSON object, but it may be overridden:

{
  "$comment": "generic test",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
     "biosamples": {
       "$dynamicAnchor": "resultsEntryType",
       "$ref": "https://raw.githubusercontent.com/redmitry/beacon-v2/redmitry-generalize-resultset/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
      }
  },
  "$ref" : "https://raw.githubusercontent.com/redmitry/beacon-v2/redmitry-generalize-resultset/framework/json/responses/beaconResultsetsResponse.json"
}

This way endpoints (e.g. OpenAPI) may better define the type of results they return - in the above we define a response which must contain only 'biosamples' results.

Best,

Dmitry

[mbaudis]

@redmitry But isn't the returnedSchemas part in meta doing this?

beacon-v2/framework/src/responses/sections/beaconResponseMeta.yaml

Line 11 in 47af89c

returnedSchemas:

At least that's what I thought & we're doing it like that:

https://progenetix.org/beacon/biosamples?testMode=true

        "returnedGranularity": "record",
        "returnedSchemas": [
            {
                "entityType": "biosample",
                "schema": "https://progenetix.org/services/schemas/biosample/"
            }
        ],

I might be wrong, though ╮(╯▽╰)╭

[redmitry]

@redmitry But isn't the returnedSchemas part in meta doing this?

Yes, but. Schema validators can't validate on metadata hints.
Currently I may validate the protocol message down to the results. Then, I have to go result by result validating each result over the schema. The change allows re-define the schema for the entryTypes so I can validate entire message with data in one pass.

This is especially useful for OpenAPI definitions - OpenAPI tools just have no knowledge about the entryTypes, so currently for them biosamples endpoint has no difference to the variations.

presentation

Cheers,

D.

[jrambla]

@redmitry could you provide an example of how this would looke like in the model, where, I assume, the schema is "de-generalized"?

[redmitry]

@redmitry could you provide an example of how this would looke like in the model, where, I assume, the schema is "de-generalized"?

{
  "$comment": "generic test",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
     "biosamples": {
       "$dynamicAnchor": "resultsEntryType",
       "$ref": "https://raw.githubusercontent.com/redmitry/beacon-v2/redmitry-generalize-resultset/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
      }
  },
  "$ref" : "https://raw.githubusercontent.com/redmitry/beacon-v2/redmitry-generalize-resultset/framework/json/responses/beaconResultsetsResponse.json"
}

The "de-generalization" here is:

  "$defs": {
     "biosamples": {
       "$dynamicAnchor": "resultsEntryType",
       "$ref": "https://raw.githubusercontent.com/redmitry/beacon-v2/redmitry-generalize-resultset/models/json/beacon-v2-default-model/biosamples/defaultSchema.json"
      }
  }

which enforces that "resultsEntryType" must be biosamples schema.
It overrides the default "resultsEntryType" type: "object", so JSON Schema validators will validate "items" with ".../biosamples/defaultSchema.json"

"results": {
  "$defs": {
    "defaultResultsEntryType": {
      "$dynamicAnchor": "resultsEntryType",
      "type": "object"
    }
  },
  "items": {
    "$dynamicRef": "#resultsEntryType"
  },
  "minItems": 0,
  "type": "array"
}

Unless someone overrides the "resultsEntryType" $dynamicAnchor the value of items is "object".

Cheers,

Dmitry

[jrambla]

Thanks! In which Model file would that "de-generalized" schema reside?

[redmitry]

Thanks! In which Model file would that "de-generalized" schema reside?

Ah! now understand the question.
Outside of the specification.
This could be done in the OpenAPI endpoint specification - so endpoints will restrict accepted endpoint entryTypes.
Technically the /map could have a schema-per-endpoint, but I do not like this because could finally replicate OpenAPI...

Dmitry

[jrambla]

Given that we are aiming to generate OpenAPI documents from the actual beacon instance, wouldn't it be better to include the information in /map or a similar place?

[redmitry]

Given that we are aiming to generate OpenAPI documents from the actual beacon instance, wouldn't it be better to include the information in /map or a similar place?

IF we gonna generate OpenAPI we don't need to put it anywhere. It could be perfectly generated because we know entryTypes schemas.