diff --git a/ImplementationGuidance/DataExamples/1-6_example_response.json b/ImplementationGuidance/DataExamples/1-6_example_response.json new file mode 100644 index 00000000..d51ab474 --- /dev/null +++ b/ImplementationGuidance/DataExamples/1-6_example_response.json @@ -0,0 +1,357 @@ +{ + "message": { + "query_graph": { + "nodes": { + "nA": { + "ids": null, + "categories": [ + "biolink:Drug" + ], + "set_interpretation": "BATCH", + "constraints": [], + "member_ids": [] + }, + "nI": { + "ids": null, + "categories": [ + "biolink:Gene" + ], + "set_interpretation": "BATCH", + "constraints": [], + "member_ids": [] + }, + "nB": { + "ids": [ + "MONDO:111" + ], + "categories": [ + "biolink:Disease" + ], + "set_interpretation": "BATCH", + "constraints": [], + "member_ids": [] + } + }, + "edges": { + "e1": { + "subject": "nA", + "object": "nI", + "knowledge_type": null, + "predicates": null, + "attribute_constraints": [ + { + "id": "biolink:knowledge_source", + "name": "special key to query on sources info", + "not": true, + "operator": "==", + "value": "infores:semmeddb" + } + ], + "qualifier_constraints": [ + { + "qualifier_set": [ + { + "qualifier_type_id": "biolink:object_direction_qualifier", + "qualifier_value": "increased" + }, + { + "qualifier_type_id": "biolink:object_aspect_qualifier", + "qualifier_value": "activity_or_abundance" + } + ] + } + ] + }, + "e2": { + "subject": "nI", + "object": "nB", + "knowledge_type": null, + "predicates": null, + "attribute_constraints": [ + { + "id": "biolink:knowledge_level", + "name": "knowledge level", + "operator": "==", + "value": [ + "knowledge_assertion", + "text_co_occurrence" + ] + }, + { + "id": "biolink:agent_type", + "name": "agent type", + "operator": "==", + "value": "automated_agent" + }, + { + "id": "biolink:z_score", + "name": "z-score", + "operator": ">", + "value": 5 + } + ], + "qualifier_constraints": [] + } + } + }, + "knowledge_graph": { + "nodes": { + "MONDO:111": { + "categories": [ + "biolink:Disease" + ], + "attributes": [], + "name": "type 1 diabetes mellitus" + }, + "CHEBI:1234": { + "categories": [ + "biolink:Drug" + ], + "attributes": [], + "name": "Metformin" + }, + "NCBIGene:7777": { + "categories": [ + "biolink:Gene" + ], + "attributes": [], + "name": "EIF2_AK3" + }, + "NCBIGene:5555": { + "categories": [ + "biolink:Gene" + ], + "attributes": [], + "name": "HMOX1" + } + }, + "edges": { + "e2_B": { + "predicate": "biolink:affects", + "subject": "NCBIGene:7777", + "object": "MONDO:111", + "sources": [ + { + "resource_id": "infores:ctd", + "resource_role": "primary_knowledge_source" + } + ], + "attributes": [ + { + "attribute_type_id": "biolink:knowledge_level", + "value": "knowledge_assertion" + }, + { + "attribute_type_id": "biolink:agent_type", + "value": "automated_agent" + }, + { + "attribute_type_id": "biolink:z_score", + "value": 7.963 + } + ], + "qualifiers": [] + }, + "e1_B": { + "predicate": "biolink:affects", + "subject": "CHEBI:1234", + "object": "NCBIGene:7777", + "sources": [ + { + "resource_id": "infores:text-mining-provider-targeted", + "resource_role": "primary_knowledge_source" + } + ], + "attributes": [ + { + "attribute_type_id": "biolink:knowledge_level", + "value": "not_provided" + }, + { + "attribute_type_id": "biolink:agent_type", + "value": "text_mining_agent" + } + ], + "qualifiers": [ + { + "qualifier_type_id": "biolink:qualified_predicate", + "qualifier_value": "biolink:causes" + }, + { + "qualifier_type_id": "biolink:object_direction_qualifier", + "qualifier_value": "increased" + }, + { + "qualifier_type_id": "biolink:object_aspect_qualifier", + "qualifier_value": "activity_or_abundance" + } + ] + }, + "e2_A": { + "predicate": "biolink:occurs_together_in_literature_with", + "subject": "NCBIGene:5555", + "object": "MONDO:111", + "sources": [ + { + "resource_id": "infores:diseases", + "resource_role": "primary_knowledge_source" + } + ], + "attributes": [ + { + "attribute_type_id": "biolink:knowledge_level", + "value": "text_co_occurrence" + }, + { + "attribute_type_id": "biolink:agent_type", + "value": "data_analysis_pipeline" + }, + { + "attribute_type_id": "biolink:z_score", + "value": 6.435 + } + ], + "qualifiers": [] + }, + "e1_A": { + "predicate": "biolink:affects", + "subject": "CHEBI:1234", + "object": "NCBIGene:5555", + "sources": [ + { + "resource_id": "infores:chembl", + "resource_role": "primary_knowledge_source" + } + ], + "attributes": [ + { + "attribute_type_id": "biolink:knowledge_level", + "value": "knowledge_assertion" + }, + { + "attribute_type_id": "biolink:agent_type", + "value": "manual_agent" + } + ], + "qualifiers": [ + { + "qualifier_type_id": "biolink:qualified_predicate", + "qualifier_value": "biolink:causes" + }, + { + "qualifier_type_id": "biolink:object_direction_qualifier", + "qualifier_value": "increased" + }, + { + "qualifier_type_id": "biolink:object_aspect_qualifier", + "qualifier_value": "activity_or_abundance" + } + ] + } + } + }, + "results": [ + { + "node_bindings": { + "nA": [ + { + "id": "CHEBI:1234", + "attributes": [] + } + ], + "nI": [ + { + "id": "NCBIGene:5555", + "attributes": [] + } + ], + "nB": [ + { + "id": "MONDO:111", + "attributes": [] + } + ] + }, + "analyses": [ + { + "resource_id": "infores:retriever", + "edge_bindings": { + "e1": [ + { + "id": "e1_A", + "attributes": [] + } + ], + "e2": [ + { + "id": "e2_A", + "attributes": [] + } + ] + } + } + ] + }, + { + "node_bindings": { + "nA": [ + { + "id": "CHEBI:1234", + "attributes": [] + } + ], + "nI": [ + { + "id": "NCBIGene:7777", + "attributes": [] + } + ], + "nB": [ + { + "id": "MONDO:111", + "attributes": [] + } + ] + }, + "analyses": [ + { + "resource_id": "infores:retriever", + "edge_bindings": { + "e1": [ + { + "id": "e1_B", + "attributes": [] + } + ] + }, + "e2": [ + { + "id": "e2_B", + "attributes": [] + } + ] + } + ] + } + ], + "auxiliary_graphs": {} + }, + "log_level": "DEBUG", + "bypass_cache": true, + "biolink_version": "4.3.2", + "schema_version": "1.6.0", + "workflow": null, + "status": "Complete", + "logs": [ + { + "level": "INFO", + "message": "Begin processing...", + "timestamp": "1" + }, + { + "level": "DEBUG", + "message": "Found 2 starting branches...", + "timestamp": "2" + } + ] +} diff --git a/ImplementationGuidance/DataExamples/2-0_example_response.json b/ImplementationGuidance/DataExamples/2-0_example_response.json new file mode 100644 index 00000000..4b4ae8f6 --- /dev/null +++ b/ImplementationGuidance/DataExamples/2-0_example_response.json @@ -0,0 +1,260 @@ +{ + "message": { + "query_graph": { + "nodes": { + "nA": { + "categories": [ + "biolink:Drug" + ] + }, + "nI": { + "categories": [ + "biolink:Gene" + ], + "set_interpretation": "COLLATE" + }, + "nB": { + "ids": [ + "MONDO:111" + ], + "categories": [ + "biolink:Disease" + ] + } + }, + "edges": { + "e1": { + "subject": "nA", + "object": "nI", + "constraints": { + "sources": { + "behavior": "DENY", + "values": [ + "infores:semmeddb" + ] + }, + "qualifiers": [ + { + "biolink:object_direction_qualifier": "increased", + "biolink:object_aspect_qualifier": "activity_or_abundance" + } + ] + } + }, + "e2": { + "subject": "nI", + "object": "nB", + "constraints": { + "knowledge_level": { + "behavior": "ALLOW", + "values": [ + "knowledge_assertion", + "text_co_occurrence" + ] + }, + "agent_type": { + "behavior": "ALLOW", + "values": [ + "automated_agent" + ] + }, + "attributes": [ + { + "id": "biolink:z_score", + "name": "z-score", + "operator": ">", + "value": 5 + } + ] + } + } + } + }, + "knowledge_graph": { + "nodes": { + "MONDO:111": { + "categories": [ + "biolink:Disease" + ], + "name": "type 1 diabetes mellitus" + }, + "CHEBI:1234": { + "categories": [ + "biolink:Drug" + ], + "name": "Metformin" + }, + "NCBIGene:7777": { + "categories": [ + "biolink:Gene" + ], + "name": "EIF2_AK3" + }, + "NCBIGene:5555": { + "categories": [ + "biolink:Gene" + ], + "name": "HMOX1" + } + }, + "edges": { + "e2_B": { + "predicate": "biolink:affects", + "subject": "NCBIGene:7777", + "object": "MONDO:111", + "knowledge_level": "knowledge_assertion", + "agent_type": "automated_agent", + "sources": [ + { + "resource_id": "infores:ctd", + "resource_role": "primary_knowledge_source" + } + ], + "attributes": [ + { + "attribute_type_id": "biolink:z_score", + "value": 7.963 + } + ] + }, + "e1_B": { + "predicate": "biolink:affects", + "subject": "CHEBI:1234", + "object": "NCBIGene:7777", + "knowledge_level": "not_provided", + "agent_type": "text_mining_agent", + "sources": [ + { + "resource_id": "infores:text-mining-provider-targeted", + "resource_role": "primary_knowledge_source" + } + ], + "qualifiers": [ + { + "qualifier_type_id": "biolink:qualified_predicate", + "qualifier_value": "biolink:causes" + }, + { + "qualifier_type_id": "biolink:object_direction_qualifier", + "qualifier_value": "increased" + }, + { + "qualifier_type_id": "biolink:object_aspect_qualifier", + "qualifier_value": "activity_or_abundance" + } + ] + }, + "e2_A": { + "predicate": "biolink:occurs_together_in_literature_with", + "subject": "NCBIGene:5555", + "object": "MONDO:111", + "knowledge_level": "text_co_occurrence", + "agent_type": "data_analysis_pipeline", + "sources": [ + { + "resource_id": "infores:diseases", + "resource_role": "primary_knowledge_source" + } + ], + "attributes": [ + { + "attribute_type_id": "biolink:z_score", + "value": 6.435 + } + ] + }, + "e1_A": { + "predicate": "biolink:affects", + "subject": "CHEBI:1234", + "object": "NCBIGene:5555", + "knowledge_level": "knowledge_assertion", + "agent_type": "manual_agent", + "sources": [ + { + "resource_id": "infores:chembl", + "resource_role": "primary_knowledge_source" + } + ], + "qualifiers": [ + { + "qualifier_type_id": "biolink:qualified_predicate", + "qualifier_value": "biolink:causes" + }, + { + "qualifier_type_id": "biolink:object_direction_qualifier", + "qualifier_value": "increased" + }, + { + "qualifier_type_id": "biolink:object_aspect_qualifier", + "qualifier_value": "activity_or_abundance" + } + ] + } + } + }, + "results": [ + { + "node_bindings": { + "nA": { + "ids": [ + "CHEBI:1234" + ] + }, + "nI": { + "ids": [ + "NCBIGene:5555", + "NCBIGene:7777" + ] + }, + "nB": { + "ids": [ + "MONDO:111" + ] + } + }, + "analyses": [ + { + "resource_id": "infores:retriever", + "edge_bindings": { + "e1": { + "ids": [ + "e1_A", + "e1_B" + ] + }, + "e2": { + "ids": [ + "e2_A", + "e2_B" + ] + } + } + } + ] + } + ] + }, + "parameters": { + "log_level": "DEBUG", + "bypass_cache": true, + "timeout": 300, + "tiers": [ + 1 + ] + }, + "biolink_version": "4.3.2", + "schema_version": "1.6.0", + "status": "Complete", + "logs": [ + { + "level": "INFO", + "message": "Begin processing...", + "timestamp": "1" + }, + { + "level": "DEBUG", + "message": "Found 2 starting branches...", + "timestamp": "2" + } + ] +} diff --git a/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md b/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md new file mode 100644 index 00000000..9ac0c8dc --- /dev/null +++ b/ImplementationGuidance/MigrationGuides/MigrationAndImplementationGuide2-0.md @@ -0,0 +1,446 @@ +# TRAPI 2.0 Migration Guide + +This guide lays out the format and functionality changes for queries and responses in TRAPI 2.0.0 (compared to 1.6.0-beta). + +TRAPI 2.0 includes many breaking changes, new/reintroduced functionality, and format changes designed to slim down TRAPI messages. This guide provides before-after examples to illustrate the more complex changes and a list for the other important changes (mainly formatting). + + +## Changes with before-after examples + + +### 1. QEdge Constraints Refactor + +#### BEFORE + +In 1.6.0-beta, you could include `attribute_constraints` and `qualifier_constraints` on QEdges. If you wanted to only include or exclude specific knowledge_level/agent_type (KL/AT) values, you'd use `attribute_constraints` because KL/AT are stored in Edge `attributes`. If you wanted to only include or exclude specific sources (infores), you may have used `attribute_constraints`. BUT this format no longer makes sense after we moved source info out of Edge `attributes` into its own top-level property `sources` several versions ago (1.4.0-beta). + +
A QEdge in 1.6.0-beta with all of these constraints would look like this (click to expand) + +

