-
Notifications
You must be signed in to change notification settings - Fork 5
/
vp_api_v2.0.yml
1122 lines (1121 loc) · 37.5 KB
/
vp_api_v2.0.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.1
info:
title: Virtual platform Beacon API
x-beaconVersion: v2.0
description: EJPRD virtual platform data record APIs
contact:
email: admin@cafevariome.org
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: v2.0
servers:
- url: https://rdnexusdev.molgeniscloud.org/cv2/BeaconAPI/
description: Development server
paths:
/info:
get:
summary: "Get information regarding this beacon."
tags:
- Informational Endpoints
responses:
200:
$ref: "#/components/schemas/InfoResponse"
/filtering_terms:
get:
summary: "Get the valid filtering terms to be used in querying/handled by this beacon."
tags:
- Informational Endpoints
responses:
200:
$ref: "#/components/schemas/FilteringTermsResponse"
/map:
get:
summary: "Get the list of endpoints included in this beacon i.e., individuals."
tags:
- Informational Endpoints
responses:
200:
$ref: "#/components/schemas/MapResponse"
/service-info:
get:
summary: "Get information about the beacon using GA4GH ServiceInfo format."
tags:
- Informational Endpoints
responses:
200:
$ref: "#/components/schemas/ServiceInfoResponse"
/configuration:
get:
summary: "Get the configuration of this beacon."
tags:
- Informational Endpoints
responses:
200:
$ref: "#/components/schemas/ConfigurationResponse"
/entry_types:
get:
summary: "Get the list of beacon entry types."
tags:
- Informational Endpoints
responses:
200:
$ref: "#/components/schemas/EntryTypesResponse"
/individuals:
post:
summary: "Request to retrieve count of individuals from a data source (i.e. patients)."
tags:
- Query Endpoints
operationId: individuals_request
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/IndividualRequest"
required: true
responses:
200:
$ref: "#/components/schemas/IndividualResponse"
400:
description: "Input data malformed"
content: {}
403:
description: "The data source does not allow this API call"
content: {}
security:
- apiAuth: []
/biosamples:
post:
summary: "Request to retrive count of biosamples from a data source."
tags:
- Query Endpoints
operationId: biosamples_request
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/BiosampleRequest"
required: true
responses:
200:
$ref: "#/components/schemas/IndividualResponse"
400:
description: "Input data malformed"
content: {}
403:
description: "The data source does not allow this API call"
content: {}
security:
- apiAuth: []
/catalogs:
post:
summary: "Request to retrive record(s) of resource(s) within a catalog/biobank/registry."
tags:
- Query Endpoints
operationId: catalogs_request
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CatalogRequest"
required: true
responses:
200:
$ref: "#/components/schemas/CatalogResponse"
400:
description: "Input data malformed"
content: {}
403:
description: "The data source does not allow this API call"
content: {}
security:
- apiAuth: []
components:
schemas:
IndividualRequest:
required:
- meta
- query
type: object
properties:
meta:
$ref: "#/components/schemas/MetaContent"
query:
$ref: "#/components/schemas/IndividualRequestQuery"
description: "Request to return individuals count for given CDEs as filters"
BiosampleRequest:
required:
- meta
- query
type: object
properties:
meta:
$ref: "#/components/schemas/MetaContent"
query:
$ref: "#/components/schemas/BiosampleRequestQuery"
description: "Request to return individuals count for given CDEs as filters"
CatalogRequest:
required:
- meta
- query
type: object
properties:
meta:
$ref: "#/components/schemas/MetaContent"
query:
$ref: "#/components/schemas/CatalogRequestQuery"
description: "Request to return resources for given CDEs as filters"
IndividualRequestQuery:
type: object
properties:
filters:
$ref: "#/components/schemas/IndividualRequestFilter"
description: "Input of the query"
IndividualRequestFilter:
type: array
items:
anyOf:
- $ref: "#/components/schemas/IndividualAlphanumericRequestFilter"
- $ref: "#/components/schemas/IndividualOntologyRequestArrayFilter"
IndividualAlphanumericRequestFilter:
required:
- id
- operator
- value
type: object
properties:
id:
type: string
description: >
Concept ID of CDEs.
Allowed terms:
* `NCIT_C28421` - Sex
* `data_2295` - Causative Gene(s)
* `NCIT_C83164` - Age this year
* `NCIT_C124353` - Symptom Onset
* `NCIT_C156420` - Age at diagnosis
example: "NCIT_C28421"
operator:
type: string
description: |
This is an advance filter option to include comparison operators in the query.
* For `alphanumeric filter`, only `'='` is allowed.
* For `numeric filter`, `'=,>,>=,<,<='` are allowed.
example: "="
value:
anyOf:
- $ref: "#/components/schemas/IndividualStringValue"
- $ref: "#/components/schemas/IndividualArrayValues"
description: "Query parameters to filter individuals based on CDEs."
IndividualStringValue:
type: string
example: '"NCIT_C17998"'
description: |
The actual value of the CDE in string format. Allowed values:
* For `NCIT_C28421`(Sex):
* `NCIT_C16576`, (Female)
* `NCIT_C20197`, (Male)
* `NCIT_C124294`, (Undetermined)
* `NCIT_C17998` (Unknown)
* Ex: \"NCIT_C16576\"
* For `data_2295`(Causative Gene):
* Any HGNC Gene symbol or an array of HGNC Symbols.
* Ex: \"FOXRED1\"
* For `NCIT_C83164`(Age this year):
* Any age as an integer
* Ex: 13
* For `NCIT_C124353`(Symptom Onset):
* Any integer
* Ex: 5
* For `NCIT_C156420`(Age at diagnosis):
* Any integer
* Ex: 8
IndividualArrayValues:
type: array
items:
type: string
example: '["NCIT_C16576","NCIT_C20197"]'
description: |
An array of allowed CDE value(s) in string format.
IndividualOntologyRequestArrayFilter:
required:
- id
type: object
properties:
id:
anyOf:
- type: string
- type: array
items:
type: string
description: "Array of string orpha ids."
example: '"ordo:Orphanet_558" or ["ordo:Orphanet_558","ordo:Orphanet_773","ordo:Orphanet_12345"]'
description: |
Concept ID of CDEs using Orpha ontology format.
Allowed values:
* For `Disease or Disorder`: A single value or an array of orphanet terms. e.g. \"ordo:Orphanet_558\" or [\"ordo:Orphanet_558\", \"ordo:Orphanet_773\"]
CatalogRequestQuery:
type: object
properties:
filters:
$ref: "#/components/schemas/CatalogRequestFilter"
description: "Input of the query"
CatalogRequestFilter:
type: array
items:
anyOf:
- $ref: "#/components/schemas/CatalogAlphanumericRequestFilter"
- $ref: "#/components/schemas/CatalogOntologyRequestArrayFilter"
CatalogAlphanumericRequestFilter:
required:
- id
- operator
- value
type: object
properties:
id:
type: string
description: >
Concept ID of Resource Metadata Schema.
Allowed terms:
* `dct:identifier` => `ID`
* `dct:title` => `Name`
* `dct:description` => `Description`
* `rdf:type` => `Resource Types`
* `dct:spatial` => `Country`
example: "resourceTypes"
operator:
type: string
description: "This is an advanced filter option to compare filter IDs with filter values using '=' operator in the query."
example: "="
value:
anyOf:
- $ref: "#/components/schemas/CatalogStringValue"
- $ref: "#/components/schemas/CatalogArrayValues"
description: "Query parameters to filter individuals based on CDEs."
CatalogStringValue:
type: string
example: "ejprd:PatientRegistry"
description: |
The actual value of the Resource Metadata Schema property for resources in string format. Allowed values:
* For `dct:identifier`: any identifier of the resource as a string.
* For `dct:title`: name of the resource as a string.
* For `dct:description`: description of the resource as a string.
* Note that you can also use wildcards. Ex: %genome comparison% returns list of records with description matching to genome comparison.
* For `rdf:type`: any one of the following string values are allowed -
* ejprd:Biobank,
* ejprd:PatientRegistry,
* ejptd:Guideline
* dcat:Dataset
* For `dct:spatial`: ISO 3166-1 alpha-2 format string (e.g. IT, FR, NL)
CatalogArrayValues:
type: array
items:
type: string
example: "[ejprd:Biobank, ejprd:PatientRegistry]"
description: |
An array of value taken from the allowed values for the filter
CatalogOntologyRequestArrayFilter:
required:
- id
type: object
properties:
id:
anyOf:
- type: string
- type: array
items:
type: string
description: "Array of string orpha ids."
example: '"ordo:Orphanet_558" or ["ordo:Orphanet_558","ordo:Orphanet_773","ordo:Orphanet_12345"]'
description: |
Ontology term for the specific Metadata Schema term.
* For `Disease or Disorder`: A single value or an array of orphanet terms. e.g. \"ordo:Orphanet_558\" or [\"ordo:Orphanet_558\", \"ordo:Orphanet_773\"]
* For `Phenotype`: a single value or an array of HPO terms
BiosampleRequestQuery:
type: object
properties:
filters:
$ref: "#/components/schemas/BiosampleRequestFilter"
description: "Input of the query"
BiosampleRequestFilter:
type: array
items:
anyOf:
- $ref: "#/components/schemas/BiosampleAlphanumericRequestFilter"
- $ref: "#/components/schemas/BiosampleOntologyRequestArrayFilter"
BiosampleAlphanumericRequestFilter:
required:
- id
- operator
- value
type: object
properties:
id:
type: string
description: >
Concept ID for biosamples
Allowed terms:
* `obo:NCIT_C28421` - Sex
* `obo:NCIT_C83164` - Year of birth
* `obo:NCIT_C156420` - Age at diagnosis
* `obo:NCIT_C70713` - Biospecimen type
example: "obo:NCIT_C70713"
operator:
type: string
description: "This is an advanced filter option to compare filter IDs with filter values using '=' operator in the query."
example: "="
value:
anyOf:
- $ref: "#/components/schemas/BiosampleStringValue"
- $ref: "#/components/schemas/BiosampleArrayValues"
description: "Query parameters to filter individuals based on CDEs."
BiosampleStringValue:
type: string
description: |
The actual value of the CDE in string format. Allowed values:
* For `obo:NCIT_C28421`(Sex):
* `NCIT_C16576`, (Female)
* `NCIT_C20197`, (Male)
* `NCIT_C124294`, (Undetermined)
* `NCIT_C17998` (Unknown)
* Ex: \"NCIT_C16576\"
* For `NCIT_C83164`(Year of birth):
* Any age as an integer
* Ex: 13
* For `NCIT_C156420`(Age at diagnosis):
* Any integer
* Ex: 8
* For obo:NCIT_C70713 (Biospecimen type):
* OBI_0000655 (blood specimen)
* OBI_0002512 (bone marrow)
* OBIB_0000036 (buffy coat)
* CL_2000001 (peripheral blood mononuclear cell)
* OBI_0100016 (blood plasma specime)
* OBI_0100017 (blood serum)
* UBERON_0007795 (ascites fluid)
* OBI_0002502 (cerebrospinal fluid)
* OBI_0002507 (saliva)
* OBI_0002503 (feces)
* OBI_0000651 (urine)
* OBI_0002599 (swab)
* OBI_2000009 (bodily fluid specimen)
* OBI_1200000 (FFPE specimen)
* OBI_0000922 (frozen specimen)
* OBI_0001472 (specimen with known storage state)
* OBI_0001051 (DNA extract)
* OBI_0000880 (RNA extract)
* OBI_0001479 (specimen from organism)
BiosampleArrayValues:
type: array
items:
type: string
example: '["OBI_0000655", "OBI_0001051"]'
description: |
An array of possible string values for the specific filter
BiosampleOntologyRequestArrayFilter:
required:
- id
type: object
properties:
id:
anyOf:
- type: string
- type: array
items:
type: string
description: "Array of string orpha ids."
example: '"ordo:Orphanet_558" or ["ordo:Orphanet_558","ordo:Orphanet_773","ordo:Orphanet_12345"]'
description: |
Concept ID of Biosamples term using Orpha ontology format.
Allowed values:
* For `Disease or Disorder`: A single value or an array of orphanet terms. e.g. \"ordo:Orphanet_558\" or [\"ordo:Orphanet_558\", \"ordo:Orphanet_773\"]
InfoResponse:
required:
- meta
- response
type: object
properties:
meta:
$ref: "#/components/schemas/MetaContent"
response:
$ref: "#/components/schemas/InfoResponseContent"
description: |
Respond with information regarding this Beacon.
FilteringTermsResponse:
required:
- meta
- response
properties:
meta:
$ref: "#/components/schemas/MetaContent"
response:
$ref: "#/components/schemas/FilterTermsResponseContent"
FilterTermsResponseContent:
required:
- filteringTerms
properties:
filteringTerms:
$ref: "#/components/schemas/FilterTermsResponse"
FilterTermsResponse:
description: |
List of filtering terms for querying this Beacon.
required:
- id
- type
type: object
properties:
id:
type: string
description: |
The field id in the case of numeric or alphanumeric fields, or the term id in the case of ontology or custom terms. CURIE syntax in the case of an ontology term.
example: NCIT_C28421
type:
type: string
description: |
Either "custom", "alphanumeric" or ontology/terminology full name.
example: alphanumeric or ontology or custom
label:
type: string
description: |
This would be the "preferred Label" in the case of an ontology term.
example: Symptom Onset
ServiceInfoResponse:
description: |
Respond with the Service Info of this Beacon.
MapResponse:
description: |
Respond with the list of available query endpoints in this Beacon.
EntryTypesResponse:
required:
- meta
- response
type: object
properties:
meta:
$ref: "#/components/schemas/MetaContent"
response:
$ref: "#/components/schemas/ETResponseContent"
description: |
Respond with the entry types available in this Beacon Implementation.
ConfigurationResponse:
description: |
Respond with this Beacon's configuration information.
MetaContent:
description: |
Information about the response that could be relevant for the Beacon client in order to interpret the results.
required:
- apiVersion
type: object
properties:
apiVersion:
type: string
description: |
Version of the API.
example: v2.0
beaconId:
type: string
description: |
Identifier of the beacon, as defined in Beacon, in reverse domain name notation.
example: BeaconAPI.cv2.rdnexusdev.molgeniscloud.org
returnedSchemas:
type: object
description: |
Set of schemas used in the response to a request.
properties:
entityType:
type: string
schema:
type: string
requestedSchemas:
type: array
description: |
ids of the schemas requested for the record in the response. For each type of entries there can be multiple schemas.
Available schemas in the beacon are specified in the /entry_types endpoint. If not specified the default one is used
items:
type: string
IndividualsMetaResponseContent:
description: |
Information about the response that could be relevant for the Beacon client in order to interpret the results.
required:
- apiVersion
- beaconId
- returnedGranularity
type: object
properties:
apiVersion:
type: string
description: |
Version of the API.
example: v2.0
beaconId:
type: string
description: |
Identifier of the beacon, as defined in Beacon, in reverse domain name notation.
example: BeaconAPI.cv2.rdnexusdev.molgeniscloud.org
receivedRequestSummary:
required:
- apiVersion
- requestedGranularity
- requestedSchemas
type: object
description: |
Section of the response that summarize the request with the following fields received as its been interpreted by the Beacon server. This could also just return the complete Beacon request made by the user.
properties:
apiVersion:
type: string
filters:
type: object
description: |
Filters as submitted in the request.
$ref: "#/components/schemas/IndividualRequestFilter"
requestedGranularity:
type: string
example: boolean, count, aggregated, record
default: count
requestedSchemas:
type: object
description: |
Set of schemas to be used in the response to a request.
properties:
entityType:
type: string
schema:
type: string
returnedGranularity:
type: string
example: boolean, count, aggregated, record
default: count
returnedSchemas:
type: object
description: |
Set of schemas to be used in the response to a request.
properties:
entityType:
type: string
schema:
type: string
InfoResponseContent:
description: |
Metadata describing a Beacon instance.
required:
- apiVersion
- environment
- id
- name
- organisation
properties:
apiVersion:
type: string
description: |
Version of the API provided by the Beacon.
example: v2.0
environment:
type: string
description: |
Environment the service is running in. Use this to distinguish between production, development and testing/staging deployments. Allowed: prod, test, dev, staging
example: dev
id:
type: string
description: |
Unique identifier of the Beacon. Use reverse domain name notation.
name:
type: string
description: |
Name of the Beacon.
organisation:
type: object
description: |
Organization owning the Beacon.
required:
- id
- name
properties:
id:
type: string
description: |
Unique identifier of the organization.
name:
type: string
description: |
Name of the organization.
ETResponseContent:
required:
- entryTypes
type: object
properties:
entryTypes:
required:
- Individuals
type: object
description: |
List of entry types.
properties:
Individuals:
description: |
Definition of an element or entry type including the Beacon v2 required and suggested attributes. This schema purpose is to describe each type of entities included in this beacon, hence Beacon clients could have some metadata about such entities.
required:
- defaultSchema
- id
- name
- ontologyTermForThisType
- partOfSpecification
type: object
properties:
defaultSchema:
description: |
Definition of an annotated URL address or a file reference.
required:
- id
- name
- referenceToSchemaDefinition
properties:
id:
type: string
description: |
A (unique) identifier of the element.
example: Individuals
name:
type: string
description: |
A distinctive name for the element.
example: Individuals
referenceToSchemaDefinition:
type: string
description: |
Conforming Schema of the element.
example: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2-Models/main/BEACON-V2-draft4-Model/individuals/defaultSchema.json
id:
description: |
A unique identifier of the element.
type: string
example: Individuals
name:
description: |
A distinctive name for the element.
type: string
example: Individuals
ontologyTermForThisType:
description: |
Definition of an ontology term.
type: object
required:
- id
properties:
id:
description: |
A CURIE identifier as `id` for ontology term.
example: NCIT:C25190
type: string
partOfSpecification:
description: |
This label is to group together entry types that are part of the same specification.
type: string
example: Beacon v2.0
description: |
Respond with a list of entry types conforming to Beacon v2 spec.
IndividualResponse:
description: |
Response of a query over individuals counts.
required:
- meta
- response
- responseSummary
type: object
properties:
meta:
$ref: "#/components/schemas/IndividualsMetaResponseContent"
response:
required:
- resultSets
properties:
resultSets:
$ref: "#/components/schemas/IndividualsResults"
responseSummary:
$ref: "#/components/schemas/IndividualResponseContent"
info:
description: |
Beacon only responds with this info object if there are any unsupported filters in the query.
$ref: "#/components/schemas/WarningResponse"
BiosampleResponse:
description: |
Response of a query over individuals counts.
required:
- meta
- response
- responseSummary
type: object
properties:
meta:
$ref: "#/components/schemas/IndividualsMetaResponseContent"
response:
required:
- resultSets
properties:
resultSets:
$ref: "#/components/schemas/IndividualsResults"
responseSummary:
$ref: "#/components/schemas/IndividualResponseContent"
info:
description: |
Beacon only responds with this info object if there are any unsupported filters in the query.
$ref: "#/components/schemas/WarningResponse"
CatalogResponse:
description: |
Response of a query over records of catalogs.
required:
- meta
- responseSummary
- response
type: object
properties:
meta:
$ref: "#/components/schemas/CatalogsMetaResponseContent"
responseSummary:
$ref: "#/components/schemas/CatalogsResponseSummaryContent"
response:
$ref: "#/components/schemas/CatalogsResponseContent"
info:
description: |
Beacon only responds with this info object if there are any unsupported filters in the query.
$ref: "#/components/schemas/WarningResponse"
CatalogsMetaResponseContent:
description: |
Information about the response that could be relevant for the Beacon client in order to interpret the results.
required:
- apiVersion
- beaconId
- returnedGranularity
type: object
properties:
apiVersion:
type: string
description: |
Version of the API.
example: v2.0
beaconId:
type: string
description: |
Identifier of the beacon, as defined in Beacon, in reverse domain name notation.
example: BeaconAPI.cv2.rdnexusdev.molgeniscloud.org
receivedRequestSummary:
required:
- apiVersion
- requestedGranularity
- requestedSchemas
type: object
description: |
Section of the response that summarize the request with the following fields received as its been interpreted by the Beacon server. This could also just return the complete Beacon request made by the user.
properties:
apiVersion:
type: string
filters:
type: object
description: |
Filters as submitted in the request.
$ref: "#/components/schemas/IndividualRequestFilter"
requestedGranularity:
type: string
example: boolean, count, aggregated, record
default: count
requestedSchemas:
type: object
description: |
Set of schemas to be used in the response to a request.
properties:
entityType:
type: string
schema:
type: string
returnedGranularity:
type: string
example: boolean, count, aggregated, record
default: count
returnedSchemas:
type: object
description: |
Set of schemas used in the response to a request.
properties:
entityType:
type: string
schema:
type: string
WarningResponse:
description: |
When an implementation is responding with a partial query match, this section lets the requestor know if any filter(s)/value(s) are not applied to the query.
required:
- warnings
type: object
properties:
warnings:
required:
- unsupportedFilters
type: object
properties:
unsupportedFilters:
type: array
items:
type: string
description: |
In an array of strings, any filter(s) that are unsupported by an implementation go here.
example: '"data_2295"'
unsupportedFilterValues:
type: array
items:
type: string
description: |
If an implementation does not support a filter value, let's say, for example, 'NCIT_C124294'(Undetermined) Sex, this unsupported value goes here as a string, and will be ignored while a partial query is performed with other supported filter(s) from the request body (if any).
example: '"NCIT_C124294","NCIT_C179980"'
description: |
Respond with a list of (comma-separated) unsupported filter(s).
example: |
{
unsupportedFilters: ["NCIT_C156420"],
unsupportedFilterValues:["NCIT_C124294"]
}
IndividualResponseContent:
required:
- exists
- numTotalResults
type: object
properties:
exists:
type: boolean
description: |
Indicator of whether any individual was observed in the
data source for the given query with CDEs parameter. This should be non-null, unless there was an error, in which case `error` has to be non-null.
numTotalResults:
type: integer
description: |
Response of the query indicating if the query yield any results. If the query is successful then the count will be returned as a response.
CatalogsResponseSummaryContent:
required:
- exists
- numTotalResults
type: object
properties:
exists:
type: boolean
description: |
Indicator of whether any catalog was observed in the
data source for the given query with CDEs filters. This should be non-null, unless there was an error, in which case `error` has to be non-null.
numTotalResults:
type: integer
description: |
Response of the query indicating if the query yield any results. If the query is successful then the count will be returned as a response.
CatalogsResponseContent:
required:
- resultSets
type: array
items:
$ref: "#/components/schemas/ResultsetsResponseContent"
ResultsetsResponseContent:
required:
- id
- setType
- exists
- resultsCount
- results
type: object
properties:
id:
type: string
description: |
id of the resultset
example: "catalogA0123"
setType:
type: string
description: |
Entry type of resultset. It SHOULD MATCH an entry type declared in the Beacon configuration.
example: "catalog"
exists:
type: boolean
description: |
Indicator of whether any catalog was observed in the
data source for the given query with CDEs filters. This should be non-null, unless there was an error, in which case `error` has to be non-null.
resultsCount:
type: integer
description: |
Number of results in this Resultset.
results:
description: |
Array set of the records matching with the query.
type: array
items:
anyOf:
- $ref: "#/components/schemas/CatalogsResultsV0.2"
- $ref: "#/components/schemas/CatalogsResultsV0.3"
resultsHandover:
description: |
Handover to the resultant record page, if any.
IndividualsResults:
type: array
items:
type: object
required:
- id
- type
- exists
- resultCount
properties:
id:
type: string
description: |
id of the result
example: "result0123"
type:
type: string
description: |
Type of result
example: "Dataset"
exists:
type: boolean
description: |
Whether the results exists or not.
resultCount:
type: integer
description: |
Count of result, either exact or higher range of result. If employing ranges, 'info' attributre is required.
info:
required:
- resultCountDescription
- contactPoint
- contactEmail
- contactURL
type: object
properties:
resultCountDescription:
required:
- minRange
- maxRange
description: |
Contains minRange and maxRange of resultant set.
type: object
properties:
minRange:
type: integer
description: |
Value of minimum range employed.
maxRange: