Model defined records¶
A beacon instance will allow to retrieve data - in contrast to the aggregated
boolean and count responses - if it supports record granularity. The type of
document(s) is selected either through the REST path
or by specifying the entity through the requestedEntityId.
While any beacon can in principle choose its own data model - and thereby the schemas of records it supports - for biomedical genomics beacons we recommend the support of the Beacon default data model
Beacon Default Data Model¶
The Beacon v2 default data model provides a set of schemas for common data entities with a focus on biomedical genomics (although neither specific to medical application or human genomics per se).
In contrast to earlier versions of the protocol, the Beacon v2 default models provide the technical blueprint for rich, structured data responses to Beacon queries, such as annotated genomic variations, biosamples from which matched variants were retrieved or data about individuals and study cohorts, where available and authorized.
Detailed information is available through the Models Introduction and the default schemas documented from there.
Examples¶
This example is a single biosample response, e.g. as the result of a REST path
call (.../biosamples/{id}/). The response just demonstrates some of the available
biosample parameters and removes some technical/meta information for clarity.
Also, the sample contains fields which are not defined in the default
schema (such as icdoMorphology...); but although the use of custom fields is discouraged to
enhance interoperability, the use of additionalProperties is allowed so the
data itself remains schema conform.
{
"meta": {
"apiVersion": "v2.0.0",
"beaconId": "org.progenetix",
"receivedRequestSummary": {
...
},
"returnedGranularity": "record",
"returnedSchemas": [
{
"entityType": "biosample",
"schema": "https://progenetix.org/services/schemas/biosample/"
}
],
},
"responseSummary": {
"exists": true,
"numTotalResults": 1
},
"response": {
"resultSets": [
{
"exists": true,
"setType": "dataset",
"id": "progenetix",
"resultsCount": 1,
"results": [
{
"id": "pgxbs-kftvi9i0",
"individualId": "pgxind-kftvi9i0",
"notes": "Primary Tumor",
"biosampleStatus": {
"id": "EFO:0009656",
"label": "neoplastic sample"
},
"collectionMoment": "P44Y1M24D",
"sampleOriginType": {
"id": "OBI:0001479",
"label": "specimen from organism"
},
"dataUseConditions": {
"id": "DUO:0000004",
"label": "no restriction"
},
"externalReferences": [
{
"id": "pgx:TCGA.933b9daf-a5bf-46cf-92b6-5ddd8279919c",
"label": "TCGA case_id"
},
{
"id": "pgx:TCGA.TCGA-76-6663",
"label": "TCGA submitter_id"
},
{
"id": "pgx:TCGA.005cb7ce-5050-43aa-85ff-cd56ed830535",
"label": "TCGA sample_id"
},
{
"id": "pgx:TCGA.GBM",
"label": "TCGA GBM project"
}
],
"histologicalDiagnosis": {
"id": "NCIT:C3058",
"label": "Glioblastoma"
},
"icdoMorphology": {
"id": "pgx:icdom-94403",
"label": "Glioblastoma, NOS"
},
"icdoTopography": {
"id": "pgx:icdot-C71.9",
"label": "Brain, NOS"
},
"pathologicalStage": {
"id": "NCIT:C92207",
"label": "Stage Unknown"
},
"sampleOriginDetail": {
"id": "UBERON:0000955",
"label": "brain"
},
"updated": "2020-09-10 17:44:04.888000"
}
]
}
]
}
}
Alternative Data Models¶
In principle, the separation of framework and models allows for different models in domains outside of the genomics focussed Beacon v2 realm, e.g. “Imaging Beacon”, to be built using the same Framework.