+ +```json +{ + "subject": "n0", + "object": "n1", + "attribute_constraints": [ + { + "id": "biolink:agent_type", // AT constraint + "name": "agent type", + "operator": "==", + "value": "automated_agent" + }, + { + "id": "biolink:knowledge_source", // source constraint: not semmeddb + "name": "special key to query on sources info", + "not": true, + "operator": "==", + "value": "infores:semmeddb" // str or array of str + }, + { + "id": "biolink:z_score", // regular attribute constraint + "name": "z-score", + "operator": ">", + "value": 5 + } + ], + "qualifier_constraints": [ + { + "qualifier_set": [ + { + "qualifier_type_id": "biolink:subject_aspect_qualifier", + "qualifier_value": "activity_or_abundance" + } + ] + } + ] +} +``` + +

+
+ +#### AFTER + +In 2.0, there is instead one property on a QEdge, `constraints`, that holds all the types of constraints, organized by key. There are 5 keys currently specified: + +* `knowledge_level`: we moved KL/AT out of Edge `attributes` and into its own top-level properties on an Edge (see #4), so they need corresponding separate constraints. This constraint is an object with two keys: `behavior` (`ALLOW` or `DENY`) and `values` (an array of strings). + * `ALLOW` means "ANY (at least 1) of the `values` MUST be in the matched Edge's corresponding property". + * `DENY` means "ALL of the `values` MUST NOT be in the matched Edge's corresponding property". +* `agent_type`: see above (KL) + * FYI: if a specified value has descendants (ex: `automated_agent`), the tool MUST treat those descendants (ex: `text_mining_agent`, etc.) as if they were included in the `values` array (aka "hierarchy expansion"). +* `sources`: this constrains the Edge `sources`. It has the same keys as KL/AT (`behavior`, `values`) plus the optional `primary_only` (if true, the constraint ONLY applies to the `primary_knowledge_source`). +* `attributes`: minItems 1, otherwise the same as previous `attribute_constraints` +* `qualifiers`: simplified format to an array of objects but preserved previous behavior. Each object represents a qualifier-set, and multiple objects/sets have an `OR` relationship. Within an object, the keys are the "qualifier-type-ids" and their values are the "qualifier values". Multiple key/value pairs in one object/set have an `AND` relationship. + +
The same QEdge in 2.0 would look like this (click to expand) +

