From 0738033386dd23d03110197e4b4fdd1d5788fda6 Mon Sep 17 00:00:00 2001 From: vdancik Date: Wed, 4 Mar 2026 14:30:18 -0500 Subject: [PATCH 01/16] update links to examples --- .../Miscellaneous/examples_and_rules.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ImplementationGuidance/Miscellaneous/examples_and_rules.md b/ImplementationGuidance/Miscellaneous/examples_and_rules.md index a333cf60..4617a766 100644 --- a/ImplementationGuidance/Miscellaneous/examples_and_rules.md +++ b/ImplementationGuidance/Miscellaneous/examples_and_rules.md @@ -11,7 +11,7 @@ object: NCBIGene:2099 # ESR1 object_aspect_qualifier: degradation object_direction_qualifier: decreased ``` -* [object_qualifiers.json](object_qualifiers.json) +* [object_qualifiers.json](../DataExamples/object_qualifiers.json) Note: the predicate chosen should reflect the relationship between the subject and the object, and is not required to be "affects". For example, below we see a statement where the relationship between Bisphenol A and ESR1 is @@ -42,7 +42,7 @@ object_aspect_qualifier: expression object_direction_qualifier: increased ``` -* [subject_and_object_qualifiers.json](subject_and_object_qualifiers.json) +* [subject_and_object_qualifiers.json](../DataExamples/subject_and_object_qualifiers.json) _"Fenofibrate is an agonist of PPARA protein"_ @@ -76,21 +76,21 @@ pathway_context_qualifier: GO:0038134 # ERBB2-EGFR signaling pathway Please note, pathway_context_qualifier is still under discussion in the Biolink Model. If you are trying to represent GO-CAMs, please contact the Biolink Model team for more information. -* [complex_gocam_qualifiers.json](complex_gocam_qualifiers.json) +* [complex_gocam_qualifiers.json](../DataExamples/complex_gocam_qualifiers.json) ### Querying for "_affects transport of_ *OR* _affects localization of_" with qualifiers instead of predicates. _"What chemicals affect either the localization or the transport of ADRB2"_ -* [localization_or_transport.json](localization_or_transport.json) +* [localization_or_transport.json](../DataExamples/localization_or_transport.json) ### When to use predicate=causes vs. qualified_predicate=causes _"What chemicals cause increased activity of PPARA protein"_ -* [causes_predicate_vs_qualifier.json](causes_predicate_vs_qualifier.json) +* [causes_predicate_vs_qualifier.json](../DataExamples/causes_predicate_vs_qualifier.json) Note: in this example we need to convert the user's request for "causes" (predicate) to an "affects" predicate with a "causes" qualified_predicate. From 4b5f6930ea338cfa5a91652c72a97f198a5b705b Mon Sep 17 00:00:00 2001 From: vdancik Date: Wed, 4 Mar 2026 14:33:18 -0500 Subject: [PATCH 02/16] update links to examples --- ImplementationGuidance/Miscellaneous/examples_and_rules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ImplementationGuidance/Miscellaneous/examples_and_rules.md b/ImplementationGuidance/Miscellaneous/examples_and_rules.md index 4617a766..acbd7412 100644 --- a/ImplementationGuidance/Miscellaneous/examples_and_rules.md +++ b/ImplementationGuidance/Miscellaneous/examples_and_rules.md @@ -102,9 +102,9 @@ These rules can not be enforced in the schema for TRAPI, but should be implement 1. __general rules__ 1. There MUST be only one of each type of qualifier in any edges.qualifier_constraints.qualifier_set 1. There MUST be only one qualified_predicate for each set of qualifiers in a QualifierConstraint. - 2. qualified_predicate is an optional qualifier. (see [localization_or_transport.json](localization_or_transport.json)) + 2. qualified_predicate is an optional qualifier. (see [localization_or_transport.json](../DataExamples/localization_or_transport.json)) 1. Both the qualified_predicate and the predicate edge properties SHOULD be queried when a predicate is provided. - see [causes_predicate_vs_qualifier.json](causes_predicate_vs_qualifier.json) + see [causes_predicate_vs_qualifier.json](../DataExamples/causes_predicate_vs_qualifier.json) 2. If a KP receives non-empty QEdge.qualifier_constraints, it MUST only return edges that satisfy the entire set of qualifier_constraints. If a KP does not yet support QEdge.qualifier_constraints, it MUST return an empty response because no matches are found. From 301c69a8b3ccb5ce0bc9f7a264889399151ea39d Mon Sep 17 00:00:00 2001 From: vdancik Date: Wed, 4 Mar 2026 14:52:40 -0500 Subject: [PATCH 03/16] Update knowledge_level_agent_type_specification.md --- ...nowledge_level_agent_type_specification.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md b/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md index aa823671..88f38fb1 100644 --- a/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md +++ b/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md @@ -50,19 +50,16 @@ NOTE that the notion of a 'level' of knowledge can in one sense relate to the st 1. Knowledge Providers MUST report one and only one `agent type` on each Edge they return in a TRAPI message, using an Attribute object keyed on the `agent_type` property. The value of this property MUST come from the biolink:AgentTypeEnum. - { - "attribute_type_id": "biolink:agent_type", - "value": "manual_agent", - "attribute_source": "infores:molepro" - } - 2. Knowledge Providers MUST report one and only one `knowledge level` for each Edge returned in a TRAPI message, using an Attribute object keyed on the `knowledge_level` property. The value MUST come from the biolink:KnowledgeLevelEnum. - { - "attribute_type_id": "biolink:knowledge_level", - "value": "knowledge_assertion", - "attribute_source": "infores:molepro" + "edge_id": { + "subject": "PUBCHEM.COMPOUND:6623", + "predicate": "biolink:affects", + "object": "HGNC:3467", + "sources": { . . . } + "knowledge_level": "knowledge_assertion", + "agent_type": "manual_agent" } -3. The main challenge in applying this standard concerns selecting appropriate agent type and knowledge level terms for a given Edge. To assist KPs in this task, a [Supplemental Guidance document](https://docs.google.com/document/d/140dtM5CjWM97JiBRdAmDT-9IKqHoOj-xbE_5TWkdYqg/edit) provides additional implementation support beyond the base specification above. This includes clarification of key distinctions, tips for proper term selection, and a corpus of examples illustrating how agent type and knowledge level terms are applied to the diverse kinds of Edges provided in Translator knowledge graphs. +4. The main challenge in applying this standard concerns selecting appropriate agent type and knowledge level terms for a given Edge. To assist KPs in this task, a [Supplemental Guidance document](https://docs.google.com/document/d/140dtM5CjWM97JiBRdAmDT-9IKqHoOj-xbE_5TWkdYqg/edit) provides additional implementation support beyond the base specification above. This includes clarification of key distinctions, tips for proper term selection, and a corpus of examples illustrating how agent type and knowledge level terms are applied to the diverse kinds of Edges provided in Translator knowledge graphs. From 2327d37ba6870694b3255dfa0a36a5860ca8267e Mon Sep 17 00:00:00 2001 From: vdancik Date: Wed, 4 Mar 2026 15:05:16 -0500 Subject: [PATCH 04/16] update knowledge_level_agent_type_specification.md --- .../knowledge_level_agent_type_specification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md b/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md index 88f38fb1..1d61a71e 100644 --- a/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md +++ b/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md @@ -48,9 +48,9 @@ NOTE that the notion of a 'level' of knowledge can in one sense relate to the st ## Implementation Guidance -1. Knowledge Providers MUST report one and only one `agent type` on each Edge they return in a TRAPI message, using an Attribute object keyed on the `agent_type` property. The value of this property MUST come from the biolink:AgentTypeEnum. +1. Knowledge Providers MUST report one and only one `agent type` on each Edge they return in a TRAPI message, using an `agent_type` property. The value of this property MUST come from the [biolink:AgentTypeEnum](https://biolink.github.io/biolink-model/AgentTypeEnum/). -2. Knowledge Providers MUST report one and only one `knowledge level` for each Edge returned in a TRAPI message, using an Attribute object keyed on the `knowledge_level` property. The value MUST come from the biolink:KnowledgeLevelEnum. +2. Knowledge Providers MUST report one and only one `knowledge level` for each Edge returned in a TRAPI message, using a `knowledge_level` property. The value MUST come from the [biolink:KnowledgeLevelEnum](https://biolink.github.io/biolink-model/KnowledgeLevelEnum/). "edge_id": { "subject": "PUBCHEM.COMPOUND:6623", @@ -61,5 +61,5 @@ NOTE that the notion of a 'level' of knowledge can in one sense relate to the st "agent_type": "manual_agent" } -4. The main challenge in applying this standard concerns selecting appropriate agent type and knowledge level terms for a given Edge. To assist KPs in this task, a [Supplemental Guidance document](https://docs.google.com/document/d/140dtM5CjWM97JiBRdAmDT-9IKqHoOj-xbE_5TWkdYqg/edit) provides additional implementation support beyond the base specification above. This includes clarification of key distinctions, tips for proper term selection, and a corpus of examples illustrating how agent type and knowledge level terms are applied to the diverse kinds of Edges provided in Translator knowledge graphs. +3. The main challenge in applying this standard concerns selecting appropriate agent type and knowledge level terms for a given Edge. To assist KPs in this task, a [Supplemental Guidance document](https://docs.google.com/document/d/140dtM5CjWM97JiBRdAmDT-9IKqHoOj-xbE_5TWkdYqg/edit) provides additional implementation support beyond the base specification above. This includes clarification of key distinctions, tips for proper term selection, and a corpus of examples illustrating how agent type and knowledge level terms are applied to the diverse kinds of Edges provided in Translator knowledge graphs. From 85e536ccec8d69ae3fc010d65fc550dcafd43206 Mon Sep 17 00:00:00 2001 From: vdancik Date: Wed, 4 Mar 2026 17:15:47 -0500 Subject: [PATCH 05/16] add specification for QNode.set_interpretation --- .../Specifications/query_specification.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index cf8e3364..05fa57e2 100644 --- a/ImplementationGuidance/Specifications/query_specification.md +++ b/ImplementationGuidance/Specifications/query_specification.md @@ -16,12 +16,20 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. ## QNode.ids - MAY be null, or MAY be missing. The meaning is the same. - MUST NOT be an empty array (#199) -- If more than one element is present, the elements MUST be treated in the sense of an "or" list. - This effectively creates a simple batch query mechanism. +- If more than one element is present, the elements MUST be treated accoring to Qnode.set_interpretation. - The list SHOULD NOT be used by the client to provide equivalent CURIEs to the server - If the server considers a subset of items in the list as equivalent CURIEs, the server SHOULD merge the subset into a single KnowledgeGraph Node +## QNode.set_interpretation +- MAY be null, or MAY be missing. If null or missing, the default is "BATCH". +- MUST be one of the following values: "BATCH", "ALL", "MANY", or "COLLATE" +- If set_interpretation is "BATCH", each CURIE in the ids list is treated independently. Results MUST include answers for each queried CURIE separately. +- If set_interpretation is "ALL", all specified CURIEs MUST appear in each Result. Multiple CURIEs are combined into a set, and the ids field MUST hold a single UUID representing this set, with individual members in member_ids. +- If set_interpretation is "MANY", member CURIEs MUST form one or more sets in the Results. Multiple CURIEs are combined into a set, and the ids field MUST hold a single UUID representing this set, with individual members in member_ids. Sets with more members are generally considered more desirable than sets with fewer members. +- If set_interpretation is "COLLATE", it MAY only be used when no ids are provided (QNode.ids is null or missing). Multiple matching nodes MUST be collated into a single Result rather than separated into separate Results. + + ## QNode.categories - MAY be null, or MAY be missing. The meaning is the same: matching Nodes may be any category - If QNode.categories is [ 'biolink:NamedThing' ], it means matching Nodes may be any category From 716a5faeef568b002b043ce4a81a97429094b1d6 Mon Sep 17 00:00:00 2001 From: vdancik Date: Wed, 4 Mar 2026 17:44:32 -0500 Subject: [PATCH 06/16] update examples of source constrains --- .../Specifications/query_specification.md | 56 +++++++++---------- 1 file changed, 25 insertions(+), 31 deletions(-) diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index 05fa57e2..94c1da1a 100644 --- a/ImplementationGuidance/Specifications/query_specification.md +++ b/ImplementationGuidance/Specifications/query_specification.md @@ -91,8 +91,8 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. return a runtime error gracefully. ## Specifying permitted and excluded KPs to an ARA -- The proper syntax for specifying or excluding specific KPs to consult to an ARA MUST be done - via a `attribute_constraint` on a QEdge. The following is a complete Query example that disallows the +- The proper syntax for specifying or excluding specific knowledge sources (infores CURIEs) to an ARA MUST be done + via a `sources` constraint on a QEdge within the `constraints` object. The following is a complete Query example that disallows the use of SemMedDB: ``` @@ -106,15 +106,14 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. "predicates": [ "biolink:entity_negatively_regulates_entity" ], - "attribute_constraints": [ - { - "id": "biolink:knowledge_source", - "name": "knowledge source", - "value": "infores:semmeddb", - "not": true, - "operator": "==" + "constraints": { + "sources": { + "behavior": "DENY", + "values": [ + "infores:semmeddb" + ] } - ] + } } }, "nodes": { @@ -139,36 +138,31 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. A general "allowlist" SHOULD look like this: ``` - "attribute_constraints": [ - { - "id": "biolink:knowledge_source", - "name": "knowledge source", - "value": [ + "constraints": { + "sources": { + "behavior": "ALLOW", + "values": [ "infores:rtx-kg2", - "infores:biothings-explorer", - ], - "operator": "==" + "infores:biothings-explorer" + ] } - ], + }, ``` -(when the value is a list, the "==" operator works like a SQL "IN" clause, as clearly documented in the TRAPI yaml) +(when `behavior` is set to "ALLOW", ANY (at least 1) of the given infores CURIEs MUST be present in the sources of bound edges) Here is what a general "denylist" should look like: ``` - "attribute_constraints": [ - { - "id": "biolink:knowledge_source", - "name": "knowledge source", - "value": [ + "constraints": { + "sources": { + "behavior": "DENY", + "values": [ "infores:rtx-kg2", - "infores:biothings-explorer", - ], - "not": true, - "operator": "==" + "infores:biothings-explorer" + ] } - ], + }, ``` -(when the value is a list, the "==" operator combined with ' "not": true ' works like a SQL "NOT IN" clause, as clearly documented in the TRAPI yaml) +(when `behavior` is set to "DENY", ALL of the given infores CURIEs MUST NOT be present in the sources of bound edges) From be0673ab055dd30a6670bf846933f33386c7fa5e Mon Sep 17 00:00:00 2001 From: vdancik Date: Thu, 5 Mar 2026 16:59:09 -0500 Subject: [PATCH 07/16] update source constrains examples --- .../Specifications/query_specification.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index 94c1da1a..2a8fd81d 100644 --- a/ImplementationGuidance/Specifications/query_specification.md +++ b/ImplementationGuidance/Specifications/query_specification.md @@ -90,7 +90,7 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. large (e.g., if the client specified `MONDO:0000001: disease or disorder`), the server SHOULD return a runtime error gracefully. -## Specifying permitted and excluded KPs to an ARA +## Specifying permitted and excluded sources to an ARA - The proper syntax for specifying or excluding specific knowledge sources (infores CURIEs) to an ARA MUST be done via a `sources` constraint on a QEdge within the `constraints` object. The following is a complete Query example that disallows the use of SemMedDB: @@ -136,33 +136,29 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. } ``` -A general "allowlist" SHOULD look like this: +An allowlist with `behavior` set to "ALLOW" requires at least one of the specified infores CURIEs to be present in the sources of bound edges: ``` "constraints": { "sources": { "behavior": "ALLOW", "values": [ - "infores:rtx-kg2", - "infores:biothings-explorer" + "infores:chembl", + "infores:chebi" ] } }, ``` -(when `behavior` is set to "ALLOW", ANY (at least 1) of the given infores CURIEs MUST be present in the sources of bound edges) - -Here is what a general "denylist" should look like: +A denylist with `behavior` set to "DENY" excludes all of the specified infores CURIEs from the sources of bound edges: ``` "constraints": { "sources": { "behavior": "DENY", "values": [ - "infores:rtx-kg2", - "infores:biothings-explorer" + "infores:ctd", + "infores:reactome" ] } }, ``` -(when `behavior` is set to "DENY", ALL of the given infores CURIEs MUST NOT be present in the sources of bound edges) - From b8b271c5af5d49a42e4ad5fab75ce021de596c36 Mon Sep 17 00:00:00 2001 From: vdancik Date: Thu, 19 Mar 2026 14:36:27 -0400 Subject: [PATCH 08/16] clarify QEdge constraints also rename examples file --- ...and_rules.md => qualifier_examples_and_rules.md} | 2 ++ .../Specifications/query_specification.md | 13 +++++++------ 2 files changed, 9 insertions(+), 6 deletions(-) rename ImplementationGuidance/Miscellaneous/{examples_and_rules.md => qualifier_examples_and_rules.md} (98%) diff --git a/ImplementationGuidance/Miscellaneous/examples_and_rules.md b/ImplementationGuidance/Miscellaneous/qualifier_examples_and_rules.md similarity index 98% rename from ImplementationGuidance/Miscellaneous/examples_and_rules.md rename to ImplementationGuidance/Miscellaneous/qualifier_examples_and_rules.md index acbd7412..d91e8bd1 100644 --- a/ImplementationGuidance/Miscellaneous/examples_and_rules.md +++ b/ImplementationGuidance/Miscellaneous/qualifier_examples_and_rules.md @@ -85,6 +85,8 @@ _"What chemicals affect either the localization or the transport of ADRB2"_ * [localization_or_transport.json](../DataExamples/localization_or_transport.json) +Note: in this example we also specify set_interpretation to have results collated. + ### When to use predicate=causes vs. qualified_predicate=causes diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index 2a8fd81d..65567a37 100644 --- a/ImplementationGuidance/Specifications/query_specification.md +++ b/ImplementationGuidance/Specifications/query_specification.md @@ -75,13 +75,14 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. it MUST immediately respond with an error Code "UnsupportedConstraint" and list all constraint names that it does not support. -## QEdge.qualifier_constraints -- If a KP server receives any QEdge.qualifier_constraints, it MUST only return qualified - edges that are compatible with the constraints. It MUST NOT return any unqualified edges. - If a KP does not yet support QEdge.qualifier_constraints, it MUST return an empty response +## QEdge.constraints +- If a KP server receives any QEdge.constraints.qualifiers, it MUST only return + edges that are compatible with the constraints. +- If a KP server receives any QEdge.constraints.qualifiers, it MUST NOT return any unqualified edges. + If a KP does not yet support QEdge.qualifiers, it MUST return an empty response because no matches are possible. -- If an ARA server receives any QEdge.qualifier_constraints, it MUST relay all - QEdge.qualifier_constraints to its KP(s) to satisfy. +- If an ARA server receives any QEdge.constraints, it MUST relay all + QEdge.constraints to its KP(s) to satisfy. ## info.x-trapi.batch_size_limit - This batch size limit refers to the maximum length of any single QNode.ids list. The limit From 5ec61c2042cbeca2417b4a0bf60f80e9b016eb0b Mon Sep 17 00:00:00 2001 From: vdancik Date: Thu, 19 Mar 2026 16:28:08 -0400 Subject: [PATCH 09/16] QEdge qualifiers --- .../Specifications/query_specification.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index 65567a37..01e1b34e 100644 --- a/ImplementationGuidance/Specifications/query_specification.md +++ b/ImplementationGuidance/Specifications/query_specification.md @@ -77,10 +77,10 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. ## QEdge.constraints - If a KP server receives any QEdge.constraints.qualifiers, it MUST only return - edges that are compatible with the constraints. -- If a KP server receives any QEdge.constraints.qualifiers, it MUST NOT return any unqualified edges. - If a KP does not yet support QEdge.qualifiers, it MUST return an empty response - because no matches are possible. + edges that are compatible with the constraints. If a KP does not yet support QEdge.constraints, + it MUST return an empty response because no matches are possible. +- If a KP server receives any QEdge.constraints.qualifiers, it MUST NOT return any edges that + don't have qualifiers. - If an ARA server receives any QEdge.constraints, it MUST relay all QEdge.constraints to its KP(s) to satisfy. From c0eb695545ef961ed42c1a8808cb1e4655e4a425 Mon Sep 17 00:00:00 2001 From: vdancik Date: Thu, 19 Mar 2026 16:32:51 -0400 Subject: [PATCH 10/16] QEdge constraints --- ImplementationGuidance/Specifications/query_specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index 01e1b34e..f0544f24 100644 --- a/ImplementationGuidance/Specifications/query_specification.md +++ b/ImplementationGuidance/Specifications/query_specification.md @@ -76,7 +76,7 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. names that it does not support. ## QEdge.constraints -- If a KP server receives any QEdge.constraints.qualifiers, it MUST only return +- If a KP server receives any QEdge.constraints, it MUST only return edges that are compatible with the constraints. If a KP does not yet support QEdge.constraints, it MUST return an empty response because no matches are possible. - If a KP server receives any QEdge.constraints.qualifiers, it MUST NOT return any edges that From d670e2c3f3438bf2ad04a3848081360df9aefe39 Mon Sep 17 00:00:00 2001 From: colleenXu <43731687+colleenXu@users.noreply.github.com> Date: Thu, 19 Mar 2026 20:37:25 +0000 Subject: [PATCH 11/16] Update docs/reference.md [no ci] --- docs/reference.md | 78 +++++++++++++++++++++++------------------------ 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/reference.md b/docs/reference.md index ccaf1397..49dced33 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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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-specification-update/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` From 6a46d09fef79f066329551d127ac8f549754572d Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Thu, 19 Mar 2026 23:37:35 -0700 Subject: [PATCH 12/16] query spec: my proposed edit to discussed line --- ImplementationGuidance/Specifications/query_specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index f0544f24..bbd097e1 100644 --- a/ImplementationGuidance/Specifications/query_specification.md +++ b/ImplementationGuidance/Specifications/query_specification.md @@ -77,8 +77,8 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. ## QEdge.constraints - If a KP server receives any QEdge.constraints, it MUST only return - edges that are compatible with the constraints. If a KP does not yet support QEdge.constraints, - it MUST return an empty response because no matches are possible. + edges that are compatible with the constraints. If a KP server receives a query that contains QEdge + constraints that it does not support yet, it MUST return an empty response. - If a KP server receives any QEdge.constraints.qualifiers, it MUST NOT return any edges that don't have qualifiers. - If an ARA server receives any QEdge.constraints, it MUST relay all From a852f5c1cd437362e27ef2e1904949ef530cf682 Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Thu, 19 Mar 2026 23:40:07 -0700 Subject: [PATCH 13/16] qualifier doc: move from Misc folder to Specifications I propose doing this because I don't think it's that diff from other spec docs --- .../qualifier_examples_and_rules.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ImplementationGuidance/{Miscellaneous => Specifications}/qualifier_examples_and_rules.md (100%) diff --git a/ImplementationGuidance/Miscellaneous/qualifier_examples_and_rules.md b/ImplementationGuidance/Specifications/qualifier_examples_and_rules.md similarity index 100% rename from ImplementationGuidance/Miscellaneous/qualifier_examples_and_rules.md rename to ImplementationGuidance/Specifications/qualifier_examples_and_rules.md From 1f1cca380e2364b5b311b31e4e77dc908adb8702 Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Thu, 26 Mar 2026 12:27:37 -0700 Subject: [PATCH 14/16] query spec: change behavior if doesn't support constraints asked --- ImplementationGuidance/Specifications/query_specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index c5f58e21..72491991 100644 --- a/ImplementationGuidance/Specifications/query_specification.md +++ b/ImplementationGuidance/Specifications/query_specification.md @@ -78,7 +78,7 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119 https://tools.ietf. ## QEdge.constraints - If a KP server receives any QEdge.constraints, it MUST only return edges that are compatible with the constraints. If a KP server receives a query that contains QEdge - constraints that it does not support yet, it MUST return an empty response. + constraints that it does not support yet, it MUST immediately respond with an error Code "UnsupportedConstraint" and list all the specified constraints that it does not support. - If a KP server receives any QEdge.constraints.qualifiers, it MUST NOT return any edges that don't have qualifiers. - If an ARA server receives any QEdge.constraints, it MUST relay all From 89e40dea384f0f370805b271fdf6c07790098eb8 Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Thu, 26 Mar 2026 12:30:42 -0700 Subject: [PATCH 15/16] qualifier ex/rules: rearrange --- .../qualifier_examples_and_rules.md | 55 ++++++++++--------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/ImplementationGuidance/Specifications/qualifier_examples_and_rules.md b/ImplementationGuidance/Specifications/qualifier_examples_and_rules.md index d91e8bd1..167e9e4b 100644 --- a/ImplementationGuidance/Specifications/qualifier_examples_and_rules.md +++ b/ImplementationGuidance/Specifications/qualifier_examples_and_rules.md @@ -1,3 +1,31 @@ +## Qualifier Rules + +These rules can not be enforced in the schema for TRAPI, but should be implemented in a validation layer. + +1. __general rules__ + 1. There MUST be only one of each type of qualifier in any edges.qualifier_constraints.qualifier_set + 1. There MUST be only one qualified_predicate for each set of qualifiers in a QualifierConstraint. + 2. qualified_predicate is an optional qualifier. (see [localization_or_transport.json](../DataExamples/localization_or_transport.json)) + 1. Both the qualified_predicate and the predicate edge properties SHOULD be queried when a predicate is provided. + see [causes_predicate_vs_qualifier.json](../DataExamples/causes_predicate_vs_qualifier.json) + 2. If a KP receives non-empty QEdge.qualifier_constraints, it MUST only return edges that satisfy the entire set of + qualifier_constraints. If a KP does not yet support QEdge.qualifier_constraints, it MUST return an empty response + because no matches are found. + 1. If a knowledge statement contains more qualifiers or differently typed qualifiers than those specified in + edges.qualifier_constraints.qualifier_set in addition to the entire set of qualifier_constraints, the knowledge + statement MAY also be returned. + 3. Qualifier constraints should be treated as "or" constraints. +2. __qualifier_value__ + 1. is constrained by either: an enumeration in biolink, or an ontology term. + 1. When an ontology term is used, the assumption is that annotations that use this term or any of its children + should be returned. + 2. When an enumerated value is used, the assumption is that annotations that use this enumerated value or any + of its children should be returned. + 1. For example, if a query asks for "biolink:object_aspect_qualifier" = "abundance", + then, aspects matching any child of "abundance" should also be returned (if the other qualifiers used in this + query are also satisfied). + + ## Biolink Qualifiers Examples ### Object qualifiers @@ -96,30 +124,3 @@ _"What chemicals cause increased activity of PPARA protein"_ Note: in this example we need to convert the user's request for "causes" (predicate) to an "affects" predicate with a "causes" qualified_predicate. - -### Qualifier Rules - -These rules can not be enforced in the schema for TRAPI, but should be implemented in a validation layer. - -1. __general rules__ - 1. There MUST be only one of each type of qualifier in any edges.qualifier_constraints.qualifier_set - 1. There MUST be only one qualified_predicate for each set of qualifiers in a QualifierConstraint. - 2. qualified_predicate is an optional qualifier. (see [localization_or_transport.json](../DataExamples/localization_or_transport.json)) - 1. Both the qualified_predicate and the predicate edge properties SHOULD be queried when a predicate is provided. - see [causes_predicate_vs_qualifier.json](../DataExamples/causes_predicate_vs_qualifier.json) - 2. If a KP receives non-empty QEdge.qualifier_constraints, it MUST only return edges that satisfy the entire set of - qualifier_constraints. If a KP does not yet support QEdge.qualifier_constraints, it MUST return an empty response - because no matches are found. - 1. If a knowledge statement contains more qualifiers or differently typed qualifiers than those specified in - edges.qualifier_constraints.qualifier_set in addition to the entire set of qualifier_constraints, the knowledge - statement MAY also be returned. - 3. Qualifier constraints should be treated as "or" constraints. -2. __qualifier_value__ - 1. is constrained by either: an enumeration in biolink, or an ontology term. - 1. When an ontology term is used, the assumption is that annotations that use this term or any of its children - should be returned. - 2. When an enumerated value is used, the assumption is that annotations that use this enumerated value or any - of its children should be returned. - 1. For example, if a query asks for "biolink:object_aspect_qualifier" = "abundance", - then, aspects matching any child of "abundance" should also be returned (if the other qualifiers used in this - query are also satisfied). From 14397dcf60b603cec4dd252e617e66c3f0b9238c Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Thu, 26 Mar 2026 12:31:16 -0700 Subject: [PATCH 16/16] change file name: qualifier rules and ex --- ...fier_examples_and_rules.md => qualifier_rules_and_examples.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ImplementationGuidance/Specifications/{qualifier_examples_and_rules.md => qualifier_rules_and_examples.md} (100%) diff --git a/ImplementationGuidance/Specifications/qualifier_examples_and_rules.md b/ImplementationGuidance/Specifications/qualifier_rules_and_examples.md similarity index 100% rename from ImplementationGuidance/Specifications/qualifier_examples_and_rules.md rename to ImplementationGuidance/Specifications/qualifier_rules_and_examples.md