Skip to content

update specification documentation #550

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vdancik wants to merge 7 commits into
base: 2.0
Choose a base branch
from
Open

update specification documentation #550

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0738033
update links to examples
vdancik Mar 4, 2026
4b5f693
update links to examples
vdancik Mar 4, 2026
301c69a
Update knowledge_level_agent_type_specification.md
vdancik Mar 4, 2026
2327d37
update knowledge_level_agent_type_specification.md
vdancik Mar 4, 2026
85e536c
add specification for QNode.set_interpretation
vdancik Mar 4, 2026
716a5fa
update examples of source constrains
vdancik Mar 4, 2026
be0673a
update source constrains examples
vdancik Mar 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions ImplementationGuidance/Miscellaneous/examples_and_rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"_

Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down
21 changes: 9 additions & 12 deletions ImplementationGuidance/Specifications/knowledge_level_agent_type_specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
78 changes: 38 additions & 40 deletions ImplementationGuidance/Specifications/query_specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:

```
Expand All @@ -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": {
Expand All @@ -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)