+ +```json +{ + "subject": "n0", + "object": "n1", + "constraints": { + "agent_type": { // AT constraint + "behavior": "ALLOW", + "values": ["automated_agent"] + }, + "sources": { // source constraint: not semmeddb + "behavior": "DENY", + "values": ["infores:semmeddb"] + }, + "attributes": [ + { + "id": "biolink:z_score", // regular attribute constraint + "name": "z-score", + "operator": ">", + "value": 5 + } + ], + "qualifiers": [ + // one qualifier set + { + "biolink:subject_aspect_qualifier": "activity_or_abundance" + } + ] + } +} +``` + +

+
+ +
+ +
This example Edge (not real!) would fulfill the constraints. Its properties are put in same order as constraints for easy comparison (click to expand) +

+ +```json +{ + "subject": "NCBIGene:1234", + "object": "MONDO:1234", + "predicate": "biolink:associated_with", + "agent_type": "data_analysis_pipeline", // matches AT constraint: this is a child of automated_agent + "knowledge_level": "text_co_occurrence", + "sources": [ // matches source constraint: not semmeddb + { + "resource_id": "infores:diseases", + "resource_role": "primary_knowledge_source" + } + ], + "attributes": [ + { + "attribute_type_id": "biolink:z_score", // matches attrib constraint: >5 + "value": 6.435 + } + ], + "qualifiers": [ + { + "qualifier_type_id": "biolink:subject_direction_qualifier", + "qualifier_value": "decreased" + }, + { + "qualifier_type_id": "biolink:subject_aspect_qualifier", // matches qualifier constraint + "qualifier_value": "activity_or_abundance" + }, + { + "qualifier_type_id": "biolink:qualified_predicate", + "qualifier_value": "biolink:causes" + } + ] +} +``` + +

+
+ + +### 2. New Query/Response Parameters + +#### BEFORE + +In 1.6.0-beta, `log_level` and `bypass_cache` were top-level properties in `Query` and `AsyncQuery`. + +A query with them would look like this: + +```json +{ + "log_level": "DEBUG", + "bypass_cache": true, + "message": {...} +} +``` + +#### AFTER + +In 2.0, these are moved under a new top-level property `parameters` (their behavior is otherwise kept the same). `parameters` also includes a new parameter/property `timeout`, so a client can state how long they will wait for a response. + +Tools can also use the new `parameters` property to hold undefined query-time parameters that affect overall behavior of the server in query execution, like specifying data-tier in the Translator ecosystem. + +`parameters` has also been added to `Response`; the server receiving a Query/AsyncQuery with `parameters` MUST echo them in its Response. If there is a conflict between the `parameters` and the server's capabilities, the server SHOULD return HTTP `409`. + +A query with the same parameters (plus timeout and custom data-tier) would look like this: + +```json +{ + "parameters": { + "log_level": "DEBUG", + "bypass_cache": true, + "timeout": 300, + "tiers": [ 1 ] + }, + "message": {...} +} +``` + + +### 3. Binding Structure Changes (Node/Edge/Path) + +#### BEFORE + +In 1.6.0-beta, the 3 kinds of bindings have this format: + +```json +... +"_bindings": { + "key1": [ + { + "id": "", + "attributes": [] + } + ], + "key2": [ + { + "id": "", + "attributes": [] + } + ] + }, +... +``` + +Details: +* `attributes` were required for `NodeBinding` and `EdgeBinding`, not defined/included in `PathBinding` +* NodeBinding had the optional property `query_id`, which supported an older implementation of subclassing. + +
Example result with node/edge bindings +

+ +```json +{ + "node_bindings": { + "n0": [ + { + "id": "NCBIGene:1234", + "attributes": [] + } + ], + "n1": [ + { + "id": "MONDO:1234", + "attributes": [] + } + ] + }, + "analyses": [ + { + "resource_id": "infores:retriever", + "edge_bindings": { + "e0": [ + { + "id": "edge-1234-1234-1234-1234", + "attributes": [] + } + ] + } + } + ] +} +``` + +

+
+ +
Example result with node/path bindings +

+ +```json +{ + "node_bindings": { + "n0": [ + { + "id": "CHEBI:4567", + "attributes": [] + } + ], + "n1": [ + { + "id": "MONDO:4567", + "attributes": [] + } + ] + }, + "analyses": [ + { + "resource_id": "infores:shepherd-aragorn", + "path_bindings": { + "p0": [ + { + "id": "auxGraph-4567-4567-4567-4567" + } + ] + } + } + ] +} +``` + +

+
+ +#### AFTER + +In 2.0, the format is simplified: + +```json +... +"_bindings": { + "key1": { + "ids": [""] + }, + "key2": { + "ids": [""] + } + }, +... +``` + +Changes: +* `_bindings` are now `minProperties: 1` (AKA when these fields are present, they MUST contain data) +* `ids` arrays are `minItems: 1` (this property is still required) +* `attributes` were removed from NodeBinding/EdgeBinding (were never used, empty arrays bloated responses) +* `query_id` was removed from NodeBinding (obsolete with the current subclassing behavior) + +
Same node/edge bindings result, converted to 2.0 +

+ +```json +{ + "node_bindings": { + "n0": { + "ids": ["NCBIGene:1234"] + }, + "n1": { + "ids": ["MONDO:1234"] + } + }, + "analyses": [ + { + "resource_id": "infores:retriever", + "edge_bindings": { + "e0": { + "ids": ["edge-1234-1234-1234-1234"] + } + } + } + ] +} +``` + +

+
+ +
Same node/path bindings result, converted to 2.0 +

