diff --git a/ImplementationGuidance/Miscellaneous/examples_and_rules.md b/ImplementationGuidance/Miscellaneous/examples_and_rules.md index a333cf60..acbd7412 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. @@ -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. diff --git a/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md b/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md index aa823671..1d61a71e 100644 --- a/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md +++ b/ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md @@ -48,20 +48,17 @@ 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/). - { - "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. +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/). - { - "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. diff --git a/ImplementationGuidance/Specifications/query_specification.md b/ImplementationGuidance/Specifications/query_specification.md index cf8e3364..2a8fd81d 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 @@ -82,9 +90,9 @@ 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 -- 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 +## 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: ``` @@ -98,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": { @@ -129,38 +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: ``` - "attribute_constraints": [ - { - "id": "biolink:knowledge_source", - "name": "knowledge source", - "value": [ - "infores:rtx-kg2", - "infores:biothings-explorer", - ], - "operator": "==" + "constraints": { + "sources": { + "behavior": "ALLOW", + "values": [ + "infores:chembl", + "infores:chebi" + ] } - ], + }, ``` -(when the value is a list, the "==" operator works like a SQL "IN" clause, as clearly documented in the TRAPI yaml) - -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: ``` - "attribute_constraints": [ - { - "id": "biolink:knowledge_source", - "name": "knowledge source", - "value": [ - "infores:rtx-kg2", - "infores:biothings-explorer", - ], - "not": true, - "operator": "==" + "constraints": { + "sources": { + "behavior": "DENY", + "values": [ + "infores:ctd", + "infores:reactome" + ] } - ], + }, ``` -(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) -