From 0738033386dd23d03110197e4b4fdd1d5788fda6 Mon Sep 17 00:00:00 2001 From: vdancik Date: Wed, 4 Mar 2026 14:30:18 -0500 Subject: [PATCH 1/7] 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 2/7] 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 3/7] 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 4/7] 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 5/7] 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 6/7] 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 7/7] 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) -