+ +```json +{ + "node_bindings": { + "n0": { + "ids": ["CHEBI:4567"] + }, + "n1": { + "ids": ["MONDO:4567"] + } + }, + "analyses": [ + { + "resource_id": "infores:shepherd-aragorn", + "path_bindings": { + "p0": { + "ids": ["auxGraph-4567-4567-4567-4567"] + } + } + } + ] +} +``` + +

+
+ + +### 4. KL/AT turned into top-level Edge properties, now required + +In 1.6.0-beta, `knowledge_level` and `agent_type` are stored in `Edge.attributes`, which is not a required property. However, for several years the Translator Consortium has actually required KL/AT on Edges. + +In 2.0, they are now top-level properties that are required on an `Edge`. The way to constrain them in queries has also changed (own keys under `QEdge.constraints`) - see #1 for details. + +Example snippet of an `Edge` in 2.0, showing the top-level KL/AT: + +```json +{ + "subject": "NCBIGene:1234", + "object": "MONDO:1234", + "predicate": "biolink:associated_with", + "agent_type": "data_analysis_pipeline", // top-level properties! + "knowledge_level": "text_co_occurrence", + "sources": [...], +} +``` + + +### 5. Add `COLLATE` option to `QNode.set_interpretation` + +In 2.0, `COLLATE` is an option that is only allowed on QNodes with no `ids` set and indicates that multiple matching nodes MUST be collated into a single Result, rather than put into separate Results. This restores some of the `QNode.is_set` behavior that was removed in 1.5.0 (don't confuse with **Node**.is_set!). + +When `COLLATE` is set, `QNode.member_ids` must not be used. + +Example scenario: + +For the query `Drug -interacts_with-> Gene -causes-> Diabetes`, if `Drug A` has matching paths to `Diabetes` through Genes A, B, and C, 3 results could be generated: +* `Drug A -interacts_with-> Gene A -causes-> Diabetes` +* `Drug A -interacts_with-> Gene B -causes-> Diabetes` +* `Drug A -interacts_with-> Gene C -causes-> Diabetes` + +But if COLLATE was set on the Gene QNode as `Drug -interacts_with-> Gene (set_interpretation: COLLATE) -causes-> Diabetes`, in that scenario only 1 result should be generated: +* `Drug A -interacts_with-> Gene [A, B, C] -causes-> Diabetes` + +The `node_bindings.[Gene QNode].ids` would include Genes A, B, and C. The edge_bindings would be collated accordingly. + + +## Other Changes + +1. `null` is no longer a valid value in queries and responses. To convey "no data", omit the field or use an empty array/object if the schema allows (doesn't set `minProperties`/`minItems`). However, unless the field's description explicitly states that the empty array/object should be used, we strongly encourage omitting fields instead to reduce needless bloat. Examples: + * `Message.knowledge_graph` should omitted, not be set to `null`, when there is no data (ex: a query, or a response with no data found). + * `Message.results` should not be set to `null` when there is no data. Its description states when it should be omitted (when not expected, like a query) VS an empty array (when it is expected and there's no data, like a response). +2. For many optional array and object properties, `minItems`/`minProperties` was set to 1. This was to reduce bloat (only include the field if there's data). See the Changelog for the list of changed properties. +3. `AuxiliaryGraph.attributes` was removed. It was previously required, but never used and its empty arrays bloated responses. +4. These properties were changed to not required: + * `Nodes.attributes` + * `QueryGraph` `edges` and `paths`: to accommodate queries with only nodes + * `KnowledgeGraph.edges`: same reason as above + * `Result.analyses`: same reason as above +5. Analysis allows edge_bindings and path_bindings to be present together (for experimental use only, small change introduced when simplifying schema classes) + + +## Full Examples + +This is an example of a 1.6.0-beta Response "transformed" into 2.0 (includes query_graph/parameters). Note that the 2.0 query/response has 2 functiona differences: +* COLLATE was set on the intermediate QNode +* new parameters were added (timeout, custom tiers) + +These examples show the main changes 1-5 (#1: all types of constraints, #5: COLLATE in 2.0 only) and the other changes 1,2, and 4. + +[1.6.0-beta Response](../DataExamples/1-6_example_response.json) + +[2.0 corresponding Response](../DataExamples/2-0_example_response.json) \ No newline at end of file diff --git a/ImplementationGuidance/Specifications/binding_structure_specification.md b/ImplementationGuidance/Specifications/binding_structure_specification.md new file mode 100644 index 00000000..ee516821 --- /dev/null +++ b/ImplementationGuidance/Specifications/binding_structure_specification.md @@ -0,0 +1,95 @@ +# Result Binding Format + +These 3 kinds of bindings in Results share a common format: +- `Result.node_bindings` +- `Result.analyses.edge_bindings` +- `Result.analyses.path_bindings` + +```json +... +"_bindings": { + "key1": { + "ids": [""] + }, + "key2": { + "ids": [""] + } +}, +... +``` + +These structures hold the mapping (binding) of QueryGraph elements to matching KnowledgeGraph elements in an answer. + +Common details: +* `node_bindings` is required in `Result`; at least 1 of `["edge_bindings", "path_bindings"]` is required in an `Analysis` +* `_bindings` are `minProperties: 1`; AKA when these fields are present, they MUST contain data +* The keys in `_bindings` MUST be the same as the keys in the corresponding QueryGraph objects (`QueryGraph.`) +* `ids` is required with `minItems: 1`. The items are the IDs of the matching KnowledgeGraph elements (``), and multiple items MAY be bound to a single key for one result/answer. +* A `Binding` currently MAY include other (undefined) properties besides `ids`. This is to support potential future dev work. + +Notes: +- `NodeBinding.query_id` from older TRAPI versions is obsolete and SHOULD NOT be used. +- `Analysis` currently allows both `edge_bindings` and `path_bindings` within the same object (for experimental dev use only) + + +## Examples + +### Results with edge bindings + +```json +{ + "node_bindings": { + "n0": { "ids": ["NCBIGene:1234"] }, + "n1": { "ids": ["MONDO:1234"] } + }, + "analyses": [ + { + "resource_id": "infores:retriever", + "edge_bindings": { + "e0": { "ids": ["edge-1234-1234-1234-1234"] } + } + } + ] +} +``` + +Multiple nodes/edges bound to a key: + +```json +{ + "node_bindings": { + "nA": { "ids": ["CHEBI:1234"] }, + "nI": { "ids": ["NCBIGene:5555", "NCBIGene:7777"] + }, + "nB": { "ids": ["MONDO:111"] } + }, + "analyses": [ + { + "resource_id": "infores:retriever", + "edge_bindings": { + "e1": { "ids": ["e1_A", "e1_B"] }, + "e2": { "ids": ["e2_A", "e2_B"] } + } + } + ] +} +``` + +### Result with path bindings + +```json +{ + "node_bindings": { + "n0": { "ids": ["CHEBI:4567"] }, + "n1": { "ids": ["MONDO:4567"] } + }, + "analyses": [ + { + "resource_id": "infores:shepherd-aragorn", + "path_bindings": { + "p0": { "ids": ["auxGraph-4567-4567-4567-4567"] } + } + } + ] +} +``` diff --git a/ImplementationGuidance/Specifications/qedge_constraints_specification.md b/ImplementationGuidance/Specifications/qedge_constraints_specification.md new file mode 100644 index 00000000..7cd8fa5f --- /dev/null +++ b/ImplementationGuidance/Specifications/qedge_constraints_specification.md @@ -0,0 +1,198 @@ +# QEdge Constraints Specification + +The `QEdge` property `constraints` holds query-constraints on other Edge fields besides the main triple (`subject`, `predicate`, `object`). It and its keys should only be present when there's a constraint (`minProperties`/`minItems`: 1). + + There are 5 keys/Edge fields currently specified: +* `qualifiers` +* `knowledge_level` +* `agent_type` +* `sources` +* `attributes` + +The keys have an `AND` relationship (all must be met by a matched Edge). + + +## Qualifiers + +* Each object represents a qualifier-set, and multiple objects/sets have an `OR` relationship. +* Within an object, the keys are the "qualifier-type-ids" and their values are the "qualifier values". Multiple key/value pairs in one object/set have an `AND` relationship. +* If a specified value has descendants (ex: `activity_or_abundance`), the tool MUST treat those descendants (ex: `abundance`, `expression`, etc.) as if they were included using an `OR` relationship (aka "hierarchy expansion"). + +Example: the matched Edge's qualifier set should include either: +* `causes` + `decreased` (or its child `downregulated`) + `activity_or_abundance` (or 1 of its descendants) +* `vaccine_antigen` (current modeling doesn't include other qualifiers) + +```json +"qualifiers": [ // each object is a qualifier-set, OR behavior between them + { // AND behavior for elements within an object + "biolink:qualified_predicate": "causes", + "biolink:object_direction_qualifier": "decreased", + "biolink:object_aspect_qualifier": "activity_or_abundance" + }, + { + "biolink:causal_mechanism_qualifier": "vaccine_antigen", + } + ] +``` + + +## Knowledge Level / Agent Type (KL/AT) + +* two required keys: `behavior` (`ALLOW` or `DENY`) and `values` (an array of strings) +* `ALLOW` means "ANY (at least 1) of the `values` MUST be in the matched Edge's corresponding property". `DENY` means "ALL of the `values` MUST NOT be in the matched Edge's corresponding property". + * Note that KnowledgeGraph Edges have only 1 value each in their `knowledge_graph`/`agent_type` fields. +* The `values` MUST be valid, from the corresponding biolink enum for the property. +* If a specified value has descendants (ex: `automated_agent`), the tool MUST treat those descendants (ex: `text_mining_agent`, etc.) as if they were included in the `values` array (aka "hierarchy expansion"). + +```json +"": { + "behavior": "", + "values": ["xxxx", "yyyy"] +} +``` + +### Examples: + +The matched Edge's `knowledge_level` should be either `text_co_occurrence` or `not_provided` (currently used for text-mined edges). + +```json +"knowledge_level": { + "behavior": "ALLOW", + "values": ["text_co_occurrence", "not_provided"] +} +``` + +The matched Edge's `agent_type` should NOT be `not_provided` or `automated_agent` or any of `automated_agent`'s descendants. + +```json +"agent_type": { + "behavior": "DENY", + "values": ["not_provided", "automated_agent"] +} +``` + + +## Sources + +This constrains the infores CURIEs in the matched Edge's `sources` (`RetrievalSource.resource_id`). It has the same format as KL/AT plus the optional field `primary_only`: + +* if set to `true`: the constraint only applies to the `primary_knowledge_source` (there's only 1 `RetrievalSource` with this `resource_role` per Edge) +* if set to `false` or not present (default): the constraint applies to the entire set of RetrievalSources in `sources` + +Notes: +* should do only on a resource level, not a tool/Translator database level (ex: shouldn't use the infores for Tiers, Retriever, or an ARA) +* Note on value descendants doesn't apply (no hierarchy for infores) + +### Examples: + +The matched Edge's `sources` should include a RetrievalSource with the resource_id `infores:chembl` or `infores:dgidb`. The resource_role of the matching RetrievalSource doesn't matter. + +```json +"sources": { + "behavior": "ALLOW", + "values": ["infores:chembl", "infores:dgidb"] +} +``` + +The matched Edge's `primary_knowledge_source` should NOT be `infores:semmeddb` or `infores:text-mining-provider-targeted`. + +```json +"sources": { + "behavior": "DENY", + "values": ["infores:semmeddb", "infores:text-mining-provider-targeted"], + "primary_only": true +} +``` + + +## Attributes + +Format didn't change in TRAPI 2.0, see docs for details. + + +## Full Examples + +
QEdge with 4/5 constraint types, no KL (click to expand) +

