-
Notifications
You must be signed in to change notification settings - Fork 28
/
TranslatorReasonerAPI.yaml
1625 lines (1625 loc) · 64.2 KB
/
TranslatorReasonerAPI.yaml
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:
description: INSERT-DESCRIPTION-OF-YOUR-SERVICE-HERE
version: INSERT-VERSION-OF-YOUR-SERVICE-HERE
title: INSERT-TITLE-OF-YOUR-SERVICE-HERE
contact:
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: INSERT-URL-HERE
x-translator:
component: INSERT-EITHER-ARA-OR-KP-OR-ARS-OR-Utility-HERE
team:
- INSERT-ONE-TRANSLATOR-TEAM-NAME-PER-ELEMENT-HERE
biolink-version: INSERT-BIOLINK-MODEL-VERSION-HERE
infores: INSERT-INFORES-CURIE-OF-THIS-RESOURCE-HERE
externalDocs:
description: >-
The values for component and team are restricted according to this
external JSON schema. See schema and examples at url
url: https://github.com/NCATSTranslator/translator_extensions/blob/\
production/x-translator/
x-trapi:
version: 1.5.0
multicuriequery: REPLACE-WITH-true-IF-multicurie-queries-ARE-IMPLEMENTED-ELSE-false
asyncquery: REPLACE-WITH-true-IF-/asyncquery-IS-IMPLEMENTED-ELSE-false
pathfinderquery: REPLACE-WITH-true-IF-pathfinder-queries-ARE-IMPLEMENTED-ELSE-false
operations:
- LIST-ALL-SUPPORTED-OPERATION-IDS-HERE-OR-REMOVE-THIS-SECTION
batch_size_limit: ADD-BATCH-SIZE-LIMIT-OR-REMOVE-IF-NO-LIMIT
rate_limit: ADD-REQUEST-RATE-LIMIT-OR-REMOVE-IF-NO-LIMIT
test_data_location: ADD-URL-THAT-RESOLVES-TO-SRI-TESTING-HARNESS-DATA
externalDocs:
description: >-
The values for version are restricted according to the regex in
this external JSON schema. See schema and examples at url
url: https://github.com/NCATSTranslator/translator_extensions/blob/\
production/x-trapi/
servers:
- url: INSERT-URL-HERE
description: INSERT-SERVER-DESCRIPTION-HERE
externalDocs:
description: >-
Documentation for the NCATS Biomedical Translator Reasoners web services
url: https://github.com/NCATSTranslator/ReasonerAPI
tags:
- name: meta_knowledge_graph
description: >-
Retrieve the meta knowledge graph representation of this
TRAPI web service. KPs MUST provide all subject category - predicate -
object category triplets that are supported by the service,
NOT including all implied ancestor relationships. ARAs SHOULD provide
the union of all meta knowledge graphs of all the KPs that they can
consult.
externalDocs:
description: >-
Documentation for the reasoner meta_knowledge_graph function
url: INSERT-URL-HERE-OR-REMOVE-EXTERNALDOCS-IF-NA
- name: query
description: Initiate a query and wait to receive the response
externalDocs:
description: Documentation for the reasoner query function
url: INSERT-URL-HERE-OR-REMOVE-EXTERNALDOCS-IF-NA
- name: asyncquery
description: Initiate a query with a callback to receive the response
externalDocs:
description: Documentation for the reasoner asynchquery function
url: INSERT-URL-HERE-OR-REMOVE-EXTERNALDOCS-IF-NA
- name: asyncquery_status
description: >-
Retrieve the current status of a previously submitted
asyncquery given its job_id
- name: translator
description: Required for SmartAPI validation of x-translator
- name: trapi
description: Required for SmartAPI validation of x-trapi
paths:
/meta_knowledge_graph:
get:
tags:
- meta_knowledge_graph
summary: Meta knowledge graph representation of this TRAPI web service.
responses:
'200':
description: >-
Returns meta knowledge graph representation of this TRAPI web
service.
content:
application/json:
schema:
$ref: '#/components/schemas/MetaKnowledgeGraph'
/query:
post:
tags:
- query
summary: Initiate a query and wait to receive a Response
description: ''
requestBody:
description: Query information to be submitted
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
responses:
'200':
description: >-
OK. There may or may not be results. Note that some of the provided
identifiers may not have been recognized.
content:
application/json:
schema:
$ref: '#/components/schemas/Response'
'400':
description: >-
Bad request. The request is invalid according to this OpenAPI
schema OR a specific identifier is believed to be invalid somehow
(not just unrecognized).
content:
application/json:
schema:
type: string
'413':
description: >-
Payload too large. Indicates that batch size was over the limit
specified in x-trapi.
content:
application/json:
schema:
type: string
'429':
description: >-
Too many requests. Indicates that the client issued requests that
exceed the rate limit specified in x-trapi.
content:
application/json:
schema:
type: string
'500':
description: >-
Internal server error.
content:
application/json:
schema:
type: string
'501':
description: >-
Not implemented.
content:
application/json:
schema:
type: string
/asyncquery:
post:
tags:
- asyncquery
summary: Initiate a query with a callback to receive the response
description: ''
requestBody:
description: Query information to be submitted
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncQuery'
responses:
'200':
description: >-
The query is accepted for processing and the Response will be
sent to the callback url when complete.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncQueryResponse'
'400':
description: >-
Bad request. The request is invalid according to this OpenAPI
schema OR a specific identifier is believed to be invalid somehow
(not just unrecognized).
content:
application/json:
schema:
type: string
'413':
description: >-
Payload too large. Indicates that batch size was over the limit
specified in x-trapi.
content:
application/json:
schema:
type: string
'429':
description: >-
Too many requests. Indicates that the client issued requests that
exceed the rate limit specified in x-trapi.
content:
application/json:
schema:
type: string
'500':
description: >-
Internal server error.
content:
application/json:
schema:
type: string
'501':
description: >-
Not implemented.
content:
application/json:
schema:
type: string
/asyncquery_status/{job_id}:
get:
tags:
- asyncquery_status
summary: >-
Retrieve the current status of a previously submitted
asyncquery given its job_id
operationId: asyncquery_status
parameters:
- in: path
name: job_id
description: Identifier of the job for status request
example: rXEOAosN3L
required: true
schema:
type: string
responses:
'200':
description: >-
Returns the status and current logs of a previously
submitted asyncquery.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncQueryStatusResponse'
'404':
description: job_id not found
'501':
description: >-
Return code 501 indicates that this endpoint has not been
implemented at this site. Sites that implement /asyncquery
MUST implement /asyncquery_status/{job_id}, but those that
do not implement /asyncquery SHOULD NOT implement
/asyncquery_status.
content:
application/json:
schema:
type: string
components:
schemas:
Query:
description: >-
The Query class is used to package a user request for information. A
Query object consists of a required Message object with optional
additional properties. Additional properties are intended to convey
implementation-specific or query-independent parameters. For example,
an additional property specifying a log level could allow a user to
override the default log level in order to receive more fine-grained
log information when debugging an issue.
x-body-name: request_body
type: object
properties:
message:
oneOf:
- $ref: '#/components/schemas/Message'
nullable: false
description: >-
The query Message is a serialization of the user request. Content
of the Message object depends on the intended TRAPI operation. For
example, the fill operation requires a non-empty query_graph field
as part of the Message, whereas other operations, e.g. overlay,
require non-empty results and knowledge_graph fields.
log_level:
description: The least critical level of logs to return
oneOf:
- $ref: '#/components/schemas/LogLevel'
nullable: true
workflow:
description: List of workflow steps to be executed.
oneOf:
- $ref: https://standards.ncats.io/workflow/1.3.5/schema
nullable: true
submitter:
type: string
description: >-
Any string for self-identifying the submitter of a query. The
purpose of this optional field is to aid in the tracking of
the source of queries for development and issue resolution.
nullable: true
bypass_cache:
type: boolean
default: false
description: >-
Set to true in order to request that the agent obtain
fresh information from its sources in all cases where
it has a viable choice between requesting fresh information
in real time and using cached information. The agent
receiving this flag MUST also include it in TRAPI sent to
downstream sources (e.g., ARS -> ARAs -> KPs).
additionalProperties: true
required:
- message
AsyncQuery:
description: >-
The AsyncQuery class is effectively the same as the Query class but
it requires a callback property.
x-body-name: request_body
type: object
properties:
callback:
type: string
nullable: false
format: uri
pattern: ^https?://
description: >-
Upon completion, this server will send a POST request to the
callback URL with `Content-Type: application/json` header and
request body containing a JSON-encoded `Response` object.
The server MAY POST `Response` objects before work is fully
complete to provide interim results with a Response.status
value of 'Running'. If a POST operation to the callback URL
does not succeed, the server SHOULD retry the POST at least
once.
message:
oneOf:
- $ref: '#/components/schemas/Message'
nullable: false
description: >-
The query Message is a serialization of the user request. Content
of the Message object depends on the intended TRAPI operation. For
example, the fill operation requires a non-empty query_graph field
as part of the Message, whereas other operations, e.g. overlay,
require non-empty results and knowledge_graph fields.
log_level:
description: The least critical level of logs to return
oneOf:
- $ref: '#/components/schemas/LogLevel'
nullable: true
workflow:
description: List of workflow steps to be executed.
oneOf:
- $ref: https://standards.ncats.io/workflow/1.3.5/schema
nullable: true
submitter:
type: string
description: >-
Any string for self-identifying the submitter of a query. The
purpose of this optional field is to aid in the tracking of
the source of queries for development and issue resolution.
nullable: true
bypass_cache:
type: boolean
default: false
description: >-
Set to true in order to request that the agent obtain
fresh information from its sources in all cases where
it has a viable choice between requesting fresh information
in real time and using cached information. The agent
receiving this flag MUST also include it in TRAPI sent to
downstream sources (e.g., ARS -> ARAs -> KPs).
additionalProperties: true
required:
- callback
- message
AsyncQueryResponse:
type: object
description: >-
The AsyncQueryResponse object contains a payload that must be
returned from a submitted async_query.
properties:
status:
description: >-
One of a standardized set of short codes:
e.g. Accepted, QueryNotTraversable, KPsNotAvailable
type: string
example: Accepted
nullable: true
description:
description: >-
A brief human-readable description of the result of the
async_query submission.
type: string
example: Async_query has been queued
nullable: true
job_id:
description: >-
An identifier for the submitted job that can be used with
/async_query_status to receive an update on the status of
the job.
type: string
example: rXEOAosN3L
nullable: false
additionalProperties: true
required:
- job_id
AsyncQueryStatusResponse:
type: object
description: >-
The AsyncQueryStatusResponse object contains a payload that describes
the current status of a previously submitted async_query.
properties:
status:
description: >-
One of a standardized set of short codes:
Queued, Running, Completed, Failed
type: string
example: Running
nullable: false
description:
description: >-
A brief human-readable description of the current state
or summary of the problem if the status is Failed.
type: string
example: Callback URL returned 500
nullable: false
logs:
description: >-
A list of LogEntry items, containing errors, warnings, debugging
information, etc. List items MUST be in chronological order with
earliest first. The most recent entry should be last. Its timestamp
will be compared against the current time to see if there is
still activity.
type: array
items:
$ref: '#/components/schemas/LogEntry'
minItems: 1
nullable: false
response_url:
description: >-
Optional URL that can be queried to restrieve the full TRAPI
Response.
type: string
example: https://arax.ncats.io/api/arax/v1.3/response/116481
nullable: true
additionalProperties: true
required:
- status
- description
- logs
Response:
type: object
description: >-
The Response object contains the main payload when a TRAPI query
endpoint interprets and responds to the submitted query successfully
(i.e., HTTP Status Code 200). The message property contains the
knowledge of the response (query graph, knowledge graph, and results).
The status, description, and logs properties provide additional details
about the response.
properties:
message:
description: >-
Contains the knowledge of the response (query graph, knowledge
graph, and results).
oneOf:
- $ref: '#/components/schemas/Message'
nullable: false
status:
description: >-
One of a standardized set of short codes,
e.g. Success, QueryNotTraversable, KPsNotAvailable
type: string
example: Success
nullable: true
description:
description: A brief human-readable description of the outcome
type: string
example: Success. 42 results found.
nullable: true
logs:
description: >-
A list of LogEntry items, containing errors, warnings, debugging
information, etc. List items MUST be in chronological order with
earliest first.
type: array
items:
$ref: '#/components/schemas/LogEntry'
minItems: 0
nullable: false
workflow:
description: List of workflow steps that were executed.
oneOf:
- $ref: https://standards.ncats.io/workflow/1.3.5/schema
nullable: true
schema_version:
type: string
example: 1.4.0
description: Version label of the TRAPI schema used in this document
nullable: true
biolink_version:
type: string
example: 3.1.2
description: Version label of the Biolink model used in this document
nullable: true
additionalProperties: true
required:
- message
Message:
description: >-
The message object holds the main content of a Query or a Response in
three properties: query_graph, results, and knowledge_graph.
The query_graph property contains the query configuration, the results
property contains any answers that are returned by the service,
and knowledge_graph property contains lists of edges and nodes in the
thought graph corresponding to this message. The content of these
properties is context-dependent to the encompassing object and
the TRAPI operation requested.
type: object
properties:
results:
description: >-
List of all returned Result objects for the query posed.
The list SHOULD NOT be assumed to be ordered. The 'score' property,
if present, MAY be used to infer result rankings. If Results are
not expected (such as for a query Message), this property SHOULD
be null or absent. If Results are expected (such as for a response
Message) and no Results are available, this property SHOULD be an
array with 0 Results in it.
type: array
items:
$ref: '#/components/schemas/Result'
nullable: true
minItems: 0
query_graph:
description: >-
QueryGraph object that contains a serialization of a query in the
form of a graph
oneOf:
- $ref: '#/components/schemas/QueryGraph'
nullable: true
knowledge_graph:
description: >-
KnowledgeGraph object that contains lists of nodes and edges
in the thought graph corresponding to the message
oneOf:
- $ref: '#/components/schemas/KnowledgeGraph'
nullable: true
auxiliary_graphs:
type: object
description: >-
Dictionary of AuxiliaryGraph instances that are used by Knowledge
Graph Edges and Result Analyses. These are referenced elsewhere by
the dictionary key.
additionalProperties:
$ref: '#/components/schemas/AuxiliaryGraph'
nullable: true
additionalProperties: false
LogEntry:
description: >-
The LogEntry object contains information useful for tracing
and debugging across Translator components. Although an
individual component (for example, an ARA or KP) may have its
own logging and debugging infrastructure, this internal
information is not, in general, available to other components.
In addition to a timestamp and logging level, LogEntry
includes a string intended to be read by a human, along with
one of a standardized set of codes describing the condition of
the component sending the message.
type: object
properties:
timestamp:
type: string
format: date-time
description: >-
Timestamp in ISO 8601 format, providing the LogEntry time
either in univeral coordinated time (UTC) using the 'Z' tag
(e.g 2020-09-03T18:13:49Z), or, if local time is provided,
the timezone offset must be provided
(e.g. 2020-09-03T18:13:49-04:00).
example: '2020-09-03T18:13:49+00:00'
nullable: false
level:
oneOf:
- $ref: '#/components/schemas/LogLevel'
nullable: true
code:
type: string
description: >-
One of a standardized set of short codes
e.g. QueryNotTraversable, KPNotAvailable, KPResponseMalformed
nullable: true
message:
type: string
description: A human-readable log message
nullable: false
additionalProperties: true
required:
- timestamp
- message
LogLevel:
type: string
description: Logging level
enum:
- ERROR
- WARNING
- INFO
- DEBUG
Result:
type: object
description: >-
A Result object specifies the nodes and edges in the knowledge graph
that satisfy the structure or conditions of a user-submitted query
graph. It must contain a NodeBindings object (list of query graph node
to knowledge graph node mappings) and a list of Analysis objects.
properties:
node_bindings:
type: object
description: >-
The dictionary of Input Query Graph to Result Knowledge Graph node
bindings where the dictionary keys are the key identifiers of the
Query Graph nodes and the associated values of those keys are
instances of NodeBinding schema type (see below). This value is an
array of NodeBindings since a given query node may have multiple
knowledge graph Node bindings in the result.
additionalProperties:
type: array
items:
$ref: '#/components/schemas/NodeBinding'
minItems: 1
nullable: false
analyses:
type: array
description: >-
The list of all Analysis components that contribute to the result.
See below for Analysis components.
items:
$ref: '#/components/schemas/Analysis'
minItems: 0
nullable: false
additionalProperties: true
required:
- node_bindings
- analyses
NodeBinding:
type: object
description: >-
An instance of NodeBinding is a single KnowledgeGraph Node mapping,
identified by the corresponding 'id' object key identifier of the
Node within the Knowledge Graph. Instances of NodeBinding may
include extra annotation in the form of additional properties.
(such annotation is not yet fully standardized). Each Node
Binding must bind directly to node in the original Query Graph.
properties:
id:
oneOf:
- $ref: '#/components/schemas/CURIE'
nullable: false
description: >-
The CURIE of a Node within the Knowledge Graph.
query_id:
oneOf:
- $ref: '#/components/schemas/CURIE'
description: >-
An optional property to provide the CURIE in the QueryGraph to
which this binding applies. If the bound QNode does not have an
an 'id' property or if it is empty, then this query_id MUST be
null or absent. If the bound QNode has one or more CURIEs
as an 'id' and this NodeBinding's 'id' refers to a QNode 'id'
in a manner where the CURIEs are different (typically due to
the NodeBinding.id being a descendant of a QNode.id), then
this query_id MUST be provided. In other cases, there is no
ambiguity, and this query_id SHOULD NOT be provided.
nullable: true
attributes:
type: array
description: >-
A list of attributes providing further information about the
node binding. This is not intended for capturing node attributes
and should only be used for properties that vary from result to
result.
items:
$ref: '#/components/schemas/Attribute'
minItems: 0
nullable: false
additionalProperties: true
required:
- id
- attributes
Analysis:
type: object
description: >-
An analysis is a dictionary that contains information about
the result tied to a particular service. Each Analysis is
generated by a single reasoning service, and describes the
outputs of analyses performed by the reasoner on a particular
Result (e.g. a result score), along with provenance information
supporting the analysis (e.g. method or data that supported
generation of the score).
properties:
resource_id:
$ref: '#/components/schemas/CURIE'
description: The id of the resource generating this Analysis
score:
type: number
format: float
example: 163.233
description: >-
A numerical score associated with this result indicating the
relevance or confidence of this result relative to others in the
returned set. Higher MUST be better.
nullable: true
edge_bindings:
type: object
description: >-
The dictionary of input Query Graph to Knowledge Graph edge
bindings where the dictionary keys are the key identifiers of the
Query Graph edges and the associated values of those keys are
instances of EdgeBinding schema type (see below). This value is an
array of EdgeBindings since a given query edge may resolve to
multiple Knowledge Graph Edges.
additionalProperties:
type: array
items:
$ref: '#/components/schemas/EdgeBinding'
support_graphs:
type: array
description: >-
This is a list of references to Auxiliary Graph instances
that supported the analysis of a Result as performed by the
reasoning service. Each item in the list is the key of a
single Auxiliary Graph.
nullable: true
items:
type: string
scoring_method:
type: string
description: >-
An identifier and link to an explanation for the method used
to generate the score
nullable: true
attributes:
type: array
description: >-
The attributes of this particular Analysis.
items:
$ref: '#/components/schemas/Attribute'
nullable: true
additionalProperties: true
required:
- resource_id
- edge_bindings
EdgeBinding:
type: object
description: >-
A instance of EdgeBinding is a single KnowledgeGraph Edge mapping,
identified by the corresponding 'id' object key identifier of the
Edge within the Knowledge Graph. Instances of EdgeBinding may include
extra annotation (such annotation is not yet fully standardized).
Edge bindings are captured within a specific reasoner's Analysis
object because the Edges in the Knowledge Graph that get bound to
the input Query Graph may differ between reasoners.
properties:
id:
type: string
description: The key identifier of a specific KnowledgeGraph Edge.
nullable: false
attributes:
type: array
description: >-
A list of attributes providing further information about the
edge binding. This is not intended for capturing edge attributes
and should only be used for properties that vary from result to
result.
items:
$ref: '#/components/schemas/Attribute'
minItems: 0
nullable: false
additionalProperties: true
required:
- id
- attributes
AuxiliaryGraph:
type: object
description: >-
A single AuxiliaryGraph instance that is used by Knowledge Graph
Edges and Result Analyses. Edges comprising an Auxiliary Graph
are a subset of the Knowledge Graph in the message. Data creators
can create an AuxiliaryGraph to assemble a specific collections
of edges from the Knowledge Graph into a named graph that can be
referenced from an Edge as evidence/explanation supporting that Edge,
or from a Result Analysis as information used to generate a score.
properties:
edges:
type: array
description: >-
List of edges that form the Auxiliary Graph. Each item is a
reference to a single Knowledge Graph edge
items:
type: string
nullable: false
minItems: 1
attributes:
type: array
description: >-
Attributes of the Auxiliary Graph
items:
$ref: '#/components/schemas/Attribute'
minItems: 0
nullable: false
additionalProperties: true
required:
- edges
- attributes
KnowledgeGraph:
type: object
description: >-
The knowledge graph associated with a set of results. The instances
of Node and Edge defining this graph represent instances of
biolink:NamedThing (concept nodes) and biolink:Association
(relationship edges) representing (Attribute) annotated knowledge
returned from the knowledge sources and inference agents wrapped by
the given TRAPI implementation.
properties:
nodes:
type: object
description: >-
Dictionary of Node instances used in the KnowledgeGraph,
referenced elsewhere in the TRAPI output by the dictionary key.
additionalProperties:
$ref: '#/components/schemas/Node'
edges:
type: object
description: >-
Dictionary of Edge instances used in the KnowledgeGraph,
referenced elsewhere in the TRAPI output by the dictionary key.
additionalProperties:
$ref: '#/components/schemas/Edge'
additionalProperties: true
required:
- nodes
- edges
QueryGraph:
type: object
description: >-
A graph representing a biomedical question. It serves as a template for
each result (answer), where each bound knowledge graph node/edge is
expected to obey the constraints of the associated query graph element.
properties:
nodes:
type: object
description: >-
The node specifications. The keys of this map are unique node
identifiers and the corresponding values include the constraints
on bound nodes.
additionalProperties:
$ref: '#/components/schemas/QNode'
edges:
type: object
description: >-
The edge specifications. The keys of this map are unique edge
identifiers and the corresponding values include the constraints
on bound edges, in addition to specifying the subject and object
QNodes.
additionalProperties:
$ref: '#/components/schemas/QEdge'
additionalProperties: true
required:
- nodes
- edges
QNode:
type: object
description: A node in the QueryGraph used to represent an entity in a
query. If a CURIE is not specified, any nodes matching the category
of the QNode will be returned in the Results.
properties:
ids:
type: array
items:
$ref: '#/components/schemas/CURIE'
minItems: 1
example: ["OMIM:603903"]
description: >-
A CURIE identifier (or list of identifiers) for this node.
The 'ids' field will hold a list of CURIEs only in the case of a
BATCH set_interpretation, where each CURIE is queried
separately. If a list of queried CURIEs is to be considered as a
set (as under a MANY or ALL set_interpretation), the 'ids' field
will hold a single id representing this set, and the individual members
of this set will be captured in a separate 'member_ids' field.
Note that the set id MUST be created as a UUID by the system that
defines the queried set, using a centralized nodenorm service.
Note also that downstream systems MUST re-use the original set UUID
in the messages they create/send, which will facilitate merging or
caching operations.
nullable: true
categories:
type: array
description: >-
These should be Biolink Model categories and are allowed
to be of type 'abstract' or 'mixin' (only in QGraphs!).
Use of 'deprecated' categories should be avoided.
items:
$ref: '#/components/schemas/BiolinkEntity'
minItems: 1
nullable: true
set_interpretation:
type: string
description: >-
Indicates how multiple CURIEs in the ids property MUST be
interpreted. BATCH indicates that the query is intended to be
a batch query and each CURIE is treated independently. ALL means
that all specified CURIES MUST appear in each Result.
MANY means that member CURIEs MUST form one or more
sets in the Results, and sets with more members are generally
considered more desirable that sets with fewer members.
If this property is missing or null, the default is BATCH.
enum:
- BATCH
- ALL
- MANY
nullable: true
member_ids:
type: array
description: >-
A list of CURIE identifiers for members of a queried set. This
field MUST be populated under a set_interpretation of MANY
or ALL, when the 'ids' field holds a UUID representing the set
itself. This field MUST NOT be used under a set_interpretation
of BATCH.
nullable: true
items:
$ref: '#/components/schemas/CURIE'
constraints:
type: array
description: >-
A list of constraints applied to a query node.
If there are multiple items, they must all be true (equivalent
to AND)
items:
$ref: '#/components/schemas/AttributeConstraint'
default: []
additionalProperties: true
QEdge:
type: object
description: >-
An edge in the QueryGraph used as a filter pattern specification in a
query. If the optional predicate property is not specified,
it is assumed to be a wildcard match to the target knowledge space.
If specified, the ontological inheritance hierarchy associated with
the term provided is assumed, such that edge bindings returned may be
an exact match to the given QEdge predicate term,
or to a term that is a descendant of the QEdge predicate term.
properties:
knowledge_type:
description: >-
Indicates the type of knowledge that the client wants from the
server between the subject and object. If the value is
'lookup', then the client wants direct lookup information from
knowledge sources. If the value is 'inferred', then the client
wants the server to get creative and connect the subject and
object in more speculative and non-direct-lookup ways. If this
property is absent or null, it MUST be assumed to mean
'lookup'. This feature is currently experimental and may be
further extended in the future.
example: lookup
nullable: true
type: string
predicates:
type: array
description: >-
These should be Biolink Model predicates and are allowed to be of
type 'abstract' or 'mixin' (only in QGraphs!). Use of 'deprecated'
predicates should be avoided.
items:
$ref: '#/components/schemas/BiolinkPredicate'
minItems: 1
nullable: true
subject:
type: string
example: https://omim.org/entry/603903
description: >-
Corresponds to the map key identifier of the
subject concept node anchoring the query filter
pattern for the query relationship edge.
object:
type: string
example: https://www.uniprot.org/uniprot/P00738
description: >-
Corresponds to the map key identifier of the
object concept node anchoring the query filter
pattern for the query relationship edge.
attribute_constraints:
type: array
description: >-
A list of attribute constraints applied to a query edge.
If there are multiple items, they must all be true (equivalent
to AND)
items:
$ref: '#/components/schemas/AttributeConstraint'
default: []
qualifier_constraints:
type: array
description: >-
A list of QualifierConstraints that provide nuance to the QEdge.
If multiple QualifierConstraints are provided, there is an OR
relationship between them. If the QEdge has multiple
predicates or if the QNodes that correspond to the subject or