{ "$schema": "https://json-schema.org/draft-07/schema", "$id": "https://standards.ncats.io/operation/1.2.0/schema", "anyOf": [ { "$ref": "#/$defs/OperationAnnotate" }, { "$ref": "#/$defs/OperationAnnotateEdges" }, { "$ref": "#/$defs/OperationAnnotateNodes" }, { "$ref": "#/$defs/OperationBind" }, { "$ref": "#/$defs/OperationCompleteResults" }, { "$ref": "#/$defs/OperationEnrichResults" }, { "$ref": "#/$defs/OperationFill" }, { "$ref": "#/$defs/OperationFilterKgraph" }, { "$ref": "#/$defs/OperationFilterKgraphContinuousKedgeAttribute" }, { "$ref": "#/$defs/OperationFilterKgraphDiscreteKedgeAttribute" }, { "$ref": "#/$defs/OperationFilterKgraphDiscreteKnodeAttribute" }, { "$ref": "#/$defs/OperationFilterKgraphOrphans" }, { "$ref": "#/$defs/OperationFilterKgraphPercentile" }, { "$ref": "#/$defs/OperationFilterKgraphStdDev" }, { "$ref": "#/$defs/OperationFilterKgraphTopN" }, { "$ref": "#/$defs/OperationFilterResults" }, { "$ref": "#/$defs/OperationFilterResultsTopN" }, { "$ref": "#/$defs/OperationLookup" }, { "$ref": "#/$defs/OperationLookupAndScore" }, { "$ref": "#/$defs/OperationOverlay" }, { "$ref": "#/$defs/OperationOverlayComputeJaccard" }, { "$ref": "#/$defs/OperationOverlayComputeNgd" }, { "$ref": "#/$defs/OperationOverlayConnectKnodes" }, { "$ref": "#/$defs/OperationOverlayFisherExactTest" }, { "$ref": "#/$defs/OperationRestate" }, { "$ref": "#/$defs/OperationScore" }, { "$ref": "#/$defs/OperationSortResults" }, { "$ref": "#/$defs/OperationSortResultsEdgeAttribute" }, { "$ref": "#/$defs/OperationSortResultsNodeAttribute" }, { "$ref": "#/$defs/OperationSortResultsScore" } ], "$defs": { "OperationAnnotate": { "type": "object", "description": "This operation adds attributes to knowledge graph elements.", "properties": { "id": { "type": "string", "enum": [ "annotate" ] }, "unique": true, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationAnnotateEdges": { "type": "object", "description": "This operation adds attributes to knowledge graph edges.", "properties": { "id": { "type": "string", "enum": [ "annotate_edges" ] }, "unique": true, "parameters": { "type": "object", "properties": { "attributes": { "description": "A list of attributes to annotate the edges with. If not included then all available data will be annotated.", "type": "array", "items": { "type": "string" }, "example": [ "pmids" ] } } } }, "required": [ "id" ], "additionalProperties": false }, "OperationAnnotateNodes": { "type": "object", "description": "This operation adds attributes to knowledge graph nodes.", "properties": { "id": { "type": "string", "enum": [ "annotate_nodes" ] }, "unique": true, "parameters": { "type": "object", "properties": { "attributes": { "description": "A list of attributes to annotate the nodes with. If not included then all available data will be annotated.", "type": "array", "items": { "type": "string" }, "example": [ "pmids" ] } } } }, "required": [ "id" ], "additionalProperties": false }, "OperationBind": { "type": "object", "description": "This operation adds results binding kgraph elements to qgraph elements.", "properties": { "id": { "type": "string", "enum": [ "bind" ] }, "unique": false, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationCompleteResults": { "type": "object", "description": "This operation combines partial results into complete results.", "properties": { "id": { "type": "string", "enum": [ "complete_results" ] }, "unique": false, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationEnrichResults": { "type": "object", "description": "Create new results by applying enrichment analysis to existing results. In particular, combines results by transforming a qnode into a set, formed of knodes that share a property or relation more often than expected by chance.", "properties": { "id": { "type": "string", "enum": [ "enrich_results" ] }, "unique": true, "parameters": { "type": "object", "properties": { "pvalue_threshold": { "description": "The cutoff p-value for enrichment.", "type": "number", "example": "1e-7", "minimum": 0, "maximum": 1, "default": "1e-6" }, "qnode_keys": { "description": "If specified, then only knodes bound to these qnodes will be examined for enrichment and combination.", "type": "array", "items": { "type": "string" }, "example": [ "n01" ] } } } }, "required": [ "id" ], "additionalProperties": false }, "OperationFill": { "type": "object", "description": "This operation adds knodes and kedges.", "properties": { "id": { "type": "string", "enum": [ "fill" ] }, "unique": true, "parameters": { "type": "object", "oneOf": [ { "properties": { "allowlist": { "type": "array", "items": { "type": "string" }, "description": "List of knowledge providers/sources that may be used to provide knowledge.", "example": [ "icees" ], "minLength": 1 }, "qedge_keys": { "type": "array", "items": { "type": "string" }, "description": "A list of qedge keys. If included only edges corresponding to the given qedge keys, as well as their connected nodes, will be filled. If not included all edges will be filled.", "example": [ "e00" ] } }, "additionalProperties": false }, { "properties": { "denylist": { "type": "array", "items": { "type": "string" }, "description": "List of knowledge providers/sources that may NOT be used to provide knowledge.", "example": [ "ctd" ], "minLength": 1 }, "qedge_keys": { "type": "array", "items": { "type": "string" }, "description": "A list of qedge keys. If included only edges corresponding to the given qedge keys, as well as their connected nodes, will be filled. If not included all edges will be filled.", "example": [ "e00" ] } }, "additionalProperties": false } ] } }, "required": [ "id" ], "additionalProperties": false }, "OperationFilterKgraph": { "type": "object", "description": "This operation removes kgraph elements (nodes and/or edges).", "properties": { "id": { "type": "string", "enum": [ "filter_kgraph" ] }, "unique": false, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationFilterKgraphContinuousKedgeAttribute": { "type": "object", "description": "This operation removes kgraph edges based on the value of a continuous edge attribute. Edges without the given attribute are left alone.", "properties": { "id": { "type": "string", "enum": [ "filter_kgraph_continuous_kedge_attribute" ] }, "unique": false, "parameters": { "type": "object", "properties": { "edge_attribute": { "description": "The name of the edge attribute to filter on.", "type": "string", "example": "normalized_google_distance" }, "threshold": { "description": "The value to compare attribute values to.", "type": "number", "example": 1.2 }, "remove_above_or_below": { "description": "Indicates whether to remove above or below the given threshold.", "type": "string", "enum": [ "above", "below" ] }, "qedge_keys": { "description": "This indicates if you only want to remove edges with specific edge_keys. If not provided or empty, all edges will be filtered on.", "type": "array", "items": { "type": "string" }, "example": [ "e01" ] }, "qnode_keys": { "description": "This indicates if you only want nodes corresponding to a specific list of qnode_keys to be removed. If not provided or empty, no nodes will be removed when filtering. Allows us to know what to do with the nodes connected to edges that are removed.", "type": "array", "items": { "type": "string" }, "example": [ "n01" ], "default": [] } }, "required": [ "edge_attribute", "threshold", "remove_above_or_below" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationFilterKgraphDiscreteKedgeAttribute": { "type": "object", "description": "This operation removes kgraph edges which have a discrete attribute containing the specified value. Edges without the given attribute are left alone.", "properties": { "id": { "type": "string", "enum": [ "filter_kgraph_discrete_kedge_attribute" ] }, "unique": false, "parameters": { "type": "object", "properties": { "edge_attribute": { "description": "The name of the edge attribute to filter on.", "type": "string", "example": "provided_by" }, "remove_value": { "description": "The value for which all edges containing this value in the specified edge_attribute should be removed.", "example": "infores:semmeddb" }, "qedge_keys": { "description": "This indicates if you only want to remove edges with specific edge_keys. If not provided or empty, all edges will be filtered on.", "type": "array", "items": { "type": "string" }, "example": [ "e01" ] }, "qnode_keys": { "description": "This indicates if you only want nodes corresponding to a specific list of qnode_keys to be removed. If not provided or empty, no nodes will be removed when filtering. Allows us to know what to do with the nodes connected to edges that are removed", "type": "array", "items": { "type": "string" }, "example": [ "n01" ], "default": [] } }, "required": [ "edge_attribute", "remove_value" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationFilterKgraphDiscreteKnodeAttribute": { "type": "object", "description": "This operation removes kgraph nodes which have a discrete attribute containing the specified value. In TRAPI 1.1+ this will look in the `attribute_type_id` and `original_attribute_name` attribute fields for the attribute name. Node without the given attribute are left alone. Edges connecting to the removed nodes will also be removed.", "properties": { "id": { "type": "string", "enum": [ "filter_kgraph_discrete_knode_attribute" ] }, "unique": false, "parameters": { "type": "object", "properties": { "node_attribute": { "description": "The name of the node attribute to filter on.", "type": "string", "example": "molecule_type" }, "remove_value": { "description": "The value for which all edges containing this value in the specified edge_attribute should be removed.", "example": "small_molecule" }, "qnode_keys": { "description": "This indicates if you only want to remove nodes corresponding to a specific list of qnode_keys to be removed. If not provided or empty, all nodes will be considered when filtering.", "type": "array", "items": { "type": "string" }, "example": [ "n01" ] } }, "required": [ "node_attribute", "remove_value" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationFilterKgraphOrphans": { "type": "object", "description": "This operation removes kgraph elements that are not referenced by any results.", "properties": { "id": { "type": "string", "enum": [ "filter_kgraph_orphans" ] }, "unique": false, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationFilterKgraphPercentile": { "type": "object", "description": "This operation removes kgraph edges that have attribute values are below/above the given percentile.", "properties": { "id": { "type": "string", "enum": [ "filter_kgraph_percentile" ] }, "unique": false, "parameters": { "type": "object", "properties": { "edge_attribute": { "description": "The name of the edge attribute to filter on.", "type": "string", "example": "normalized_google_distance" }, "threshold": { "description": "The percentile to threshold on.", "type": "number", "example": 96.8, "minimum": 0, "maximum": 100, "default": 95 }, "remove_above_or_below": { "description": "Indicates whether to remove above or below the given threshold.", "type": "string", "enum": [ "above", "below" ], "default": "below" }, "qedge_keys": { "description": "This indicates if you only want to filter on specific edge_keys. If not provided or empty, all edges will be filtered on.", "type": "array", "items": { "type": "string" }, "example": [ "e01" ] }, "qnode_keys": { "description": "This indicates if you only want nodes corresponding to a specific list of qnode_keys to be removed. If not provided or empty, no nodes will be removed when filtering. Allows us to know what to do with the nodes connected to edges that are removed.", "type": "array", "items": { "type": "string" }, "example": [ "n01" ], "default": [] } }, "required": [ "edge_attribute" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationFilterKgraphStdDev": { "type": "object", "description": "This operation removes kgraph edges that have attribute values are below/above the mean +/- n standard deviations.", "properties": { "id": { "type": "string", "enum": [ "filter_kgraph_std_dev" ] }, "unique": false, "parameters": { "type": "object", "properties": { "edge_attribute": { "description": "The name of the edge attribute to filter on.", "type": "string", "example": "normalized_google_distance" }, "num_sigma": { "description": "The number of standard deviations to threshold on.", "type": "number", "example": 1.2, "minimum": 0, "default": 1 }, "remove_above_or_below": { "description": "Indictes whether to remove above or below the given threshold.", "type": "string", "enum": [ "above", "below" ], "default": "below" }, "plus_or_minus_std_dev": { "description": "Indicate whether or not the threshold should be found using plus or minus the standard deviation. E.g. when plus_or_minus_std_dev is set to plus will set the cutoff for filtering as the mean + num_sigma * std_dev while setting plus_or_minus_std_dev to minus will set the cutoff as the mean - num_sigma * std_dev.", "type": "string", "enum": [ "plus", "minus" ], "default": "plus" }, "qedge_keys": { "description": "This indicates if you only want to filter on specific edge_keys. If not provided or empty, all edges will be filtered on.", "type": "array", "items": { "type": "string" }, "example": [ "e01" ] }, "qnode_keys": { "description": "This indicates if you only want nodes corresponding to a specific list of qnode_keys to be removed. If not provided or empty, no nodes will be removed when filtering.", "type": "array", "items": { "type": "string" }, "example": [ "n01" ], "default": [] } }, "required": [ "edge_attribute" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationFilterKgraphTopN": { "type": "object", "description": "This operation removes kgraph edges that have attribute values are below/above the top/bottom n values.", "properties": { "id": { "type": "string", "enum": [ "filter_kgraph_top_n" ] }, "unique": false, "parameters": { "type": "object", "properties": { "edge_attribute": { "description": "The name of the edge attribute to filter on.", "type": "string", "example": "normalized_google_distance" }, "max_edges": { "description": "The number of edges to keep.", "type": "integer", "example": 10, "minimum": 0, "default": 50 }, "keep_top_or_bottom": { "description": "Indicate whether or not the the top or bottom n values should be kept.", "type": "string", "enum": [ "top", "bottom" ], "default": "top" }, "qedge_keys": { "description": "This indicates if you only want to filter on specific edge_keys. If not provided or empty, all edges will be filtered on.", "type": "array", "items": { "type": "string" }, "example": [ "e01" ] }, "qnode_keys": { "description": "This indicates if you only want nodes corresponding to a specific list of qnode_keys to be removed. If not provided or empty, no nodes will be removed when filtering. Allows us to know what to do with the nodes connected to edges that are removed.", "type": "array", "items": { "type": "string" }, "example": [ "n01" ], "default": [] } }, "required": [ "edge_attribute" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationFilterResults": { "type": "object", "description": "This operation allows the TRAPI server to remove elements from the list of results.", "properties": { "id": { "type": "string", "enum": [ "filter_results" ] }, "unique": false, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationFilterResultsTopN": { "type": "object", "description": "This operation truncates the results to at most `max_results` that appear in the TRAPI JSON message.", "properties": { "id": { "type": "string", "enum": [ "filter_results_top_n" ] }, "unique": false, "parameters": { "type": "object", "properties": { "max_results": { "description": "The maximum number of results to return.", "type": "integer", "minimum": 0, "example": 50 } }, "required": [ "max_results" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationLookup": { "type": "object", "description": "This operation adds knodes/kedges and (complete) results. It is equivalent to the workflow fill + bind + complete_results.", "properties": { "id": { "type": "string", "enum": [ "lookup" ] }, "unique": true, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationLookupAndScore": { "type": "object", "description": "This operation adds knodes/kedges, (complete) results, and scores (to the results). It is equivalent to the workflow fill + bind + complete_results + score.", "properties": { "id": { "type": "string", "enum": [ "lookup_and_score" ] }, "unique": true, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationOverlay": { "type": "object", "description": "This operation adds additional qedges and/or kedges and/or result edge bindings.", "properties": { "id": { "type": "string", "enum": [ "overlay" ] }, "unique": false, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationOverlayComputeJaccard": { "type": "object", "description": "This operation computes the Jaccard Similarity which measures how many intermediate_node_key nodes are directly connected to both the end_node_keys nodes for all pairs of nodes with corresponding keys. It will then add edges to the knowledge graph along with edge attributes (with the property name jaccard_index) between each start_node_key and object_node_key. A query graph edge will also be added using the key specified by virtual_relation_label. This is used for purposes such as \"find me all drugs (start_node_key) that have many proteins (intermediate_node_key) in common with this disease (end_node_key).\" This can be used for downstream filtering to concentrate on relevant bioentities.", "properties": { "id": { "type": "string", "enum": [ "overlay_compute_jaccard" ] }, "unique": false, "parameters": { "type": "object", "properties": { "intermediate_node_key": { "description": "A qnode key specifying the intermediate node.", "type": "string", "example": "n1" }, "end_node_keys": { "description": "A list of qnode keys specifying the ending nodes.", "type": "array", "items": { "type": "string" }, "example": [ "n0", "n2" ] }, "virtual_relation_label": { "description": "The key of the query graph edge that corresponds to the knowledge graph edges that were added by this operation.", "type": "string", "example": "J1" } }, "required": [ "intermediate_node_key", "end_node_keys", "virtual_relation_label" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationOverlayComputeNgd": { "type": "object", "description": "This operation computes the normalized Google distance (co-occurrence frequency) in PubMed abstracts and adds virual edges between qnodes AND/OR knodes AND/OR results edge bindings. If no publications are found infinity is returned.", "properties": { "id": { "type": "string", "enum": [ "overlay_compute_ngd" ] }, "unique": false, "parameters": { "type": "object", "properties": { "virtual_relation_label": { "description": "An label to help identify the virtual edge in the relation field", "type": "string", "example": "NGD1" }, "qnode_keys": { "description": "A list of qnode keys to overlay pairwise edges onto. Must be be a list of at least 2 valid qnodes.", "type": "array", "items": { "type": "string" }, "example": [ "n00", "n01" ] } }, "required": [ "virtual_relation_label", "qnode_keys" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationOverlayConnectKnodes": { "type": "object", "description": "Given a TRAPI message, create new kedges between existing knodes. These may be created using arbitrary methods or data sources, though provenance should be attached to the new kedges. Each new kedge is also added to all results containing node bindings to both the subject and object knodes. This may be independent of any qedge connections, i.e. kedges can be created between any nodes in the kgraph.", "properties": { "id": { "type": "string", "enum": [ "overlay_connect_knodes" ] }, "unique": false, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationOverlayFisherExactTest": { "type": "object", "description": "Fisher exact test computes the Fisher's Exact Test p-values of the connection between a list of given nodes with specified query id (subject_qnode_key e.g. n01) to their adjacent nodes with specified query id (object_qnode_key e.g. n02) in the message knowledge graph. This information is then added as an edge attribute to a virtual edge which is then added to the query graph and knowledge graph. It can also allow you to filter out the user-defined insignificance of connections based on a specified p-value cutoff or return the top n smallest p-value of connections and only add their corresponding virtual edges to the knowledge graph.", "properties": { "id": { "type": "string", "enum": [ "overlay_fisher_exact_test" ] }, "unique": false, "parameters": { "type": "object", "properties": { "subject_qnode_key": { "description": "A specific subject query node id.", "type": "string", "example": "n1" }, "object_qnode_key": { "description": "A specific object query node id.", "type": "string", "example": "n2" }, "virtual_relation_label": { "description": "An label to help identify the virtual edge.", "type": "string", "example": "f1" }, "rel_edge_key": { "description": "A specific Qedge id connected to both subject nodes and object nodes in message KG (optional, otherwise all edges connected to both subject nodes and object nodes in message KG are considered).", "type": "string", "example": "e01" } }, "required": [ "subject_qnode_key", "object_qnode_key", "virtual_relation_label" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationRestate": { "type": "object", "description": "This operation modifies the query graph.", "properties": { "id": { "type": "string", "enum": [ "restate" ] }, "unique": true, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationScore": { "type": "object", "description": "This operation adds scores to results.", "properties": { "id": { "type": "string", "enum": [ "score" ] }, "unique": true, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationSortResults": { "type": "object", "description": "This operation allows the TRAPI server to sort the elements of the list of results.", "properties": { "id": { "type": "string", "enum": [ "sort_results" ] }, "unique": false, "parameters": {} }, "required": [ "id" ], "additionalProperties": false }, "OperationSortResultsEdgeAttribute": { "type": "object", "description": "This operation sorts the results by the given edge attribute. If in ascending order, the minimum value of the results edges with the given attribute will be taken while the maximum will be taken for descending order. If a result has no edges with the given attribute, it will be listed last. If `max_results` is given, it truncates the results to at most the given value.", "properties": { "id": { "type": "string", "enum": [ "sort_results_edge_attribute" ] }, "unique": false, "parameters": { "type": "object", "properties": { "edge_attribute": { "description": "The name of the edge attribute to order by.", "type": "string", "example": "normalized_google_distance" }, "ascending_or_descending": { "description": "Indicates whether results should be sorted in ascending or descending order.", "type": "string", "enum": [ "ascending", "descending" ] }, "qedge_keys": { "description": "This indicates if you only want to consider edges with specific edge_keys. If not provided or empty, all edges will be looked at.", "type": "array", "items": { "type": "string" }, "example": [ "e01" ] } }, "required": [ "edge_attribute", "ascending_or_descending" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationSortResultsNodeAttribute": { "type": "object", "description": "This operation sorts the results by the given node attribute. If in ascending order, the minimum value of the results nodes with the given attribute will be taken while the maximum will be taken for descending order. If a result has no nodes with the given attribute, it will be listed last. If `max_results` is given, it truncates the results to at most the given value.", "properties": { "id": { "type": "string", "enum": [ "sort_results_node_attribute" ] }, "unique": false, "parameters": { "type": "object", "properties": { "node_attribute": { "description": "The name of the node attribute to order by.", "type": "string", "example": "normalized_google_distance" }, "ascending_or_descending": { "description": "Indicates whether results should be sorted in ascending or descending order.", "type": "string", "enum": [ "ascending", "descending" ] }, "qnode_keys": { "description": "This indicates if you only want to consider nodes with specific node_keys. If not provided or empty, all nodes will be looked at.", "type": "array", "items": { "type": "string" }, "example": [ "e01" ] } }, "required": [ "node_attribute", "ascending_or_descending" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false }, "OperationSortResultsScore": { "type": "object", "description": "This operation sorts the results by the result score. If `max_results` is given, it truncates the results to at most the given value.", "properties": { "id": { "type": "string", "enum": [ "sort_results_score" ] }, "unique": false, "parameters": { "type": "object", "properties": { "ascending_or_descending": { "description": "Indicates whether results should be sorted in ascending or descending order.", "type": "string", "enum": [ "ascending", "descending" ] } }, "required": [ "ascending_or_descending" ] } }, "required": [ "id", "parameters" ], "additionalProperties": false } } }