+ +```json +{ + "subject": "n0", + "object": "n1", + "constraints": { + "agent_type": { // AT constraint + "behavior": "ALLOW", + "values": ["automated_agent"] + }, + "sources": { // source constraint: not semmeddb + "behavior": "DENY", + "values": ["infores:semmeddb"] + }, + "attributes": [ + { + "id": "biolink:z_score", // regular attribute constraint + "name": "z-score", + "operator": ">", + "value": 5 + } + ], + "qualifiers": [ + // one qualifier set + { + "biolink:subject_aspect_qualifier": "activity_or_abundance" + } + ] + } +} +``` + +

+
+ +
+ +
This example Edge (not real!) would fulfill those constraints. Its properties are put in same order as constraints for easy comparison (click to expand) +

+ +```json +{ + "subject": "NCBIGene:1234", + "object": "MONDO:1234", + "predicate": "biolink:associated_with", + "agent_type": "data_analysis_pipeline", // matches AT constraint: this is a child of automated_agent + "knowledge_level": "text_co_occurrence", + "sources": [ // matches source constraint: not semmeddb + { + "resource_id": "infores:diseases", + "resource_role": "primary_knowledge_source" + } + ], + "attributes": [ + { + "attribute_type_id": "biolink:z_score", // matches attrib constraint: >5 + "value": 6.435 + } + ], + "qualifiers": [ + { + "qualifier_type_id": "biolink:subject_direction_qualifier", + "qualifier_value": "decreased" + }, + { + "qualifier_type_id": "biolink:subject_aspect_qualifier", // matches qualifier constraint + "qualifier_value": "activity_or_abundance" + }, + { + "qualifier_type_id": "biolink:qualified_predicate", + "qualifier_value": "biolink:causes" + } + ] +} +``` + +

+
+ +
+ +[Response with all 5 kinds of constraints on QEdges](../DataExamples/2-0_example_response.json) diff --git a/docs/reference.md b/docs/reference.md index ccaf1397..5568acb0 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -2,7 +2,7 @@ ## Components -#### Query [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L277:L315) +#### Query [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L277:L315) 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. ##### Fixed Fields @@ -14,7 +14,7 @@ The Query class is used to package a user request for information. A Query objec | message | [Message](#message-) | 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. | | workflow | [workflow](#workflow-) | List of workflow steps to be executed. | -#### AsyncQuery [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L316:L339) +#### AsyncQuery [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L316:L339) The AsyncQuery class is effectively the same as the Query class but it requires a callback property. @@ -27,7 +27,7 @@ The AsyncQuery class is effectively the same as the Query class but it requires | --- | :---: | --- | | callback | `string` | 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. | -#### QueryParameters [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L340:L371) +#### QueryParameters [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L340:L371) Query-time parameters that don't affect the semantics of a query or intended workflow, but may affect overall behavior of the server in the execution of this query. The server MUST maintain parameters it is given in the response. ##### Fixed Fields @@ -38,7 +38,7 @@ Query-time parameters that don't affect the semantics of a query or intended wor | log_level | [LogLevel](#loglevel-) | The least critical level of logs to return. | | bypass_cache | `boolean` | 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). | -#### AsyncQueryResponse [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L372:L402) +#### AsyncQueryResponse [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L372:L402) The AsyncQueryResponse object contains a payload that must be returned from a submitted async_query. ##### Fixed Fields @@ -49,7 +49,7 @@ The AsyncQueryResponse object contains a payload that must be returned from a su | description | `string` | A brief human-readable description of the result of the async_query submission. | | job_id | `string` | An identifier for the submitted job that can be used with /async_query_status to receive an update on the status of the job. | -#### AsyncQueryStatusResponse [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L403:L445) +#### AsyncQueryStatusResponse [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L403:L445) The AsyncQueryStatusResponse object contains a payload that describes the current status of a previously submitted async_query. ##### Fixed Fields @@ -61,7 +61,7 @@ The AsyncQueryStatusResponse object contains a payload that describes the curren | logs | Array\[[LogEntry](#logentry-)\] | 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. | | response_url | `string` | Optional URL that can be queried to restrieve the full TRAPI Response. | -#### Response [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L446:L502) +#### Response [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L446:L502) 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. ##### Fixed Fields @@ -77,7 +77,7 @@ The Response object contains the main payload when a TRAPI query endpoint interp | schema_version | `string` | Version label of the TRAPI schema used in this document | | biolink_version | `string` | Version label of the Biolink model used in this document | -#### Message [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L503:L546) +#### Message [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L503:L546) 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. ##### Fixed Fields @@ -89,7 +89,7 @@ The message object holds the main content of a Query or a Response in three prop | knowledge_graph | [KnowledgeGraph](#knowledgegraph-) | KnowledgeGraph object that contains lists of nodes and edges in the thought graph corresponding to the message | | auxiliary_graphs | Map\[`string`, [AuxiliaryGraph](#auxiliarygraph-)\] | Dictionary of AuxiliaryGraph instances that are used by Knowledge Graph Edges and Result Analyses. These are referenced elsewhere by the dictionary key. | -#### LogEntry [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L547:L584) +#### LogEntry [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L547:L584) 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. ##### Fixed Fields @@ -101,7 +101,7 @@ The LogEntry object contains information useful for tracing and debugging across | code | `string` | One of a standardized set of short codes e.g. QueryNotTraversable, KPNotAvailable, KPResponseMalformed | | message | `string` | A human-readable log message | -#### LogLevel [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L585:L592) +#### LogLevel [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L585:L592) Logging level `string` @@ -113,7 +113,7 @@ one of: - INFO - DEBUG -#### Result [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L593:L623) +#### Result [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L593:L623) 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. ##### Fixed Fields @@ -123,7 +123,7 @@ A Result object specifies the nodes and edges in the knowledge graph that satisf | node_bindings | Map\[`string`, [NodeBinding](#nodebinding-)\] | 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). Because a given QNode may have multiple knowledge Nodes bound in the result, the NodeBinding object may list multiple knowledge Nodes. | | analyses | Array\[[Analysis](#analysis-)\] | The list of all Analysis components that contribute to the result. See below for Analysis components. | -#### NodeBinding [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L624:L643) +#### NodeBinding [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L624:L643) A NodeBinding object defines all relevant KnowledgeGraph Node mappings, identified by the corresponding object key identifier(s) of the Node(s) 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. ##### Fixed Fields @@ -132,7 +132,7 @@ A NodeBinding object defines all relevant KnowledgeGraph Node mappings, identifi | --- | :---: | --- | | ids | Array\[[CURIE](#curie-)\] | The CURIEs of one or more Nodes within the Knowledge Graph. | -#### Analysis [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L644:L713) +#### Analysis [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L644:L713) 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). ##### Fixed Fields @@ -147,7 +147,7 @@ An analysis is a dictionary that contains information about the result tied to a | scoring_method | `string` | An identifier and link to an explanation for the method used to generate the score | | attributes | Array\[[Attribute](#attribute-)\] | The attributes of this particular Analysis. | -#### EdgeBinding [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L714:L733) +#### EdgeBinding [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L714:L733) An EdgeBinding object defines all relevant KnowledgeGraph Edge mappings, 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. ##### Fixed Fields @@ -156,7 +156,7 @@ An EdgeBinding object defines all relevant KnowledgeGraph Edge mappings, identif | --- | :---: | --- | | ids | Array\[`string`\] | The key identifiers of specific KnowledgeGraph Edges. | -#### PathBinding [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L734:L750) +#### PathBinding [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L734:L750) A PathBinding object binds a single QueryGraph path (the key to this object) to one or more relevant AuxiliaryGraph ids containing a list of edges in the path. The Auxiliary Graph does not convey any order of edges in the path. ##### Fixed Fields @@ -165,7 +165,7 @@ A PathBinding object binds a single QueryGraph path (the key to this object) to | --- | :---: | --- | | ids | Array\[`string`\] | The key identifiers of specific auxiliary graphs. | -#### AuxiliaryGraph [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L751:L776) +#### AuxiliaryGraph [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L751:L776) A single AuxiliaryGraph instance that is used by Knowledge Graph Edges, Result Analysis support graphs, and Path Bindings. 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 collection of edges from the Knowledge Graph into a named graph that can be referenced from an Edge as evidence/explanation supporting that Edge, from a Result Analysis as information used to generate a score, or from a Path Binding as the path for that Analysis. ##### Fixed Fields @@ -174,7 +174,7 @@ A single AuxiliaryGraph instance that is used by Knowledge Graph Edges, Result A | --- | :---: | --- | | edges | Array\[`string`\] | List of edges that form the Auxiliary Graph. Each item is a reference to a single Knowledge Graph Edge. This list is not ordered, nor is the order intended to convey any relationship between the edges that form this Auxiliary Graph. | -#### KnowledgeGraph [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L777:L803) +#### KnowledgeGraph [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L777:L803) 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. ##### Fixed Fields @@ -184,7 +184,7 @@ The knowledge graph associated with a set of results. The instances of Node and | nodes | Map\[`string`, [Node](#node-)\] | Dictionary of Node instances used in the KnowledgeGraph, referenced elsewhere in the TRAPI output by the dictionary key. | | edges | Map\[`string`, [Edge](#edge-)\] | Dictionary of Edge instances used in the KnowledgeGraph, referenced elsewhere in the TRAPI output by the dictionary key. | -#### QueryGraph [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L804:L844) +#### QueryGraph [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L804:L844) 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. ##### Fixed Fields @@ -195,7 +195,7 @@ A graph representing a biomedical question. It serves as a template for each res | edges | Map\[`string`, [QEdge](#qedge-)\] | 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. | | paths | Map\[`string`, [QPath](#qpath-)\] | The QueryGraph path specification, used only for pathfinder type queries. The keys of this map are unique path identifiers and the corresponding values include the constraints on bound paths, in addition to specifying the subject, object, and intermediate QNodes. | -#### QNode [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L845:L920) +#### QNode [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L845:L920) 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. ##### Fixed Fields @@ -208,7 +208,7 @@ A node in the QueryGraph used to represent an entity in a query. If a CURIE is n | member_ids | Array\[[CURIE](#curie-)\] | 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 or COLLATE or when set_interpretation is absent. | | constraints | Array\[[AttributeConstraint](#attributeconstraint-)\] | A list of constraints applied to a query node. If there are multiple items, they must all be true (equivalent to AND) | -#### QEdge [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L921:L981) +#### QEdge [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L921:L981) 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. ##### Fixed Fields @@ -221,7 +221,7 @@ An edge in the QueryGraph used as a filter pattern specification in a query. If | object | `string` | Corresponds to the map key identifier of the object concept node anchoring the query filter pattern for the query relationship edge. | | constraints | [QEdgeConstraints](#qedgeconstraints-) | An object containing all constraints placed on the QEdge. ALL edges bound to this QEdge MUST conform to ALL given constraints; underlying edges (such as those appearing in supporting graphs) are not required to conform to the given constraints. | -#### QEdgeConstraints [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L982:L1056) +#### QEdgeConstraints [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L982:L1056) A subschema for constraints that may be placed on a given QEdge. ALL edges bound to the given QEdge MUST conform to ALL given constraints; underlying edges (such as those appearing in supporting graphs) are not required to conform to the given constraints. ##### Fixed Fields @@ -234,7 +234,7 @@ A subschema for constraints that may be placed on a given QEdge. ALL edges bound | qualifiers | Array\[[QualifierSetConstraint](#qualifiersetconstraint-)\] | A list of QualifierSetConstraints applied to a QEdge. If multiple QualifierSetConstraints 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 object of this QEdge have multiple categories or multiple curies, then constraints.qualifiers MUST NOT be specified because these complex use cases are not supported at this time. | | sources | [AllowDenyConstraint](#allowdenyconstraint-) \| `object` | A list of infores CURIEs which are either allowed or denied in the sources (resource_id) of the bound Edge. If `behavior` is set to "ALLOW", ANY (at least 1) of the given infores CURIEs MUST be present. If `behavior` is set to "DENY", then ALL given infores CURIEs MUST NOT be present. | -#### AllowDenyConstraint [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1057:L1080) +#### AllowDenyConstraint [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1057:L1080) A list of values which are to either be allowed or denied. If `behavior` is set to "ALLOW", then ANY (at least 1) of the given values MUST appear in the constrained property in order for it to meet the constraint (OR relationship). If `behavior` is set to "DENY", then ALL of the given values MUST NOT appear in the constrained property in order for it to meet the constraint (NOT (x OR y) relationship). ##### Fixed Fields @@ -244,7 +244,7 @@ A list of values which are to either be allowed or denied. If `behavior` is set | behavior | `string` | | | values | Array\[`string`\] | | -#### QPath [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1081:L1129) +#### QPath [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1081:L1129) A path in the QueryGraph used for pathfinder queries. Both subject and object MUST reference QNodes that have a CURIE in their ids field. Paths returned that bind to this QPath can represent some relationship between subject and object. ##### Fixed Fields @@ -256,7 +256,7 @@ A path in the QueryGraph used for pathfinder queries. Both subject and object MU | predicates | Array\[[BiolinkPredicate](#biolinkpredicate-)\] | QPath predicates are intended to convey what type of paths are desired, NOT a constraint on the types of predicates that may be in result paths. If no predicate is listed, the ARA SHOULD find paths such that the relationship represented by the path is a "related_to" relationship. 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. | | constraints | Array\[[PathConstraint](#pathconstraint-)\] | A list of constraints for the QPath. If multiple constraints are listed, it should be interpreted as an OR relationship. Each path returned is required to comply with at least one constraint. | -#### PathConstraint [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1130:L1146) +#### PathConstraint [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1130:L1146) A constraint for paths. ARAs must comply with constraints when finding paths. ##### Fixed Fields @@ -265,7 +265,7 @@ A constraint for paths. ARAs must comply with constraints when finding paths. | --- | :---: | --- | | intermediate_categories | Array\[[BiolinkEntity](#biolinkentity-)\] | A list of Biolink model categories by which to constrain paths returned. If multiple categories are listed, it should be interpreted as an AND relationship. Each path returned by ARAs MUST contain at least one node of each category listed. | -#### Node [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1147:L1181) +#### Node [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1147:L1181) A node in the KnowledgeGraph which represents some biomedical concept. Nodes are identified by the keys in the KnowledgeGraph Node mapping. ##### Fixed Fields @@ -277,7 +277,7 @@ A node in the KnowledgeGraph which represents some biomedical concept. Nodes are | attributes | Array\[[Attribute](#attribute-)\] | A list of attributes describing the node | | is_set | `boolean` | Indicates that the node represents a set of entities. If this property is missing or null, it is assumed to be false. | -#### Attribute [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1182:L1267) +#### Attribute [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1182:L1267) Generic attribute for a node or an edge that expands the key-value pair concept by including fields for additional metadata. These fields can be used to describe the source of the statement made in a key-value pair of the attribute object, or describe the attribute's value itself including its semantic type, or a url providing additional information about it. An attribute may be further qualified with sub-attributes (for example to provide confidence intervals on a value). ##### Fixed Fields @@ -293,7 +293,7 @@ Generic attribute for a node or an edge that expands the key-value pair concept | description | `string` | Human-readable description for the attribute and its value. | | attributes | Array\[[Attribute](#attribute-)\] | A list of attributes providing further information about the parent attribute (for example to provide provenance information about the parent attribute). | -#### Edge [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1268:L1350) +#### Edge [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1268:L1350) A specification of the semantic relationship linking two concepts that are expressed as nodes in the knowledge "thought" graph resulting from a query upon the underlying knowledge source. ##### Fixed Fields @@ -309,7 +309,7 @@ A specification of the semantic relationship linking two concepts that are expre | knowledge_level | `string` | One of the biolink-enumerated permissible values for `knowledge level` that provides the level of knowledge the Edge represents. (See https://biolink.github.io/biolink-model/KnowledgeLevelEnum/) | | agent_type | `string` | One of the biolink-enumerated permissible values for `agent type` that provides the kind of agent which originated the knowledge presented by the Edge. (See https://biolink.github.io/biolink-model/AgentTypeEnum/) | -#### Qualifier [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1351:L1387) +#### Qualifier [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1351:L1387) An additional nuance attached to an assertion ##### Fixed Fields @@ -319,7 +319,7 @@ An additional nuance attached to an assertion | qualifier_type_id | [CURIE](#curie-) | CURIE for a Biolink 'qualifier' association slot, generally taken from Biolink association slots designated for this purpose (that is, association slots with names ending in 'qualifier') e.g. biolink:subject_aspect_qualifier, biolink:subject_direction_qualifier, biolink:object_aspect_qualifier, etc. Such qualifiers are used to elaborate a second layer of meaning of a knowledge graph edge. Available qualifiers are edge properties in the Biolink Model (see https://biolink.github.io/biolink-model/docs/edge_properties.html) which have slot names with the suffix string 'qualifier'. | | qualifier_value | `string` | The value associated with the type of the qualifier, drawn from a set of controlled values by the type as specified in the Biolink model (e.g. 'expression' or 'abundance' for the qualifier type 'biolink:subject_aspect_qualifier', etc). The enumeration of qualifier values for a given qualifier type is generally going to be constrained by the category of edge (i.e. biolink:Association subtype) of the (Q)Edge. | -#### QualifierSetConstraint [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1388:L1403) +#### QualifierSetConstraint [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1388:L1403) A constraint on the qualifiers of a bound Edge (types and values). A given key-value pair defines the required qualifier_type_id and qualifier_value of one Qualifier, respectively. For example, a QualifierSetConstraint can constrain a "ChemicalX - affects - ?Gene" query to return only edges where ChemicalX specifically affects the 'expression' of the Gene, by constraining on the qualifier_type "biolink:object_aspect_qualifier" with a qualifier_value of "expression". Multiple type-value pairs have an AND relationship. @@ -329,19 +329,19 @@ A constraint on the qualifiers of a bound Edge (types and values). A given key-v | --- | :---: | --- | | ^biolink: | `string` | | -#### BiolinkEntity [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1404:L1415) +#### BiolinkEntity [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1404:L1415) Compact URI (CURIE) for a Biolink class, biolink:NamedThing or a child thereof. The CURIE must use the prefix 'biolink:' followed by the PascalCase class name. `string` (pattern: `^biolink:[A-Z][a-zA-Z]*$`) -#### BiolinkPredicate [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1416:L1428) +#### BiolinkPredicate [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1416:L1428) CURIE for a Biolink 'predicate' slot, taken from the Biolink slot ('is_a') hierarchy rooted in biolink:related_to (snake_case). This predicate defines the Biolink relationship between the subject and object nodes of a biolink:Association defining a knowledge graph edge. `string` (pattern: `^biolink:[a-z][a-z_]*$`) -#### CURIE [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1429:L1438) +#### CURIE [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1429:L1438) A Compact URI, consisting of a prefix and a reference separated by a colon, such as UniProtKB:P00738. Via an external context definition, the CURIE prefix and colon may be replaced by a URI prefix, such as http://identifiers.org/uniprot/, to form a full URI. `string` -#### MetaKnowledgeGraph [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1439:L1466) +#### MetaKnowledgeGraph [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1439:L1466) Knowledge-map representation of this TRAPI web service. The meta knowledge graph is composed of the union of most specific categories and predicates for each node and edge. ##### Fixed Fields @@ -351,7 +351,7 @@ Knowledge-map representation of this TRAPI web service. The meta knowledge graph | nodes | Map\[`string`, [MetaNode](#metanode-)\] | Collection of the most specific node categories provided by this TRAPI web service, indexed by Biolink class CURIEs. A node category is only exposed here if there is node for which that is the most specific category available. | | edges | Array\[[MetaEdge](#metaedge-)\] | List of the most specific edges/predicates provided by this TRAPI web service. A predicate is only exposed here if there is an edge for which the predicate is the most specific available. | -#### MetaNode [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1467:L1490) +#### MetaNode [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1467:L1490) Description of a node category provided by this TRAPI web service. ##### Fixed Fields @@ -361,7 +361,7 @@ Description of a node category provided by this TRAPI web service. | id_prefixes | Array\[`string`\] | List of CURIE prefixes for the node category that this TRAPI web service understands and accepts on the input. | | attributes | Array\[[MetaAttribute](#metaattribute-)\] | Node attributes provided by this TRAPI web service. | -#### MetaEdge [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1491:L1555) +#### MetaEdge [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1491:L1555) Edge in a meta knowledge map describing relationship between a subject Biolink class and an object Biolink class. ##### Fixed Fields @@ -376,7 +376,7 @@ Edge in a meta knowledge map describing relationship between a subject Biolink c | qualifiers | Array\[[MetaQualifier](#metaqualifier-)\] | Qualifiers that are possible to be found on this edge type. | | association | [BiolinkEntity](#biolinkentity-) | The Biolink association type (entity) that this edge represents. Associations are classes in Biolink that represent a relationship between two entities. For example, the association 'gene interacts with gene' is represented by the Biolink class, 'biolink:GeneToGeneAssociation'. If association is filled out, then the testing harness can help validate that the qualifiers are being used correctly. | -#### MetaQualifier [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1556:L1575) +#### MetaQualifier [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1556:L1575) ##### Fixed Fields @@ -385,7 +385,7 @@ Edge in a meta knowledge map describing relationship between a subject Biolink c | qualifier_type_id | [CURIE](#curie-) | The CURIE of the qualifier type. | | applicable_values | Array\[`string`\] | The list of values that are possible for this qualifier. | -#### MetaAttribute [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1576:L1613) +#### MetaAttribute [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1576:L1613) ##### Fixed Fields @@ -397,7 +397,7 @@ Edge in a meta knowledge map describing relationship between a subject Biolink c | constraint_use | `boolean` | Indicates whether this attribute can be used as a query constraint. | | constraint_name | `string` | Human-readable name or label for the constraint concept. Required whenever constraint_use is true. | -#### AttributeConstraint [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1614:L1707) +#### AttributeConstraint [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1614:L1707) Generic query constraint for a query node or query edge ##### Fixed Fields @@ -412,7 +412,7 @@ Generic query constraint for a query node or query edge | unit_id | any | CURIE of the units of the value or list of values in the 'value' property. The Units of Measurement Ontology (UO) should be used if possible. The unit_id MUST be provided for (lists of) numerical values that correspond to a quantity that has units. | | unit_name | any | Term name that is associated with the CURIE of the units of the value or list of values in the 'value' property. The Units of Measurement Ontology (UO) SHOULD be used if possible. This property SHOULD be provided if a unit_id is provided. This is redundant but recommended for human readability. | -#### RetrievalSource [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1708:L1765) +#### RetrievalSource [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1708:L1765) Provides information about how a particular InformationResource served as a source from which knowledge expressed in an Edge, or data used to generate this knowledge, was retrieved. ##### Fixed Fields @@ -424,7 +424,7 @@ Provides information about how a particular InformationResource served as a sour | upstream_resource_ids | Array\[[CURIE](#curie-)\] | An upstream InformationResource from which the resource being described directly retrieved a record of the knowledge expressed in the Edge, or data used to generate this knowledge. This is an array because there are cases where a merged Edge holds knowledge that was retrieved from multiple sources. e.g. an Edge provided by the ARAGORN ARA can expressing knowledge it retrieved from both the automat-mychem-info and molepro KPs, which both provided it with records of this single fact. | | source_record_urls | Array\[`string`\] | A URL linking to a specific web page or document provided by the source, that contains a record of the knowledge expressed in the Edge. If the knowledge is contained in more than one web page on an Information Resource's site, urls MAY be provided for each. For example, Therapeutic Targets Database (TTD) has separate web pages for 'Imatinib' and its protein target KIT, both of which hold the claim that 'the KIT protein is a therapeutic target for Imatinib'. | -#### ResourceRoleEnum [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0/TranslatorReasonerAPI.yaml#L1766:L1777) +#### ResourceRoleEnum [↗](https://github.com/NCATSTranslator/ReasonerAPI/blob/2.0-migration-guide-plus/TranslatorReasonerAPI.yaml#L1766:L1777) The role played by the InformationResource in serving as a source for an Edge. Note that a given Edge should have one and only one 'primary' source, and may have any number of 'aggregator' or 'supporting data' sources. This enumeration is found in Biolink Model, but is repeated here for convenience. `string`