From 16dee366f5caac78625644a967887d12c7d08acf Mon Sep 17 00:00:00 2001 From: Colleen Xu Date: Wed, 17 Aug 2022 15:37:53 -0700 Subject: [PATCH] revert main-yamls to trapi1.2 and make new yamls for trapi1.3 --- .../service-provider-trapi.yaml | 359 ++-- .../service-provider-trapi_temp13.yaml | 1285 ++++++++++++ biothings_explorer/smartapi.yaml | 490 ++--- biothings_explorer/smartapi_temp13.yaml | 1777 +++++++++++++++++ 4 files changed, 3335 insertions(+), 576 deletions(-) create mode 100644 biothings_explorer/service-provider-trapi_temp13.yaml create mode 100644 biothings_explorer/smartapi_temp13.yaml diff --git a/biothings_explorer/service-provider-trapi.yaml b/biothings_explorer/service-provider-trapi.yaml index 74d42708..ce4b2c4e 100644 --- a/biothings_explorer/service-provider-trapi.yaml +++ b/biothings_explorer/service-provider-trapi.yaml @@ -9,19 +9,18 @@ info: x-role: responsible developer description: >- Separate registration for the BTE's Service-Provider-specific endpoints. This allows others - use BTE as a TRAPI service/interface to query all of the non-TRAPI APIs that Service Provider ingests - through x-bte annotation. + to query all of the non-TRAPI APIs that Service Provider ingests through x-bte annotation - + through a TRAPI setup. termsOfService: https://biothings.io/about - title: Service Provider TRAPI + title: Service Provider TRAPI (v1.2) version: 2.8.1 x-trapi: - version: 1.3.0 + version: 1.2.0 ## will update to 1.3 once all instances have trapi1.3 code asyncquery: true operations: ## look at https://standards.ncats.io/operation.json for details. was previously lookup - lookup_and_score ## no batch_size_limit (BTE manages IDs for QNodes and sub-queries internally) - rate_limit: 15 ## /query endpoints have a limit of 15 requests/client/min ## /meta_knowledge_graph endpoints have a limit of 30 requests/client/min ## other endpoints don't have rate limits @@ -41,11 +40,8 @@ servers: - url: https://bte.ci.transltr.io/v1/team/Service%20Provider description: ITRB CI server x-maturity: staging -- url: https://api.bte.ncats.io/v1/team/Service%20Provider - description: Non-ITRB dev (primary internal use) - x-maturity: development tags: -- name: 1.3.0 +- name: 1.2.0 ## will update to 1.3 once all instances have trapi1.3 code - name: meta_knowledge_graph - name: query - name: asyncquery @@ -56,26 +52,29 @@ tags: ## instead go through it and copy-paste in sections as-needed ## examples are using MyVariant-specific query paths: - ## copied from BTE's /meta_knowledge_graph and modified summary/description + ## copied directly from TRAPI spec /meta_knowledge_graph: get: tags: - meta_knowledge_graph - summary: TRAPI-compliant meta-knowledge-graph representation for Service Provider's SmartAPI KP APIs (that have x-bte annotation) + summary: TRAPI-compliant Meta knowledge graph representation for Service Provider's SmartAPI KP APIs (that have x-bte annotation) + description: Returns a TRAPI-compliant meta knowledge graph representation of Service Provider's SmartAPI KP APIs (that have x-bte annotation) responses: '200': - description: >- - Returns a TRAPI-compliant meta-knowledge-graph representation for Service Provider's SmartAPI KP APIs (that have x-bte annotation) + description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MetaKnowledgeGraph' - ## copied from BTE's /query and modified summary + ## modified TRAPI spec: example and BTE-specific parameters, used by developers running local instances of BTE /query: post: tags: - query - summary: Query Service Provider's SMARTAPI KP APIs (that have x-bte annotation) as an individual TRAPI service + summary: >- + Query Service Provider's SMARTAPI KP APIs (that have x-bte annotation) as an individual TRAPI + service + description: '' parameters: - description: option to choose whether or not to enable caching in: query @@ -94,8 +93,6 @@ paths: required: true content: application/json: - schema: - $ref: '#/components/schemas/Query' ## should use MyVariant to answer this example: message: @@ -113,6 +110,8 @@ paths: e1: subject: "n0" object: "n1" + schema: + $ref: '#/components/schemas/Query' responses: '200': description: >- @@ -131,22 +130,6 @@ paths: application/json: schema: type: string - '413': - description: >- - Payload too large. Indicates that batch size was over the limit - specified in x-trapi. - content: - application/json: - schema: - type: string - '429': - description: >- - Too many requests. Indicates that the client issued requests that - exceed the rate limit specified in x-trapi. - content: - application/json: - schema: - type: string '500': description: >- Internal server error. @@ -182,6 +165,7 @@ paths: # endpoint without a callback property: BTE then handled it in a polling manner and # provided a job id. The job id can be used here to check the status or retrieve # the Response. + # description: '' # parameters: # - description: option to override original query log level # in: query @@ -189,9 +173,7 @@ paths: # required: false # schema: # type: string - # description: >- - # Logging level. The order of priority is ERROR, WARNING, INFO, DEBUG. BTE will return all logs at the - # specified level and those at higher priority levels + # description: Logging level # enum: # - ERROR # - WARNING @@ -199,7 +181,7 @@ paths: # - DEBUG # responses: # '200': - # description: Returns status. If successfully completed, it will return a TRAPI Response object under the field returnvalue + # description: Returns status. If successfully completed, it will return a TRAPI Response object # content: # application/json: # schema: @@ -225,21 +207,24 @@ paths: # properties: # response: # $ref: '#/components/schemas/Response' - ## copied from BTE's /asyncquery and modified summary + ## modified TRAPI spec: summary sections tell users that AsyncQuery schema was changed to make callback optional /asyncquery: post: tags: - asyncquery summary: >- - This endpoint is for asynchronously querying Service Provider's SMARTAPI KP APIs (that have x-bte annotation) - as an individual TRAPI service. + This endpoint is for querying Service Provider's SMARTAPI KP APIs + (that have x-bte annotation) through a TRAPI API interface (BTE). Initiate a query that will be handled in an asynchronous manner (there is a queue and queries will be executed in the order that they enter the queue). For BTE, it is optional to have a callback property in the request-body. If the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve - the Response using BTE's /v1/check_query_status/{id} endpoint. + the Response using the /v1/check_query_status/{id} endpoint. + + Note that there's no "team/Service Provider/" in the check_query_status endpoint. + description: '' parameters: - description: option to choose whether or not to enable caching in: query @@ -258,8 +243,6 @@ paths: required: true content: application/json: - schema: - $ref: '#/components/schemas/AsyncQuery' ## should use MyVariant to answer this example: message: @@ -277,6 +260,8 @@ paths: e1: subject: "n0" object: "n1" + schema: + $ref: '#/components/schemas/AsyncQuery' responses: '200': description: >- @@ -285,7 +270,7 @@ paths: the Response will be sent to the callback url when complete. If the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve - the Response using BTE's /v1/check_query_status/{id} endpoint. + the Response using the /v1/check_query_status/{id} endpoint. content: application/json: schema: @@ -299,22 +284,6 @@ paths: application/json: schema: type: string - '413': - description: >- - Payload too large. Indicates that batch size was over the limit - specified in x-trapi. - content: - application/json: - schema: - type: string - '429': - description: >- - Too many requests. Indicates that the client issued requests that - exceed the rate limit specified in x-trapi. - content: - application/json: - schema: - type: string '500': description: >- Internal server error. @@ -336,9 +305,7 @@ components: ## - AsyncQuery: callback property not required (commented it out of the 'required' field), ## comment out workflow.allOf section ## - Response: comment out workflow.allOf section - ## - QEdge: set additionalProperties to false (see comments below for details) - ## - Attribute: comment out properties.attributes.items since the self-$ref breaks execution of - ## BTE's api-schema-builder/openapi-validator-middleware + ## - QNode: commented out an example for some reason schemas: Query: description: >- @@ -370,13 +337,6 @@ components: # allOf: # - $ref: http://standards.ncats.io/workflow/1.0.0/schema nullable: true - submitter: - type: string - description: >- - Any string for self-identifying the submitter of a query. The - purpose of this optional field is to aid in the tracking of - the source of queries for development and issue resolution. - nullable: true additionalProperties: true required: - message @@ -418,17 +378,10 @@ components: # allOf: # - $ref: http://standards.ncats.io/workflow/1.0.0/schema nullable: true - submitter: - type: string - description: >- - Any string for self-identifying the submitter of a query. The - purpose of this optional field is to aid in the tracking of - the source of queries for development and issue resolution. - nullable: true additionalProperties: true - required: ## BTE does not require the callback property, see the asyncquery ## endpoint summary and 200 response description + required: # - callback - message Response: @@ -601,39 +554,15 @@ components: - edge_bindings NodeBinding: type: object - description: >- - An instance of NodeBinding is a single KnowledgeGraph Node mapping, - identified by the corresponding 'id' object key identifier of the - Node within the Knowledge Graph. Instances of NodeBinding may - include extra annotation in the form of additional properties. - (such annotation is not yet fully standardized). properties: id: $ref: '#/components/schemas/CURIE' description: >- - The CURIE of a Node within the Knowledge Graph. - query_id: - $ref: '#/components/schemas/CURIE' - description: >- - An optional property to provide the CURIE in the QueryGraph to - which this binding applies. If the bound QNode does not have an - an 'id' property or if it is empty, then this query_id MUST be - null or absent. If the bound QNode has one or more CURIEs - as an 'id' and this NodeBinding's 'id' refers to a QNode 'id' - in a manner where the CURIEs are different (typically due to - the NodeBinding.id being a descendant of a QNode.id), then - this query_id MUST be provided. In other cases, there is no - ambiguity, and this query_id SHOULD NOT be provided. - attributes: - type: array - description: >- - A list of attributes providing further information about the - node binding. This is not intended for capturing node attributes - and should only be used for properties that vary from result to - result. - items: - $ref: '#/components/schemas/Attribute' - nullable: true + An instance of NodeBinding is a single KnowledgeGraph Node mapping, + identified by the corresponding 'id' object key identifier of the + Node within the Knowledge Graph. Instances of NodeBinding may + include extra annotation (such annotation is not yet fully + standardized). additionalProperties: true required: - id @@ -728,7 +657,8 @@ components: items: $ref: '#/components/schemas/CURIE' minItems: 1 - example: [OMIM:603903] + ## commenting it out since smartapi editor doesn't handle this well + # example: [OMIM:603903] description: CURIE identifier for this node nullable: true categories: @@ -758,7 +688,7 @@ components: If there are multiple items, they must all be true (equivalent to AND) items: - $ref: '#/components/schemas/AttributeConstraint' + $ref: '#/components/schemas/QueryConstraint' default: [] additionalProperties: true QEdge: @@ -772,20 +702,6 @@ components: an exact match to the given QEdge predicate term, or to a term that is a descendant of the QEdge predicate term. properties: - knowledge_type: - description: >- - Indicates the type of knowledge that the client wants from the - server between the subject and object. If the value is - 'lookup', then the client wants direct lookup information from - knowledge sources. If the value is 'inferred', then the client - wants the server to get creative and connect the subject and - object in more speculative and non-direct-lookup ways. If this - property is absent or null, it MUST be assumed to mean - 'lookup'. This feature is currently experimental and may be - further extended in the future. - example: lookup - nullable: true - type: string predicates: type: array items: @@ -806,32 +722,16 @@ components: Corresponds to the map key identifier of the object concept node anchoring the query filter pattern for the query relationship edge. - attribute_constraints: + constraints: type: array description: >- - A list of attribute contraints applied to a query edge. + A list of contraints applied to a query edge. If there are multiple items, they must all be true (equivalent to AND) items: - $ref: '#/components/schemas/AttributeConstraint' + $ref: '#/components/schemas/QueryConstraint' default: [] - qualifier_constraints: - type: array - description: >- - A list of QualifierConstraints that provide nuance to the QEdge. - If multiple QualifierConstraints 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 qualifier_constraints MUST NOT be specified - because these complex use cases are not supported at this time. - items: - $ref: '#/components/schemas/QualifierConstraint' - default: [] - ## changing from true to false, so BTE will reject queries that have these additional properties - ## BTE doesn't use these and this is the easiest way to recognize when they are there and respond to that - ## Related to Implementation rules https://github.com/NCATSTranslator/ReasonerAPI/blob/1.3/ImplementationRules.md#qedgexxxxx - additionalProperties: false + additionalProperties: true required: - subject - object @@ -867,7 +767,7 @@ components: 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 + about it. An attribute may be further qualified with a SubAttribute (for example to provide confidence intervals on a value). properties: attribute_type_id: @@ -881,7 +781,7 @@ components: '0.000153' represents a p-value supporting an edge, or that a value of 'ChEMBL' represents the original source of the knowledge expressed in the edge. - example: biolink:synonym + example: Biolink:has_p-value_evidence, Biolink:has_original_source original_attribute_name: type: string description: >- @@ -938,8 +838,80 @@ components: A list of attributes providing further information about the parent attribute (for example to provide provenance information about the parent attribute). - # items: - # $ref: '#/components/schemas/Attribute' + items: + $ref: '#/components/schemas/SubAttribute' + nullable: true + required: + - attribute_type_id + - value + additionalProperties: false + SubAttribute: + type: object + description: >- + Second-level attribute that can be used to qualify information + contained in a primary Attribute attached to a Node or Edge. + properties: + attribute_type_id: + $ref: '#/components/schemas/CURIE' + description: >- + The 'key' of the attribute object, holding a CURIE of an ontology + property defining the attribute (preferably the CURIE of a + Biolink association slot). This property captures the relationship + asserted to hold between the value of the attribute, and the node + or edge from which it hangs. For example, that a value of + '0.000153' represents a p-value supporting an edge, or that + a value of 'ChEMBL' represents the original source of the knowledge + expressed in the edge. + example: Biolink:has_p-value_evidence, Biolink:has_original_source + original_attribute_name: + type: string + description: >- + The term used by the original source of an attribute to describe + the meaning or significance of the value it captures. This may be + a column name in a source tsv file, or a key in a source json + document for the field in the data that held the attribute's + value. Capturing this information where possible lets us preserve + what the original source said. Note that the data type is string' + but the contents of the field could also be a CURIE of a third + party ontology term. + example: p-value + nullable: true + value: + description: >- + Value of the attribute. May be any data type, including a list. + example: 0.000153 + value_type_id: + allOf: + - $ref: '#/components/schemas/CURIE' + description: >- + CURIE describing the semantic type of an attribute's value. Use + a Biolink class if possible, otherwise a term from an external + ontology. If a suitable CURIE/identifier does not exist, enter a + descriptive phrase here and submit the new type for consideration + by the appropriate authority. + example: EDAM:data_1187 + nullable: true + attribute_source: + type: string + description: >- + The source of the core assertion made by the key-value pair of an + attribute object. Use a CURIE or namespace designator for this + resource where possible. + example: UniProtKB + nullable: true + value_url: + type: string + description: >- + Human-consumable URL linking to a web document that provides + additional information about an attribute's value (not the node + or the edge fom which it hangs). + example: https://pubmed.ncbi.nlm.nih.gov/32529952 + nullable: true + description: + type: string + description: >- + Human-readable description for the attribute and its value. + example: Assertion Authored By Dr. Trans L. Ator nullable: true required: - attribute_type_id @@ -974,67 +946,10 @@ components: items: $ref: '#/components/schemas/Attribute' nullable: true - qualifiers: - type: array - description: >- - A set of Qualifiers that act together to add nuance - or detail to the statement expressed in an Edge. - items: - $ref: '#/components/schemas/Qualifier' - nullable: true additionalProperties: false required: - subject - object - Qualifier: - additionalProperties: false - description: >- - An additional nuance attached to an assertion - type: object - properties: - qualifier_type_id: - type: string - description: >- - The category of the qualifier, drawn from a hierarchy of qualifier - slots in the Biolink model (e.g. subject_aspect, subject_direction, - object_aspect, object_direction, etc). - example: subject_aspect - nullable: false - qualifier_value: - type: string - description: >- - 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 'subject_aspect', etc). - example: expression - nullable: false - required: - - qualifier_type_id - - qualifier_value - QualifierConstraint: - additionalProperties: false - description: >- - Defines a query constraint based on the - qualifier_types and qualifier_values of a set of - Qualifiers attached to an edge. For example, it 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 "object_aspect" with - a qualifier_value of "expression". - properties: - qualifier_set: - type: array - description: >- - A set of Qualifiers that serves to add nuance to a query, - by constraining allowed values held by Qualifiers - on queried Edges. - items: - $ref: '#/components/schemas/Qualifier' - nullable: false - required: - - qualifier_set - type: object BiolinkEntity: description: >- Compact URI (CURIE) for a Biolink class, biolink:NamedThing @@ -1129,7 +1044,7 @@ components: $ref: '#/components/schemas/BiolinkEntity' description: >- Subject node category of this relationship edge. - example: biolink:ChemicalEntity + example: biolink:ChemicalSubstance predicate: $ref: '#/components/schemas/BiolinkPredicate' description: >- @@ -1140,16 +1055,6 @@ components: description: >- Object node category of this relationship edge. example: biolink:Protein - knowledge_types: - description: >- - A list of knowledge_types that are supported by the service. - If the knowledge_types is null, this means that only 'lookup' - is supported. Currently allowed values are 'lookup' or 'inferred'. - items: - type: string - minItems: 1 - nullable: true - type: array attributes: type: array description: >- @@ -1200,7 +1105,7 @@ components: nullable: true required: - attribute_type_id - AttributeConstraint: + QueryConstraint: type: object description: >- Generic query constraint for a query node or query edge @@ -1232,39 +1137,27 @@ components: description: >- Relationship between the database value and the constraint value for the specified id. The operators ==, >, and < mean - is equal to, is greater than, and is less than, + is exactly equal to, is greater than, and is less than, respectively. The 'matches' operator indicates that the value is a regular expression to be evaluated. If value is a list type, then at least one evaluation must be true (equivalent to OR). This means that the == operator with a list acts like a SQL 'IN' - clause. If the value of the compared attribute is a list, then - comparisons are performed between each of the constraint values - and each of the attribute values, and any one true evaluation - counts as an overall true (e.g., [1,2,3] == [6,7,2] is true). - The == operator is therefore a broad interpretation of inclusion. - The '===' operator requires that the constraint value and - the attribute value be the same data type, length, - content, and order (e.g. only [1,2,3] === [1,2,3]). - The 'not' property negates the operator such that not + clause. The 'not' property negates the operator such that not and == means 'not equal to' (or 'not in' for a list), and not > - means <=, and not < means >=, not matches means does not - match, and not === means the match between the constraint - and attribute values are not exact. - The '==' operator SHOULD NOT be used in a manner that + means <=, and not < means >=, and not matches means does not + match. The '==' operator SHOULD NOT be used in a manner that describes an "is a" subclass relationship for the parent QNode. enum: - == - '>' - < - matches - - === value: example: 57.0 description: >- Value of the attribute. May be any data type, including a list. If the value is a list and there are multiple items, at least one - comparison must be true (equivalent to OR) unless the '===' - operator is used. If 'value' is of data + comparison must be true (equivalent to OR). If 'value' is of data type 'object', the keys of the object MAY be treated as a list. A 'list' data type paired with the '>' or '<' operators will encode extraneous comparisons, but this is permitted as it is in diff --git a/biothings_explorer/service-provider-trapi_temp13.yaml b/biothings_explorer/service-provider-trapi_temp13.yaml new file mode 100644 index 00000000..15855438 --- /dev/null +++ b/biothings_explorer/service-provider-trapi_temp13.yaml @@ -0,0 +1,1285 @@ +openapi: 3.0.3 +## made this document by copying https://github.com/NCATS-Tangerine/translator-api-registry/blob/master/biothings_explorer/smartapi.yaml +## section-by-section and adjusting when needed +info: + contact: + email: cwu@scripps.edu + name: Chunlei Wu + x-id: https://github.com/newgene + x-role: responsible developer + description: >- + Separate registration for the BTE's Service-Provider-specific endpoints. This allows others + use BTE as a TRAPI service/interface to query all of the non-TRAPI APIs that Service Provider ingests + through x-bte annotation. + termsOfService: https://biothings.io/about + title: Service Provider TRAPI (v1.3) + version: 2.8.1 + x-trapi: + version: 1.3.0 + asyncquery: true + operations: + ## look at https://standards.ncats.io/operation.json for details. was previously lookup + - lookup_and_score + ## no batch_size_limit (BTE manages IDs for QNodes and sub-queries internally) + rate_limit: 15 + ## /query endpoints have a limit of 15 requests/client/min + ## /meta_knowledge_graph endpoints have a limit of 30 requests/client/min + ## other endpoints don't have rate limits + x-translator: + infores: "infores:service-provider-trapi" + biolink-version: 2.4.8 + component: KP + team: + - Service Provider +servers: +- url: https://api.bte.ncats.io/v1/team/Service%20Provider + description: Non-ITRB dev (primary internal use) + x-maturity: development +tags: +- name: 1.3.0 +- name: meta_knowledge_graph +- name: query +- name: asyncquery +- name: translator +- name: trapi +- name: biothings +## Note: BTE has custom behavior so DO NOT blindly copy-paste the TRAPI specs / schemas into the document below +## instead go through it and copy-paste in sections as-needed +## examples are using MyVariant-specific query +paths: + ## copied from BTE's /meta_knowledge_graph and modified summary/description + /meta_knowledge_graph: + get: + tags: + - meta_knowledge_graph + summary: TRAPI-compliant meta-knowledge-graph representation for Service Provider's SmartAPI KP APIs (that have x-bte annotation) + responses: + '200': + description: >- + Returns a TRAPI-compliant meta-knowledge-graph representation for Service Provider's SmartAPI KP APIs (that have x-bte annotation) + content: + application/json: + schema: + $ref: '#/components/schemas/MetaKnowledgeGraph' + ## copied from BTE's /query and modified summary + /query: + post: + tags: + - query + summary: Query Service Provider's SMARTAPI KP APIs (that have x-bte annotation) as an individual TRAPI service + parameters: + - description: option to choose whether or not to enable caching + in: query + name: caching + required: false + schema: + type: boolean + - description: dryrun a query (logs the queries BTE will make) + in: query + name: dryrun + required: false + schema: + type: boolean + requestBody: + description: Query information to be submitted + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + ## should use MyVariant to answer this + example: + message: + query_graph: + nodes: + n0: + ids: + - "DBSNP:rs121913521" + categories: + - "biolink:SequenceVariant" + n1: + categories: + - "biolink:Disease" + edges: + e1: + subject: "n0" + object: "n1" + responses: + '200': + description: >- + OK. There may or may not be results. Note that some of the provided + identifiers may not have been recognized. + content: + application/json: + schema: + $ref: '#/components/schemas/Response' + '400': + description: >- + Bad request. The request is invalid according to this OpenAPI + schema OR a specific identifier is believed to be invalid somehow + (not just unrecognized). + content: + application/json: + schema: + type: string + '413': + description: >- + Payload too large. Indicates that batch size was over the limit + specified in x-trapi. + content: + application/json: + schema: + type: string + '429': + description: >- + Too many requests. Indicates that the client issued requests that + exceed the rate limit specified in x-trapi. + content: + application/json: + schema: + type: string + '500': + description: >- + Internal server error. + content: + application/json: + schema: + type: string + '501': + description: >- + Not implemented. + content: + application/json: + schema: + type: string + ## need to remove the extra stuff from server url to use this endpoint.. + ## example: https://api.bte.ncats.io/check_query_status/{id} + ## not TRAPI spec: BTE-specific endpoint related to asyncquery + # /check_query_status/{id}: + # ## moved because smartapi-editor gave alert that a non-existent post endpoint wouldn't know what {id} is + # parameters: + # - description: job-id + # in: path + # name: id + # required: true + # ## Cache refreshing means this will be changing pretty often, so not including an example + # schema: + # type: string + # get: + # tags: + # - asyncquery + # summary: >- + # This endpoint should be used when a Query was sent to BTE through an /asyncquery + # endpoint without a callback property: BTE then handled it in a polling manner and + # provided a job id. The job id can be used here to check the status or retrieve + # the Response. + # parameters: + # - description: option to override original query log level + # in: query + # name: log_level + # required: false + # schema: + # type: string + # description: >- + # Logging level. The order of priority is ERROR, WARNING, INFO, DEBUG. BTE will return all logs at the + # specified level and those at higher priority levels + # enum: + # - ERROR + # - WARNING + # - INFO + # - DEBUG + # responses: + # '200': + # description: Returns status. If successfully completed, it will return a TRAPI Response object under the field returnvalue + # content: + # application/json: + # schema: + # type: object + # required: + # - id + # - state + # properties: + # id: + # description: the job-id + # type: string + # state: + # description: the status of the job + # reason: + # description: when the state is 'failed', this field states a reason for the failure + # type: string + # returnvalue: + # ## returnvalue.response is where the TRAPI Response is + # description: >- + # When the state is 'completed', this will contain the TRAPI Response object. Note + # that BTE might return an error, no results, etc as a Response... + # type: object + # properties: + # response: + # $ref: '#/components/schemas/Response' + ## copied from BTE's /asyncquery and modified summary + /asyncquery: + post: + tags: + - asyncquery + summary: >- + This endpoint is for asynchronously querying Service Provider's SMARTAPI KP APIs (that have x-bte annotation) + as an individual TRAPI service. + + Initiate a query that will be handled in an asynchronous manner (there is a + queue and queries will be executed in the order that they enter the queue). + For BTE, it is optional to have a callback property in the request-body. If + the callback property is not included, BTE will handle the query in a polling + manner: it will provide a job-id that can be used to check the status or retrieve + the Response using BTE's /v1/check_query_status/{id} endpoint. + parameters: + - description: option to choose whether or not to enable caching + in: query + name: caching + required: false + schema: + type: boolean + - description: dryrun a query (logs the queries BTE will make) + in: query + name: dryrun + required: false + schema: + type: boolean + requestBody: + description: Query information to be submitted + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AsyncQuery' + ## should use MyVariant to answer this + example: + message: + query_graph: + nodes: + n0: + ids: + - "DBSNP:rs121913521" + categories: + - "biolink:SequenceVariant" + n1: + categories: + - "biolink:Disease" + edges: + e1: + subject: "n0" + object: "n1" + responses: + '200': + description: >- + The query is accepted for processing. The behavior will depend on whether + the callback property is included. If the callback property is included, + the Response will be sent to the callback url when complete. If the callback + property is not included, BTE will handle the query in a polling manner: it + will provide a job-id that can be used to check the status or retrieve + the Response using BTE's /v1/check_query_status/{id} endpoint. + content: + application/json: + schema: + type: string + '400': + description: >- + Bad request. The request is invalid according to this OpenAPI + schema OR a specific identifier is believed to be invalid somehow + (not just unrecognized). + content: + application/json: + schema: + type: string + '413': + description: >- + Payload too large. Indicates that batch size was over the limit + specified in x-trapi. + content: + application/json: + schema: + type: string + '429': + description: >- + Too many requests. Indicates that the client issued requests that + exceed the rate limit specified in x-trapi. + content: + application/json: + schema: + type: string + '500': + description: >- + Internal server error. + content: + application/json: + schema: + type: string + '501': + description: >- + Not implemented. + content: + application/json: + schema: + type: string +components: + ## look for comments to see parts that have been modified for BTE + ## - Query: comment out workflow.allOf section since the $ref breaks execution of + ## BTE's api-schema-builder/openapi-validator-middleware + ## - AsyncQuery: callback property not required (commented it out of the 'required' field), + ## comment out workflow.allOf section + ## - Response: comment out workflow.allOf section + ## - QEdge: set additionalProperties to false (see comments below for details) + ## - Attribute: comment out properties.attributes.items since the self-$ref breaks execution of + ## BTE's api-schema-builder/openapi-validator-middleware + schemas: + Query: + description: >- + 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. + x-body-name: request_body + type: object + properties: + message: + $ref: '#/components/schemas/Message' + description: >- + 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. + log_level: + description: The least critical level of logs to return + allOf: + - $ref: '#/components/schemas/LogLevel' + nullable: true + workflow: + description: List of workflow steps to be executed. + # allOf: + # - $ref: http://standards.ncats.io/workflow/1.0.0/schema + nullable: true + submitter: + type: string + description: >- + Any string for self-identifying the submitter of a query. The + purpose of this optional field is to aid in the tracking of + the source of queries for development and issue resolution. + nullable: true + additionalProperties: true + required: + - message + AsyncQuery: + description: >- + The AsyncQuery class is effectively the same as the Query class but + it requires a callback property. + x-body-name: request_body + type: object + properties: + callback: + type: string + format: uri + pattern: ^https?:// + description: >- + 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. + message: + $ref: '#/components/schemas/Message' + description: >- + 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. + log_level: + description: The least critical level of logs to return + allOf: + - $ref: '#/components/schemas/LogLevel' + nullable: true + workflow: + description: List of workflow steps to be executed. + # allOf: + # - $ref: http://standards.ncats.io/workflow/1.0.0/schema + nullable: true + submitter: + type: string + description: >- + Any string for self-identifying the submitter of a query. The + purpose of this optional field is to aid in the tracking of + the source of queries for development and issue resolution. + nullable: true + additionalProperties: true + required: + ## BTE does not require the callback property, see the asyncquery + ## endpoint summary and 200 response description + # - callback + - message + Response: + type: object + description: >- + 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. + properties: + message: + description: >- + Contains the knowledge of the response (query graph, knowledge + graph, and results). + $ref: '#/components/schemas/Message' + status: + description: >- + One of a standardized set of short codes, + e.g. Success, QueryNotTraversable, KPsNotAvailable + type: string + example: Success + nullable: true + description: + description: A brief human-readable description of the outcome + type: string + example: Success. 42 results found. + nullable: true + logs: + description: >- + Log entries containing errors, warnings, debugging information, etc + type: array + items: + $ref: '#/components/schemas/LogEntry' + nullable: true + workflow: + description: List of workflow steps that were executed. + # allOf: + # - $ref: http://standards.ncats.io/workflow/1.0.0/schema + nullable: true + additionalProperties: true + required: + - message + Message: + description: >- + 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. + type: object + properties: + results: + description: >- + List of all returned Result objects for the query posed. + The list SHOULD NOT be assumed to be ordered. The 'score' property, + if present, MAY be used to infer result rankings. + type: array + items: + $ref: '#/components/schemas/Result' + nullable: true + query_graph: + description: >- + QueryGraph object that contains a serialization of a query in the + form of a graph + allOf: + - $ref: '#/components/schemas/QueryGraph' + nullable: true + knowledge_graph: + description: >- + KnowledgeGraph object that contains lists of nodes and edges + in the thought graph corresponding to the message + allOf: + - $ref: '#/components/schemas/KnowledgeGraph' + nullable: true + additionalProperties: false + LogEntry: + description: >- + 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. + type: object + properties: + timestamp: + type: string + format: date-time + description: Timestamp in ISO 8601 format + example: '2020-09-03T18:13:49+00:00' + nullable: true + level: + allOf: + - $ref: '#/components/schemas/LogLevel' + nullable: true + code: + type: string + description: >- + One of a standardized set of short codes + e.g. QueryNotTraversable, KPNotAvailable, KPResponseMalformed + nullable: true + message: + type: string + description: A human-readable log message + nullable: true + additionalProperties: true + LogLevel: + type: string + description: Logging level + enum: + - ERROR + - WARNING + - INFO + - DEBUG + Result: + type: object + description: >- + 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 an EdgeBindings object (list of + query graph edge to knowledge graph edge mappings). + properties: + node_bindings: + type: object + description: >- + 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). This value is an + array of NodeBindings since a given query node may have multiple + knowledge graph Node bindings in the result. + additionalProperties: + type: array + items: + $ref: '#/components/schemas/NodeBinding' + edge_bindings: + type: object + description: >- + The dictionary of Input Query Graph to Result Knowledge Graph edge + bindings where the dictionary keys are the key identifiers of the + Query Graph edges and the associated values of those keys are + instances of EdgeBinding schema type (see below). This value is an + array of EdgeBindings since a given query edge may resolve to + multiple knowledge graph edges in the result. + additionalProperties: + type: array + items: + $ref: '#/components/schemas/EdgeBinding' + score: + type: number + format: float + example: 163.233 + description: >- + A numerical score associated with this result indicating the + relevance or confidence of this result relative to others in the + returned set. Higher MUST be better. + nullable: true + additionalProperties: true + required: + - node_bindings + - edge_bindings + NodeBinding: + type: object + description: >- + An instance of NodeBinding is a single KnowledgeGraph Node mapping, + identified by the corresponding 'id' object key identifier of the + Node within the Knowledge Graph. Instances of NodeBinding may + include extra annotation in the form of additional properties. + (such annotation is not yet fully standardized). + properties: + id: + $ref: '#/components/schemas/CURIE' + description: >- + The CURIE of a Node within the Knowledge Graph. + query_id: + $ref: '#/components/schemas/CURIE' + description: >- + An optional property to provide the CURIE in the QueryGraph to + which this binding applies. If the bound QNode does not have an + an 'id' property or if it is empty, then this query_id MUST be + null or absent. If the bound QNode has one or more CURIEs + as an 'id' and this NodeBinding's 'id' refers to a QNode 'id' + in a manner where the CURIEs are different (typically due to + the NodeBinding.id being a descendant of a QNode.id), then + this query_id MUST be provided. In other cases, there is no + ambiguity, and this query_id SHOULD NOT be provided. + attributes: + type: array + description: >- + A list of attributes providing further information about the + node binding. This is not intended for capturing node attributes + and should only be used for properties that vary from result to + result. + items: + $ref: '#/components/schemas/Attribute' + nullable: true + additionalProperties: true + required: + - id + EdgeBinding: + type: object + description: >- + A instance of EdgeBinding is a single KnowledgeGraph Edge mapping, + 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). + properties: + id: + type: string + description: The key identifier of a specific KnowledgeGraph Edge. + attributes: + type: array + description: >- + A list of attributes providing further information about the + edge binding. This is not intended for capturing edge attributes + and should only be used for properties that vary from result to + result. + items: + $ref: '#/components/schemas/Attribute' + nullable: true + additionalProperties: true + required: + - id + KnowledgeGraph: + type: object + description: >- + 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. + properties: + nodes: + type: object + description: >- + Dictionary of Node instances used in the KnowledgeGraph, + referenced elsewhere in the TRAPI output by the dictionary key. + additionalProperties: + $ref: '#/components/schemas/Node' + edges: + type: object + description: >- + Dictionary of Edge instances used in the KnowledgeGraph, + referenced elsewhere in the TRAPI output by the dictionary key. + additionalProperties: + $ref: '#/components/schemas/Edge' + additionalProperties: true + required: + - nodes + - edges + QueryGraph: + type: object + description: >- + 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. + properties: + nodes: + type: object + description: >- + The node specifications. The keys of this map are unique node + identifiers and the corresponding values include the constraints + on bound nodes. + additionalProperties: + $ref: '#/components/schemas/QNode' + edges: + type: object + description: >- + 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. + additionalProperties: + $ref: '#/components/schemas/QEdge' + additionalProperties: true + required: + - nodes + - edges + QNode: + type: object + description: 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. + properties: + ids: + type: array + items: + $ref: '#/components/schemas/CURIE' + minItems: 1 + example: [OMIM:603903] + description: CURIE identifier for this node + nullable: true + categories: + type: array + items: + $ref: '#/components/schemas/BiolinkEntity' + minItems: 1 + nullable: true + is_set: + type: boolean + description: >- + Boolean that if set to true, indicates that this QNode MAY have + multiple KnowledgeGraph Nodes bound to it within each Result. + The nodes in a set should be considered as a set of independent + nodes, rather than a set of dependent nodes, i.e., the answer + would still be valid if the nodes in the set were instead returned + individually. Multiple QNodes may have is_set=True. If a QNode + (n1) with is_set=True is connected to a QNode (n2) with + is_set=False, each n1 must be connected to n2. If a QNode (n1) + with is_set=True is connected to a QNode (n2) with is_set=True, + each n1 must be connected to at least one n2. + default: false + constraints: + type: array + description: >- + A list of contraints applied to a query node. + If there are multiple items, they must all be true (equivalent + to AND) + items: + $ref: '#/components/schemas/AttributeConstraint' + default: [] + additionalProperties: true + QEdge: + type: object + description: >- + An edge in the QueryGraph used as an 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. + properties: + knowledge_type: + description: >- + Indicates the type of knowledge that the client wants from the + server between the subject and object. If the value is + 'lookup', then the client wants direct lookup information from + knowledge sources. If the value is 'inferred', then the client + wants the server to get creative and connect the subject and + object in more speculative and non-direct-lookup ways. If this + property is absent or null, it MUST be assumed to mean + 'lookup'. This feature is currently experimental and may be + further extended in the future. + example: lookup + nullable: true + type: string + predicates: + type: array + items: + $ref: '#/components/schemas/BiolinkPredicate' + minItems: 1 + nullable: true + subject: + type: string + example: https://omim.org/entry/603903 + description: >- + Corresponds to the map key identifier of the + subject concept node anchoring the query filter + pattern for the query relationship edge. + object: + type: string + example: https://www.uniprot.org/uniprot/P00738 + description: >- + Corresponds to the map key identifier of the + object concept node anchoring the query filter + pattern for the query relationship edge. + attribute_constraints: + type: array + description: >- + A list of attribute contraints applied to a query edge. + If there are multiple items, they must all be true (equivalent + to AND) + items: + $ref: '#/components/schemas/AttributeConstraint' + default: [] + qualifier_constraints: + type: array + description: >- + A list of QualifierConstraints that provide nuance to the QEdge. + If multiple QualifierConstraints 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 qualifier_constraints MUST NOT be specified + because these complex use cases are not supported at this time. + items: + $ref: '#/components/schemas/QualifierConstraint' + default: [] + ## changing from true to false, so BTE will reject queries that have these additional properties + ## BTE doesn't use these and this is the easiest way to recognize when they are there and respond to that + ## Related to Implementation rules https://github.com/NCATSTranslator/ReasonerAPI/blob/1.3/ImplementationRules.md#qedgexxxxx + additionalProperties: false + required: + - subject + - object + Node: + type: object + description: >- + A node in the KnowledgeGraph which represents some biomedical + concept. Nodes are identified by the keys in the KnowledgeGraph + Node mapping. + properties: + name: + type: string + example: Haptoglobin + description: Formal name of the entity + nullable: true + categories: + type: array + items: + $ref: '#/components/schemas/BiolinkEntity' + nullable: true + attributes: + type: array + description: A list of attributes describing the node + items: + $ref: '#/components/schemas/Attribute' + nullable: true + additionalProperties: false + Attribute: + type: object + description: >- + 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). + properties: + attribute_type_id: + $ref: '#/components/schemas/CURIE' + description: >- + The 'key' of the attribute object, holding a CURIE of an ontology + property defining the attribute (preferably the CURIE of a + Biolink association slot). This property captures the relationship + asserted to hold between the value of the attribute, and the node + or edge from which it hangs. For example, that a value of + '0.000153' represents a p-value supporting an edge, or that + a value of 'ChEMBL' represents the original source of the knowledge + expressed in the edge. + example: biolink:synonym + original_attribute_name: + type: string + description: >- + The term used by the original source of an attribute to describe + the meaning or significance of the value it captures. This may be + a column name in a source tsv file, or a key in a source json + document for the field in the data that held the attribute's + value. Capturing this information where possible lets us preserve + what the original source said. Note that the data type is string' + but the contents of the field could also be a CURIE of a third + party ontology term. + example: p-value + nullable: true + value: + description: >- + Value of the attribute. May be any data type, including a list. + example: 0.000153 + value_type_id: + allOf: + - $ref: '#/components/schemas/CURIE' + description: >- + CURIE describing the semantic type of an attribute's value. Use + a Biolink class if possible, otherwise a term from an external + ontology. If a suitable CURIE/identifier does not exist, enter a + descriptive phrase here and submit the new type for consideration + by the appropriate authority. + example: EDAM:data_1187 + nullable: true + attribute_source: + type: string + description: >- + The source of the core assertion made by the key-value pair of an + attribute object. Use a CURIE or namespace designator for this + resource where possible. + example: UniProtKB + nullable: true + value_url: + type: string + description: >- + Human-consumable URL linking to a web document that provides + additional information about an attribute's value (not the node + or the edge fom which it hangs). + example: https://pubmed.ncbi.nlm.nih.gov/32529952 + nullable: true + description: + type: string + description: >- + Human-readable description for the attribute and its value. + example: Assertion Authored By Dr. Trans L. Ator + nullable: true + attributes: + type: array + description: >- + A list of attributes providing further information about the + parent attribute (for example to provide provenance + information about the parent attribute). + # items: + # $ref: '#/components/schemas/Attribute' + nullable: true + required: + - attribute_type_id + - value + additionalProperties: false + Edge: + type: object + description: >- + 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. + properties: + predicate: + allOf: + - $ref: '#/components/schemas/BiolinkPredicate' + nullable: true + subject: + $ref: '#/components/schemas/CURIE' + example: OMIM:603903 + description: >- + Corresponds to the map key CURIE of the + subject concept node of this relationship edge. + object: + $ref: '#/components/schemas/CURIE' + example: UniProtKB:P00738 + description: >- + Corresponds to the map key CURIE of the + object concept node of this relationship edge. + attributes: + type: array + description: A list of additional attributes for this edge + items: + $ref: '#/components/schemas/Attribute' + nullable: true + qualifiers: + type: array + description: >- + A set of Qualifiers that act together to add nuance + or detail to the statement expressed in an Edge. + items: + $ref: '#/components/schemas/Qualifier' + nullable: true + additionalProperties: false + required: + - subject + - object + Qualifier: + additionalProperties: false + description: >- + An additional nuance attached to an assertion + type: object + properties: + qualifier_type_id: + type: string + description: >- + The category of the qualifier, drawn from a hierarchy of qualifier + slots in the Biolink model (e.g. subject_aspect, subject_direction, + object_aspect, object_direction, etc). + example: subject_aspect + nullable: false + qualifier_value: + type: string + description: >- + 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 'subject_aspect', etc). + example: expression + nullable: false + required: + - qualifier_type_id + - qualifier_value + QualifierConstraint: + additionalProperties: false + description: >- + Defines a query constraint based on the + qualifier_types and qualifier_values of a set of + Qualifiers attached to an edge. For example, it 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 "object_aspect" with + a qualifier_value of "expression". + properties: + qualifier_set: + type: array + description: >- + A set of Qualifiers that serves to add nuance to a query, + by constraining allowed values held by Qualifiers + on queried Edges. + items: + $ref: '#/components/schemas/Qualifier' + nullable: false + required: + - qualifier_set + type: object + BiolinkEntity: + description: >- + 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. + type: string + pattern: ^biolink:[A-Z][a-zA-Z]*$ + externalDocs: + description: Biolink model entities + url: https://biolink.github.io/biolink-model/docs/NamedThing.html + example: biolink:PhenotypicFeature + BiolinkPredicate: + description: >- + 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. + type: string + pattern: ^biolink:[a-z][a-z_]*$ + externalDocs: + description: Biolink model predicates + url: https://biolink.github.io/biolink-model/docs/related_to.html + example: biolink:interacts_with + CURIE: + type: string + description: >- + 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. + externalDocs: + url: https://www.w3.org/TR/2010/NOTE-curie-20101216/ + MetaKnowledgeGraph: + type: object + description: >- + 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. + properties: + nodes: + type: object + description: >- + 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. + additionalProperties: + $ref: '#/components/schemas/MetaNode' + edges: + type: array + description: >- + 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. + items: + $ref: '#/components/schemas/MetaEdge' + required: + - nodes + - edges + MetaNode: + type: object + description: >- + Description of a node category provided by this TRAPI web service. + properties: + id_prefixes: + type: array + description: >- + List of CURIE prefixes for the node category that this TRAPI web + service understands and accepts on the input. + items: + type: string + minItems: 1 + example: [CHEMBL.COMPOUND, INCHIKEY] + attributes: + type: array + description: >- + Node attributes provided by this TRAPI web service. + items: + $ref: '#/components/schemas/MetaAttribute' + nullable: true + required: + - id_prefixes + additionalProperties: false + MetaEdge: + type: object + description: >- + Edge in a meta knowledge map describing relationship between a subject + Biolink class and an object Biolink class. + properties: + subject: + $ref: '#/components/schemas/BiolinkEntity' + description: >- + Subject node category of this relationship edge. + example: biolink:ChemicalEntity + predicate: + $ref: '#/components/schemas/BiolinkPredicate' + description: >- + Biolink relationship between the subject and object categories. + example: biolink:affects + object: + $ref: '#/components/schemas/BiolinkEntity' + description: >- + Object node category of this relationship edge. + example: biolink:Protein + knowledge_types: + description: >- + A list of knowledge_types that are supported by the service. + If the knowledge_types is null, this means that only 'lookup' + is supported. Currently allowed values are 'lookup' or 'inferred'. + items: + type: string + minItems: 1 + nullable: true + type: array + attributes: + type: array + description: >- + Edge attributes provided by this TRAPI web service. + items: + $ref: '#/components/schemas/MetaAttribute' + nullable: true + required: + - subject + - predicate + - object + additionalProperties: false + MetaAttribute: + type: object + properties: + attribute_type_id: + $ref: '#/components/schemas/CURIE' + description: >- + Type of an attribute provided by this TRAPI web service + (preferably the CURIE of a Biolink association slot) + example: biolink:p_value + attribute_source: + type: string + description: >- + Source of an attribute provided by this TRAPI web service. + example: infores:chembl + nullable: true + original_attribute_names: + type: array + items: + type: string + description: >- + Names of an the attribute as provided by the source. + nullable: true + minItems: 1 + constraint_use: + type: boolean + description: >- + Indicates whether this attribute can be used as a query + constraint. + default: false + constraint_name: + type: string + description: >- + Human-readable name or label for the constraint concept. + Required whenever constraint_use is true. + example: p-value + nullable: true + required: + - attribute_type_id + AttributeConstraint: + type: object + description: >- + Generic query constraint for a query node or query edge + properties: + id: + allOf: + - $ref: '#/components/schemas/CURIE' + description: >- + CURIE of the concept being constrained. For properties + defined by the Biolink model this SHOULD be a biolink CURIE. + otherwise, if possible, from the EDAM ontology. If a suitable + CURIE does not exist, enter a descriptive phrase here and + submit the new type for consideration by the appropriate + authority. + example: EDAM:data_0844 + name: + type: string + description: >- + Human-readable name or label for the constraint concept. + If appropriate, it SHOULD be the term name of the CURIE used + as the 'id'. This is redundant but required for human + readability. + example: molecular mass + not: + type: boolean + default: false + operator: + type: string + description: >- + Relationship between the database value and the constraint value + for the specified id. The operators ==, >, and < mean + is equal to, is greater than, and is less than, + respectively. The 'matches' operator indicates that the value + is a regular expression to be evaluated. If value is a list type, + then at least one evaluation must be true (equivalent to OR). + This means that the == operator with a list acts like a SQL 'IN' + clause. If the value of the compared attribute is a list, then + comparisons are performed between each of the constraint values + and each of the attribute values, and any one true evaluation + counts as an overall true (e.g., [1,2,3] == [6,7,2] is true). + The == operator is therefore a broad interpretation of inclusion. + The '===' operator requires that the constraint value and + the attribute value be the same data type, length, + content, and order (e.g. only [1,2,3] === [1,2,3]). + The 'not' property negates the operator such that not + and == means 'not equal to' (or 'not in' for a list), and not > + means <=, and not < means >=, not matches means does not + match, and not === means the match between the constraint + and attribute values are not exact. + The '==' operator SHOULD NOT be used in a manner that + describes an "is a" subclass relationship for the parent QNode. + enum: + - == + - '>' + - < + - matches + - === + value: + example: 57.0 + description: >- + Value of the attribute. May be any data type, including a list. + If the value is a list and there are multiple items, at least one + comparison must be true (equivalent to OR) unless the '===' + operator is used. If 'value' is of data + type 'object', the keys of the object MAY be treated as a list. + A 'list' data type paired with the '>' or '<' operators will + encode extraneous comparisons, but this is permitted as it is in + SQL and other languages. + unit_id: + example: UO:0000222 + description: >- + 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. + nullable: true + unit_name: + example: kilodalton + description: >- + 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. + nullable: true + required: + - name + - id + - operator + - value + additionalProperties: false diff --git a/biothings_explorer/smartapi.yaml b/biothings_explorer/smartapi.yaml index d23d0fc8..2928d518 100644 --- a/biothings_explorer/smartapi.yaml +++ b/biothings_explorer/smartapi.yaml @@ -6,16 +6,15 @@ info: url: https://github.com/andrewsu description: A TRAPI/Reasoner Standard API for BioThings Explorer (BTE) termsOfService: https://biothings.io/about - title: BioThings Explorer (BTE) TRAPI + title: BioThings Explorer (BTE) TRAPI (v1.2) version: 2.8.1 x-trapi: - version: 1.3.0 + version: 1.2.0 ## will update to 1.3 once all instances have trapi1.3 code asyncquery: true operations: ## look at https://standards.ncats.io/operation.json for details. was previously lookup - lookup_and_score ## no batch_size_limit (BTE manages IDs for QNodes and sub-queries internally) - rate_limit: 15 ## /query endpoints have a limit of 15 requests/client/min ## /meta_knowledge_graph endpoints have a limit of 30 requests/client/min ## other endpoints don't have rate limits @@ -40,11 +39,8 @@ servers: - url: https://bte.ci.transltr.io/v1 description: ITRB CI server x-maturity: staging -- url: https://api.bte.ncats.io/v1 - description: Non-ITRB dev (primary internal use) - x-maturity: development tags: -- name: 1.3.0 +- name: 1.2.0 ## will update to 1.3 once all instances have trapi1.3 code - name: meta_knowledge_graph - name: query - name: asyncquery @@ -61,11 +57,10 @@ paths: tags: - meta_knowledge_graph summary: Meta knowledge graph representation of this TRAPI web service. + description: Returns meta knowledge graph representation of this TRAPI web service. responses: '200': - description: >- - Returns meta knowledge graph representation of this TRAPI web - service. + description: Successful Response content: application/json: schema: @@ -75,11 +70,10 @@ paths: get: tags: - meta_knowledge_graph - summary: TRAPI-compliant meta-knowledge-graph representation for an individual SmartAPI KP API (that has x-bte annotation) + summary: TRAPI-compliant Meta knowledge graph representation for an individual SmartAPI KP API (that has x-bte annotation) + description: Returns a TRAPI-compliant meta knowledge graph representation of an individual SmartAPI KP API (that has x-bte annotation) parameters: - - description: >- - SmartAPI ID of an API with x-bte annotation. The easiest way to find these is to read the list of APIs BTE uses - https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js + - description: SmartAPI ID of an API, you can get it from https://smart-api.info/registry in: path name: smartapi_id required: true @@ -88,8 +82,7 @@ paths: type: string responses: '200': - description: >- - Returns a TRAPI-compliant meta-knowledge-graph representation for an individual SmartAPI KP API (that has x-bte annotation) + description: Successful Response content: application/json: schema: @@ -99,14 +92,10 @@ paths: get: tags: - meta_knowledge_graph - summary: TRAPI-compliant meta-knowledge-graph representation for one KP team's SmartAPI KP APIs (that have x-bte annotation) + summary: TRAPI-compliant Meta knowledge graph representation for one KP/ARA team's SmartAPI KP APIs (that have x-bte annotation) + description: Returns a TRAPI-compliant meta knowledge graph representation of one team's set of SmartAPI KP APIs (that have x-bte annotation) parameters: - - description: >- - Translator Team Name. Current options: Service Provider, Multiomics Provider, Text Mining Provider. - The easiest way to find what KP APIs would be included under these teams is to read the list of APIs BTE uses - https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js. - Note that Service Provider endpoints are also advertised separately as a KP - http://smart-api.info/registry?q=36f82f05705c317bac17ddae3a0ea2f0 + - description: Translator Team Name, e.g. Service Provider, Multiomics Provider in: path name: team_name required: true @@ -119,8 +108,7 @@ paths: - Service Provider responses: '200': - description: >- - Returns a TRAPI-compliant meta-knowledge-graph representation for one KP team's SmartAPI KP APIs (that have x-bte annotation) + description: Successful Response content: application/json: schema: @@ -130,7 +118,7 @@ paths: post: tags: - query - summary: Initiate a TRAPI-format query to BTE (operating as an ARA) and wait to receive a Response + summary: Query BioThings Explorer TRAPI API as ARA with a TRAPI query parameters: - description: option to choose whether or not to enable caching in: query @@ -149,8 +137,6 @@ paths: required: true content: application/json: - schema: - $ref: '#/components/schemas/Query' ## should use MyVariant to answer this example: message: @@ -168,6 +154,8 @@ paths: e1: subject: "n0" object: "n1" + schema: + $ref: '#/components/schemas/Query' responses: '200': description: >- @@ -186,22 +174,6 @@ paths: application/json: schema: type: string - '413': - description: >- - Payload too large. Indicates that batch size was over the limit - specified in x-trapi. - content: - application/json: - schema: - type: string - '429': - description: >- - Too many requests. Indicates that the client issued requests that - exceed the rate limit specified in x-trapi. - content: - application/json: - schema: - type: string '500': description: >- Internal server error. @@ -216,16 +188,14 @@ paths: application/json: schema: type: string - ## copied from /query above and modified: BTE-specific endpoint + ## copied from /query above and modified: BTE-specific endpoint /smartapi/{smartapi_id}/query: post: tags: - query - summary: Query individual SmartAPI KP API (that has x-bte annotation) as a TRAPI KP API + summary: Query individual SmartAPI KP API (that has x-bte annotation) as a TRAPI API parameters: - - description: >- - SmartAPI ID of an API with x-bte annotation. The easiest way to find these is to read the list of APIs BTE uses - https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js + - description: SmartAPI ID of an API, you can get it from https://smart-api.info/registry in: path name: smartapi_id required: true @@ -249,8 +219,6 @@ paths: required: true content: application/json: - schema: - $ref: '#/components/schemas/Query' ## should use MyVariant to answer this example: message: @@ -268,6 +236,8 @@ paths: e1: subject: "n0" object: "n1" + schema: + $ref: '#/components/schemas/Query' responses: '200': description: >- @@ -286,22 +256,6 @@ paths: application/json: schema: type: string - '413': - description: >- - Payload too large. Indicates that batch size was over the limit - specified in x-trapi. - content: - application/json: - schema: - type: string - '429': - description: >- - Too many requests. Indicates that the client issued requests that - exceed the rate limit specified in x-trapi. - content: - application/json: - schema: - type: string '500': description: >- Internal server error. @@ -323,14 +277,10 @@ paths: - query summary: >- Query an individual Translator team's SMARTAPI KP APIs (that have x-bte annotation) as an individual TRAPI - service by specifying the team name + service using team name + description: '' parameters: - - description: >- - Translator Team Name. Current options: Service Provider, Multiomics Provider, Text Mining Provider. - The easiest way to find what KP APIs would be included under these teams is to read the list of APIs BTE uses - https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js. - Note that Service Provider endpoints are also advertised separately as a KP - http://smart-api.info/registry?q=36f82f05705c317bac17ddae3a0ea2f0 + - description: Translator Team Name, e.g. Service Provider, Multiomics Provider in: path name: team_name required: true @@ -358,8 +308,6 @@ paths: required: true content: application/json: - schema: - $ref: '#/components/schemas/Query' ## should use MyVariant to answer this example: message: @@ -377,6 +325,8 @@ paths: e1: subject: "n0" object: "n1" + schema: + $ref: '#/components/schemas/Query' responses: '200': description: >- @@ -395,22 +345,6 @@ paths: application/json: schema: type: string - '413': - description: >- - Payload too large. Indicates that batch size was over the limit - specified in x-trapi. - content: - application/json: - schema: - type: string - '429': - description: >- - Too many requests. Indicates that the client issued requests that - exceed the rate limit specified in x-trapi. - content: - application/json: - schema: - type: string '500': description: >- Internal server error. @@ -444,6 +378,7 @@ paths: endpoint without a callback property: BTE then handled it in a polling manner and provided a job id. The job id can be used here to check the status or retrieve the Response. + description: '' parameters: - description: option to override original query log level in: query @@ -451,9 +386,7 @@ paths: required: false schema: type: string - description: >- - Logging level. The order of priority is ERROR, WARNING, INFO, DEBUG. BTE will return all logs at the - specified level and those at higher priority levels + description: Logging level enum: - ERROR - WARNING @@ -461,7 +394,7 @@ paths: - DEBUG responses: '200': - description: Returns status. If successfully completed, it will return a TRAPI Response object under the field returnvalue + description: Returns status. If successfully completed, it will return a TRAPI Response object content: application/json: schema: @@ -487,7 +420,7 @@ paths: properties: response: $ref: '#/components/schemas/Response' - ## modified TRAPI spec: summary sections tell users that AsyncQuery schema was changed to make callback optional + ## modified TRAPI spec: summary sections tell users that AsyncQuery schema was changed to make callback optional /asyncquery: post: tags: @@ -498,7 +431,8 @@ paths: For BTE, it is optional to have a callback property in the request-body. If the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve - the Response using BTE's /v1/check_query_status/{id} endpoint. + the Response using the /v1/check_query_status/{id} endpoint. + description: '' parameters: - description: option to choose whether or not to enable caching in: query @@ -517,8 +451,6 @@ paths: required: true content: application/json: - schema: - $ref: '#/components/schemas/AsyncQuery' ## should use MyVariant to answer this example: message: @@ -536,6 +468,8 @@ paths: e1: subject: "n0" object: "n1" + schema: + $ref: '#/components/schemas/AsyncQuery' responses: '200': description: >- @@ -544,7 +478,7 @@ paths: the Response will be sent to the callback url when complete. If the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve - the Response using BTE's /v1/check_query_status/{id} endpoint. + the Response using the /v1/check_query_status/{id} endpoint. content: application/json: schema: @@ -558,22 +492,6 @@ paths: application/json: schema: type: string - '413': - description: >- - Payload too large. Indicates that batch size was over the limit - specified in x-trapi. - content: - application/json: - schema: - type: string - '429': - description: >- - Too many requests. Indicates that the client issued requests that - exceed the rate limit specified in x-trapi. - content: - application/json: - schema: - type: string '500': description: >- Internal server error. @@ -594,19 +512,17 @@ paths: tags: - asyncquery summary: >- - This endpoint is for asynchronously querying an individual SmartAPI KP API (that has x-bte annotation) - as a TRAPI KP API. + This endpoint is for individual SmartAPI KP APIs (that have x-bte annotation), to query + them through a TRAPI API interface (BTE). Initiate a query that will be handled in an asynchronous manner (there is a queue and queries will be executed in the order that they enter the queue). For BTE, it is optional to have a callback property in the request-body. If the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve - the Response using BTE's /v1/check_query_status/{id} endpoint. + the Response using the /v1/check_query_status/{id} endpoint. parameters: - - description: >- - SmartAPI ID of an API with x-bte annotation. The easiest way to find these is to read the list of APIs BTE uses - https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js + - description: SmartAPI ID of an API, you can get it from https://smart-api.info/registry in: path name: smartapi_id required: true @@ -630,8 +546,6 @@ paths: required: true content: application/json: - schema: - $ref: '#/components/schemas/AsyncQuery' ## should use MyVariant to answer this example: message: @@ -649,6 +563,8 @@ paths: e1: subject: "n0" object: "n1" + schema: + $ref: '#/components/schemas/AsyncQuery' responses: '200': description: >- @@ -657,7 +573,7 @@ paths: the Response will be sent to the callback url when complete. If the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve - the Response using BTE's /v1/check_query_status/{id} endpoint. + the Response using the /v1/check_query_status/{id} endpoint. content: application/json: schema: @@ -671,22 +587,6 @@ paths: application/json: schema: type: string - '413': - description: >- - Payload too large. Indicates that batch size was over the limit - specified in x-trapi. - content: - application/json: - schema: - type: string - '429': - description: >- - Too many requests. Indicates that the client issued requests that - exceed the rate limit specified in x-trapi. - content: - application/json: - schema: - type: string '500': description: >- Internal server error. @@ -707,22 +607,18 @@ paths: tags: - asyncquery summary: >- - This endpoint is for asynchronously querying an individual Translator team's SMARTAPI KP APIs (that have x-bte annotation) - as an individual TRAPI service by specifying the team name. + This endpoint is for querying an individual Translator team's SMARTAPI KP APIs + (that have x-bte annotation) through a TRAPI API interface (BTE). Initiate a query that will be handled in an asynchronous manner (there is a queue and queries will be executed in the order that they enter the queue). For BTE, it is optional to have a callback property in the request-body. If the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve - the Response using BTE's /v1/check_query_status/{id} endpoint. + the Response using the /v1/check_query_status/{id} endpoint. + description: '' parameters: - - description: >- - Translator Team Name. Current options: Service Provider, Multiomics Provider, Text Mining Provider. - The easiest way to find what KP APIs would be included under these teams is to read the list of APIs BTE uses - https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js. - Note that Service Provider endpoints are also advertised separately as a KP - http://smart-api.info/registry?q=36f82f05705c317bac17ddae3a0ea2f0 + - description: Translator Team Name, e.g. Service Provider, Multiomics Provider in: path name: team_name required: true @@ -750,8 +646,6 @@ paths: required: true content: application/json: - schema: - $ref: '#/components/schemas/AsyncQuery' ## should use MyVariant to answer this example: message: @@ -769,6 +663,8 @@ paths: e1: subject: "n0" object: "n1" + schema: + $ref: '#/components/schemas/AsyncQuery' responses: '200': description: >- @@ -777,7 +673,7 @@ paths: the Response will be sent to the callback url when complete. If the callback property is not included, BTE will handle the query in a polling manner: it will provide a job-id that can be used to check the status or retrieve - the Response using BTE's /v1/check_query_status/{id} endpoint. + the Response using the /v1/check_query_status/{id} endpoint. content: application/json: schema: @@ -791,22 +687,6 @@ paths: application/json: schema: type: string - '413': - description: >- - Payload too large. Indicates that batch size was over the limit - specified in x-trapi. - content: - application/json: - schema: - type: string - '429': - description: >- - Too many requests. Indicates that the client issued requests that - exceed the rate limit specified in x-trapi. - content: - application/json: - schema: - type: string '500': description: >- Internal server error. @@ -828,9 +708,7 @@ components: ## - AsyncQuery: callback property not required (commented it out of the 'required' field), ## comment out workflow.allOf section ## - Response: comment out workflow.allOf section - ## - QEdge: set additionalProperties to false (see comments below for details) - ## - Attribute: comment out properties.attributes.items since the self-$ref breaks execution of - ## BTE's api-schema-builder/openapi-validator-middleware + ## - QNode: commented out an example for some reason schemas: Query: description: >- @@ -862,13 +740,6 @@ components: # allOf: # - $ref: http://standards.ncats.io/workflow/1.0.0/schema nullable: true - submitter: - type: string - description: >- - Any string for self-identifying the submitter of a query. The - purpose of this optional field is to aid in the tracking of - the source of queries for development and issue resolution. - nullable: true additionalProperties: true required: - message @@ -910,17 +781,10 @@ components: # allOf: # - $ref: http://standards.ncats.io/workflow/1.0.0/schema nullable: true - submitter: - type: string - description: >- - Any string for self-identifying the submitter of a query. The - purpose of this optional field is to aid in the tracking of - the source of queries for development and issue resolution. - nullable: true additionalProperties: true - required: ## BTE does not require the callback property, see the asyncquery ## endpoint summary and 200 response description + required: # - callback - message Response: @@ -1093,39 +957,15 @@ components: - edge_bindings NodeBinding: type: object - description: >- - An instance of NodeBinding is a single KnowledgeGraph Node mapping, - identified by the corresponding 'id' object key identifier of the - Node within the Knowledge Graph. Instances of NodeBinding may - include extra annotation in the form of additional properties. - (such annotation is not yet fully standardized). properties: id: $ref: '#/components/schemas/CURIE' description: >- - The CURIE of a Node within the Knowledge Graph. - query_id: - $ref: '#/components/schemas/CURIE' - description: >- - An optional property to provide the CURIE in the QueryGraph to - which this binding applies. If the bound QNode does not have an - an 'id' property or if it is empty, then this query_id MUST be - null or absent. If the bound QNode has one or more CURIEs - as an 'id' and this NodeBinding's 'id' refers to a QNode 'id' - in a manner where the CURIEs are different (typically due to - the NodeBinding.id being a descendant of a QNode.id), then - this query_id MUST be provided. In other cases, there is no - ambiguity, and this query_id SHOULD NOT be provided. - attributes: - type: array - description: >- - A list of attributes providing further information about the - node binding. This is not intended for capturing node attributes - and should only be used for properties that vary from result to - result. - items: - $ref: '#/components/schemas/Attribute' - nullable: true + An instance of NodeBinding is a single KnowledgeGraph Node mapping, + identified by the corresponding 'id' object key identifier of the + Node within the Knowledge Graph. Instances of NodeBinding may + include extra annotation (such annotation is not yet fully + standardized). additionalProperties: true required: - id @@ -1220,7 +1060,8 @@ components: items: $ref: '#/components/schemas/CURIE' minItems: 1 - example: [OMIM:603903] + ## commenting it out since smartapi editor doesn't handle this well + # example: [OMIM:603903] description: CURIE identifier for this node nullable: true categories: @@ -1250,7 +1091,7 @@ components: If there are multiple items, they must all be true (equivalent to AND) items: - $ref: '#/components/schemas/AttributeConstraint' + $ref: '#/components/schemas/QueryConstraint' default: [] additionalProperties: true QEdge: @@ -1264,20 +1105,6 @@ components: an exact match to the given QEdge predicate term, or to a term that is a descendant of the QEdge predicate term. properties: - knowledge_type: - description: >- - Indicates the type of knowledge that the client wants from the - server between the subject and object. If the value is - 'lookup', then the client wants direct lookup information from - knowledge sources. If the value is 'inferred', then the client - wants the server to get creative and connect the subject and - object in more speculative and non-direct-lookup ways. If this - property is absent or null, it MUST be assumed to mean - 'lookup'. This feature is currently experimental and may be - further extended in the future. - example: lookup - nullable: true - type: string predicates: type: array items: @@ -1298,32 +1125,16 @@ components: Corresponds to the map key identifier of the object concept node anchoring the query filter pattern for the query relationship edge. - attribute_constraints: + constraints: type: array description: >- - A list of attribute contraints applied to a query edge. + A list of contraints applied to a query edge. If there are multiple items, they must all be true (equivalent to AND) items: - $ref: '#/components/schemas/AttributeConstraint' - default: [] - qualifier_constraints: - type: array - description: >- - A list of QualifierConstraints that provide nuance to the QEdge. - If multiple QualifierConstraints 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 qualifier_constraints MUST NOT be specified - because these complex use cases are not supported at this time. - items: - $ref: '#/components/schemas/QualifierConstraint' + $ref: '#/components/schemas/QueryConstraint' default: [] - ## changing from true to false, so BTE will reject queries that have these additional properties - ## BTE doesn't use these and this is the easiest way to recognize when they are there and respond to that - ## Related to Implementation rules https://github.com/NCATSTranslator/ReasonerAPI/blob/1.3/ImplementationRules.md#qedgexxxxx - additionalProperties: false + additionalProperties: true required: - subject - object @@ -1359,7 +1170,7 @@ components: 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 + about it. An attribute may be further qualified with a SubAttribute (for example to provide confidence intervals on a value). properties: attribute_type_id: @@ -1373,7 +1184,7 @@ components: '0.000153' represents a p-value supporting an edge, or that a value of 'ChEMBL' represents the original source of the knowledge expressed in the edge. - example: biolink:synonym + example: Biolink:has_p-value_evidence, Biolink:has_original_source original_attribute_name: type: string description: >- @@ -1430,8 +1241,80 @@ components: A list of attributes providing further information about the parent attribute (for example to provide provenance information about the parent attribute). - # items: - # $ref: '#/components/schemas/Attribute' + items: + $ref: '#/components/schemas/SubAttribute' + nullable: true + required: + - attribute_type_id + - value + additionalProperties: false + SubAttribute: + type: object + description: >- + Second-level attribute that can be used to qualify information + contained in a primary Attribute attached to a Node or Edge. + properties: + attribute_type_id: + $ref: '#/components/schemas/CURIE' + description: >- + The 'key' of the attribute object, holding a CURIE of an ontology + property defining the attribute (preferably the CURIE of a + Biolink association slot). This property captures the relationship + asserted to hold between the value of the attribute, and the node + or edge from which it hangs. For example, that a value of + '0.000153' represents a p-value supporting an edge, or that + a value of 'ChEMBL' represents the original source of the knowledge + expressed in the edge. + example: Biolink:has_p-value_evidence, Biolink:has_original_source + original_attribute_name: + type: string + description: >- + The term used by the original source of an attribute to describe + the meaning or significance of the value it captures. This may be + a column name in a source tsv file, or a key in a source json + document for the field in the data that held the attribute's + value. Capturing this information where possible lets us preserve + what the original source said. Note that the data type is string' + but the contents of the field could also be a CURIE of a third + party ontology term. + example: p-value + nullable: true + value: + description: >- + Value of the attribute. May be any data type, including a list. + example: 0.000153 + value_type_id: + allOf: + - $ref: '#/components/schemas/CURIE' + description: >- + CURIE describing the semantic type of an attribute's value. Use + a Biolink class if possible, otherwise a term from an external + ontology. If a suitable CURIE/identifier does not exist, enter a + descriptive phrase here and submit the new type for consideration + by the appropriate authority. + example: EDAM:data_1187 + nullable: true + attribute_source: + type: string + description: >- + The source of the core assertion made by the key-value pair of an + attribute object. Use a CURIE or namespace designator for this + resource where possible. + example: UniProtKB + nullable: true + value_url: + type: string + description: >- + Human-consumable URL linking to a web document that provides + additional information about an attribute's value (not the node + or the edge fom which it hangs). + example: https://pubmed.ncbi.nlm.nih.gov/32529952 + nullable: true + description: + type: string + description: >- + Human-readable description for the attribute and its value. + example: Assertion Authored By Dr. Trans L. Ator nullable: true required: - attribute_type_id @@ -1466,67 +1349,10 @@ components: items: $ref: '#/components/schemas/Attribute' nullable: true - qualifiers: - type: array - description: >- - A set of Qualifiers that act together to add nuance - or detail to the statement expressed in an Edge. - items: - $ref: '#/components/schemas/Qualifier' - nullable: true additionalProperties: false required: - subject - object - Qualifier: - additionalProperties: false - description: >- - An additional nuance attached to an assertion - type: object - properties: - qualifier_type_id: - type: string - description: >- - The category of the qualifier, drawn from a hierarchy of qualifier - slots in the Biolink model (e.g. subject_aspect, subject_direction, - object_aspect, object_direction, etc). - example: subject_aspect - nullable: false - qualifier_value: - type: string - description: >- - 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 'subject_aspect', etc). - example: expression - nullable: false - required: - - qualifier_type_id - - qualifier_value - QualifierConstraint: - additionalProperties: false - description: >- - Defines a query constraint based on the - qualifier_types and qualifier_values of a set of - Qualifiers attached to an edge. For example, it 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 "object_aspect" with - a qualifier_value of "expression". - properties: - qualifier_set: - type: array - description: >- - A set of Qualifiers that serves to add nuance to a query, - by constraining allowed values held by Qualifiers - on queried Edges. - items: - $ref: '#/components/schemas/Qualifier' - nullable: false - required: - - qualifier_set - type: object BiolinkEntity: description: >- Compact URI (CURIE) for a Biolink class, biolink:NamedThing @@ -1621,7 +1447,7 @@ components: $ref: '#/components/schemas/BiolinkEntity' description: >- Subject node category of this relationship edge. - example: biolink:ChemicalEntity + example: biolink:ChemicalSubstance predicate: $ref: '#/components/schemas/BiolinkPredicate' description: >- @@ -1632,16 +1458,6 @@ components: description: >- Object node category of this relationship edge. example: biolink:Protein - knowledge_types: - description: >- - A list of knowledge_types that are supported by the service. - If the knowledge_types is null, this means that only 'lookup' - is supported. Currently allowed values are 'lookup' or 'inferred'. - items: - type: string - minItems: 1 - nullable: true - type: array attributes: type: array description: >- @@ -1692,7 +1508,7 @@ components: nullable: true required: - attribute_type_id - AttributeConstraint: + QueryConstraint: type: object description: >- Generic query constraint for a query node or query edge @@ -1724,39 +1540,27 @@ components: description: >- Relationship between the database value and the constraint value for the specified id. The operators ==, >, and < mean - is equal to, is greater than, and is less than, + is exactly equal to, is greater than, and is less than, respectively. The 'matches' operator indicates that the value is a regular expression to be evaluated. If value is a list type, then at least one evaluation must be true (equivalent to OR). This means that the == operator with a list acts like a SQL 'IN' - clause. If the value of the compared attribute is a list, then - comparisons are performed between each of the constraint values - and each of the attribute values, and any one true evaluation - counts as an overall true (e.g., [1,2,3] == [6,7,2] is true). - The == operator is therefore a broad interpretation of inclusion. - The '===' operator requires that the constraint value and - the attribute value be the same data type, length, - content, and order (e.g. only [1,2,3] === [1,2,3]). - The 'not' property negates the operator such that not + clause. The 'not' property negates the operator such that not and == means 'not equal to' (or 'not in' for a list), and not > - means <=, and not < means >=, not matches means does not - match, and not === means the match between the constraint - and attribute values are not exact. - The '==' operator SHOULD NOT be used in a manner that + means <=, and not < means >=, and not matches means does not + match. The '==' operator SHOULD NOT be used in a manner that describes an "is a" subclass relationship for the parent QNode. enum: - == - '>' - < - matches - - === value: example: 57.0 description: >- Value of the attribute. May be any data type, including a list. If the value is a list and there are multiple items, at least one - comparison must be true (equivalent to OR) unless the '===' - operator is used. If 'value' is of data + comparison must be true (equivalent to OR). If 'value' is of data type 'object', the keys of the object MAY be treated as a list. A 'list' data type paired with the '>' or '<' operators will encode extraneous comparisons, but this is permitted as it is in diff --git a/biothings_explorer/smartapi_temp13.yaml b/biothings_explorer/smartapi_temp13.yaml new file mode 100644 index 00000000..cd6a0a3b --- /dev/null +++ b/biothings_explorer/smartapi_temp13.yaml @@ -0,0 +1,1777 @@ +openapi: 3.0.3 +info: + contact: + email: asu@scripps.edu + name: Andrew Su + url: https://github.com/andrewsu + description: A TRAPI/Reasoner Standard API for BioThings Explorer (BTE) + termsOfService: https://biothings.io/about + title: BioThings Explorer (BTE) TRAPI (v1.3) + version: 2.8.1 + x-trapi: + version: 1.3.0 + asyncquery: true + operations: + ## look at https://standards.ncats.io/operation.json for details. was previously lookup + - lookup_and_score + ## no batch_size_limit (BTE manages IDs for QNodes and sub-queries internally) + rate_limit: 15 + ## /query endpoints have a limit of 15 requests/client/min + ## /meta_knowledge_graph endpoints have a limit of 30 requests/client/min + ## other endpoints don't have rate limits + x-translator: + infores: "infores:biothings-explorer" + biolink-version: 2.4.8 + component: ARA + team: + - Exploring Agent +servers: +## ITRB Production and Test are deployed manually, based on the staging instance +## ITRB CI / staging is basically deployed manually, from main branches +## - automatic for updates in bte-trapi-workspace main branch, but those rarely happen +## - we could technically control what branches are used (but right now we don't do this) +## non-ITRB dev: total manual control on updates (what branches of modules are used for updates) +- url: https://api.bte.ncats.io/v1 + description: Non-ITRB dev (primary internal use) + x-maturity: development +tags: +- name: 1.3.0 +- name: meta_knowledge_graph +- name: query +- name: asyncquery +- name: translator +- name: trapi +- name: biothings +## Note: BTE has custom behavior so DO NOT blindly copy-paste the TRAPI specs / schemas into the document below +## instead go through it and copy-paste in sections as-needed +## examples are using MyVariant-specific query +paths: + ## copied directly from TRAPI spec + /meta_knowledge_graph: + get: + tags: + - meta_knowledge_graph + summary: Meta knowledge graph representation of this TRAPI web service. + responses: + '200': + description: >- + Returns meta knowledge graph representation of this TRAPI web + service. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaKnowledgeGraph' + ## copied from /meta_knowledge_graph above and modified: BTE-specific endpoint + /smartapi/{smartapi_id}/meta_knowledge_graph: + get: + tags: + - meta_knowledge_graph + summary: TRAPI-compliant meta-knowledge-graph representation for an individual SmartAPI KP API (that has x-bte annotation) + parameters: + - description: >- + SmartAPI ID of an API with x-bte annotation. The easiest way to find these is to read the list of APIs BTE uses + https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js + in: path + name: smartapi_id + required: true + example: 09c8782d9f4027712e65b95424adba79 ## MyVariant + schema: + type: string + responses: + '200': + description: >- + Returns a TRAPI-compliant meta-knowledge-graph representation for an individual SmartAPI KP API (that has x-bte annotation) + content: + application/json: + schema: + $ref: '#/components/schemas/MetaKnowledgeGraph' + ## copied from /meta_knowledge_graph above and modified: BTE-specific endpoint + /team/{team_name}/meta_knowledge_graph: + get: + tags: + - meta_knowledge_graph + summary: TRAPI-compliant meta-knowledge-graph representation for one KP team's SmartAPI KP APIs (that have x-bte annotation) + parameters: + - description: >- + Translator Team Name. Current options: Service Provider, Multiomics Provider, Text Mining Provider. + The easiest way to find what KP APIs would be included under these teams is to read the list of APIs BTE uses + https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js. + Note that Service Provider endpoints are also advertised separately as a KP + http://smart-api.info/registry?q=36f82f05705c317bac17ddae3a0ea2f0 + in: path + name: team_name + required: true + example: "Service Provider" + schema: + type: string + enum: + - Multiomics Provider + - Text Mining Provider + - Service Provider + responses: + '200': + description: >- + Returns a TRAPI-compliant meta-knowledge-graph representation for one KP team's SmartAPI KP APIs (that have x-bte annotation) + content: + application/json: + schema: + $ref: '#/components/schemas/MetaKnowledgeGraph' + ## modified TRAPI spec: example and BTE-specific parameters, used by developers running local instances of BTE + /query: + post: + tags: + - query + summary: Initiate a TRAPI-format query to BTE (operating as an ARA) and wait to receive a Response + parameters: + - description: option to choose whether or not to enable caching + in: query + name: caching + required: false + schema: + type: boolean + - description: dryrun a query (logs the queries BTE will make) + in: query + name: dryrun + required: false + schema: + type: boolean + requestBody: + description: Query information to be submitted + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + ## should use MyVariant to answer this + example: + message: + query_graph: + nodes: + n0: + ids: + - "DBSNP:rs121913521" + categories: + - "biolink:SequenceVariant" + n1: + categories: + - "biolink:Disease" + edges: + e1: + subject: "n0" + object: "n1" + responses: + '200': + description: >- + OK. There may or may not be results. Note that some of the provided + identifiers may not have been recognized. + content: + application/json: + schema: + $ref: '#/components/schemas/Response' + '400': + description: >- + Bad request. The request is invalid according to this OpenAPI + schema OR a specific identifier is believed to be invalid somehow + (not just unrecognized). + content: + application/json: + schema: + type: string + '413': + description: >- + Payload too large. Indicates that batch size was over the limit + specified in x-trapi. + content: + application/json: + schema: + type: string + '429': + description: >- + Too many requests. Indicates that the client issued requests that + exceed the rate limit specified in x-trapi. + content: + application/json: + schema: + type: string + '500': + description: >- + Internal server error. + content: + application/json: + schema: + type: string + '501': + description: >- + Not implemented. + content: + application/json: + schema: + type: string + ## copied from /query above and modified: BTE-specific endpoint + /smartapi/{smartapi_id}/query: + post: + tags: + - query + summary: Query individual SmartAPI KP API (that has x-bte annotation) as a TRAPI KP API + parameters: + - description: >- + SmartAPI ID of an API with x-bte annotation. The easiest way to find these is to read the list of APIs BTE uses + https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js + in: path + name: smartapi_id + required: true + example: 09c8782d9f4027712e65b95424adba79 ## MyVariant + schema: + type: string + - description: option to choose whether or not to enable caching + in: query + name: caching + required: false + schema: + type: boolean + - description: dryrun a query (logs the queries BTE will make) + in: query + name: dryrun + required: false + schema: + type: boolean + requestBody: + description: Query information to be submitted + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + ## should use MyVariant to answer this + example: + message: + query_graph: + nodes: + n0: + ids: + - "DBSNP:rs121913521" + categories: + - "biolink:SequenceVariant" + n1: + categories: + - "biolink:Disease" + edges: + e1: + subject: "n0" + object: "n1" + responses: + '200': + description: >- + OK. There may or may not be results. Note that some of the provided + identifiers may not have been recognized. + content: + application/json: + schema: + $ref: '#/components/schemas/Response' + '400': + description: >- + Bad request. The request is invalid according to this OpenAPI + schema OR a specific identifier is believed to be invalid somehow + (not just unrecognized). + content: + application/json: + schema: + type: string + '413': + description: >- + Payload too large. Indicates that batch size was over the limit + specified in x-trapi. + content: + application/json: + schema: + type: string + '429': + description: >- + Too many requests. Indicates that the client issued requests that + exceed the rate limit specified in x-trapi. + content: + application/json: + schema: + type: string + '500': + description: >- + Internal server error. + content: + application/json: + schema: + type: string + '501': + description: >- + Not implemented. + content: + application/json: + schema: + type: string + ## copied from /query above and modified: BTE-specific endpoint + /team/{team_name}/query: + post: + tags: + - query + summary: >- + Query an individual Translator team's SMARTAPI KP APIs (that have x-bte annotation) as an individual TRAPI + service by specifying the team name + parameters: + - description: >- + Translator Team Name. Current options: Service Provider, Multiomics Provider, Text Mining Provider. + The easiest way to find what KP APIs would be included under these teams is to read the list of APIs BTE uses + https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js. + Note that Service Provider endpoints are also advertised separately as a KP + http://smart-api.info/registry?q=36f82f05705c317bac17ddae3a0ea2f0 + in: path + name: team_name + required: true + example: "Service Provider" + schema: + type: string + enum: + - Multiomics Provider + - Text Mining Provider + - Service Provider + - description: option to choose whether or not to enable caching + in: query + name: caching + required: false + schema: + type: boolean + - description: dryrun a query (logs the queries BTE will make) + in: query + name: dryrun + required: false + schema: + type: boolean + requestBody: + description: Query information to be submitted + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + ## should use MyVariant to answer this + example: + message: + query_graph: + nodes: + n0: + ids: + - "DBSNP:rs121913521" + categories: + - "biolink:SequenceVariant" + n1: + categories: + - "biolink:Disease" + edges: + e1: + subject: "n0" + object: "n1" + responses: + '200': + description: >- + OK. There may or may not be results. Note that some of the provided + identifiers may not have been recognized. + content: + application/json: + schema: + $ref: '#/components/schemas/Response' + '400': + description: >- + Bad request. The request is invalid according to this OpenAPI + schema OR a specific identifier is believed to be invalid somehow + (not just unrecognized). + content: + application/json: + schema: + type: string + '413': + description: >- + Payload too large. Indicates that batch size was over the limit + specified in x-trapi. + content: + application/json: + schema: + type: string + '429': + description: >- + Too many requests. Indicates that the client issued requests that + exceed the rate limit specified in x-trapi. + content: + application/json: + schema: + type: string + '500': + description: >- + Internal server error. + content: + application/json: + schema: + type: string + '501': + description: >- + Not implemented. + content: + application/json: + schema: + type: string + ## not TRAPI spec: BTE-specific endpoint related to asyncquery + /check_query_status/{id}: + ## moved because smartapi-editor gave alert that a non-existent post endpoint wouldn't know what {id} is + parameters: + - description: job-id + in: path + name: id + required: true + ## Cache refreshing means this will be changing pretty often, so not including an example + schema: + type: string + get: + tags: + - asyncquery + summary: >- + This endpoint should be used when a Query was sent to BTE through an /asyncquery + endpoint without a callback property: BTE then handled it in a polling manner and + provided a job id. The job id can be used here to check the status or retrieve + the Response. + parameters: + - description: option to override original query log level + in: query + name: log_level + required: false + schema: + type: string + description: >- + Logging level. The order of priority is ERROR, WARNING, INFO, DEBUG. BTE will return all logs at the + specified level and those at higher priority levels + enum: + - ERROR + - WARNING + - INFO + - DEBUG + responses: + '200': + description: Returns status. If successfully completed, it will return a TRAPI Response object under the field returnvalue + content: + application/json: + schema: + type: object + required: + - id + - state + properties: + id: + description: the job-id + type: string + state: + description: the status of the job + reason: + description: when the state is 'failed', this field states a reason for the failure + type: string + returnvalue: + ## returnvalue.response is where the TRAPI Response is + description: >- + When the state is 'completed', this will contain the TRAPI Response object. Note + that BTE might return an error, no results, etc as a Response... + type: object + properties: + response: + $ref: '#/components/schemas/Response' + ## modified TRAPI spec: summary sections tell users that AsyncQuery schema was changed to make callback optional + /asyncquery: + post: + tags: + - asyncquery + summary: >- + Initiate a query that will be handled in an asynchronous manner (there is a + queue and queries will be executed in the order that they enter the queue). + For BTE, it is optional to have a callback property in the request-body. If + the callback property is not included, BTE will handle the query in a polling + manner: it will provide a job-id that can be used to check the status or retrieve + the Response using BTE's /v1/check_query_status/{id} endpoint. + parameters: + - description: option to choose whether or not to enable caching + in: query + name: caching + required: false + schema: + type: boolean + - description: dryrun a query (logs the queries BTE will make) + in: query + name: dryrun + required: false + schema: + type: boolean + requestBody: + description: Query information to be submitted + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AsyncQuery' + ## should use MyVariant to answer this + example: + message: + query_graph: + nodes: + n0: + ids: + - "DBSNP:rs121913521" + categories: + - "biolink:SequenceVariant" + n1: + categories: + - "biolink:Disease" + edges: + e1: + subject: "n0" + object: "n1" + responses: + '200': + description: >- + The query is accepted for processing. The behavior will depend on whether + the callback property is included. If the callback property is included, + the Response will be sent to the callback url when complete. If the callback + property is not included, BTE will handle the query in a polling manner: it + will provide a job-id that can be used to check the status or retrieve + the Response using BTE's /v1/check_query_status/{id} endpoint. + content: + application/json: + schema: + type: string + '400': + description: >- + Bad request. The request is invalid according to this OpenAPI + schema OR a specific identifier is believed to be invalid somehow + (not just unrecognized). + content: + application/json: + schema: + type: string + '413': + description: >- + Payload too large. Indicates that batch size was over the limit + specified in x-trapi. + content: + application/json: + schema: + type: string + '429': + description: >- + Too many requests. Indicates that the client issued requests that + exceed the rate limit specified in x-trapi. + content: + application/json: + schema: + type: string + '500': + description: >- + Internal server error. + content: + application/json: + schema: + type: string + '501': + description: >- + Not implemented. + content: + application/json: + schema: + type: string + ## copied from /asyncquery above and modified: BTE-specific endpoint + /smartapi/{smartapi_id}/asyncquery: + post: + tags: + - asyncquery + summary: >- + This endpoint is for asynchronously querying an individual SmartAPI KP API (that has x-bte annotation) + as a TRAPI KP API. + + Initiate a query that will be handled in an asynchronous manner (there is a + queue and queries will be executed in the order that they enter the queue). + For BTE, it is optional to have a callback property in the request-body. If + the callback property is not included, BTE will handle the query in a polling + manner: it will provide a job-id that can be used to check the status or retrieve + the Response using BTE's /v1/check_query_status/{id} endpoint. + parameters: + - description: >- + SmartAPI ID of an API with x-bte annotation. The easiest way to find these is to read the list of APIs BTE uses + https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js + in: path + name: smartapi_id + required: true + example: 09c8782d9f4027712e65b95424adba79 ## MyVariant + schema: + type: string + - description: option to choose whether or not to enable caching + in: query + name: caching + required: false + schema: + type: boolean + - description: dryrun a query (logs the queries BTE will make) + in: query + name: dryrun + required: false + schema: + type: boolean + requestBody: + description: Query information to be submitted + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AsyncQuery' + ## should use MyVariant to answer this + example: + message: + query_graph: + nodes: + n0: + ids: + - "DBSNP:rs121913521" + categories: + - "biolink:SequenceVariant" + n1: + categories: + - "biolink:Disease" + edges: + e1: + subject: "n0" + object: "n1" + responses: + '200': + description: >- + The query is accepted for processing. The behavior will depend on whether + the callback property is included. If the callback property is included, + the Response will be sent to the callback url when complete. If the callback + property is not included, BTE will handle the query in a polling manner: it + will provide a job-id that can be used to check the status or retrieve + the Response using BTE's /v1/check_query_status/{id} endpoint. + content: + application/json: + schema: + type: string + '400': + description: >- + Bad request. The request is invalid according to this OpenAPI + schema OR a specific identifier is believed to be invalid somehow + (not just unrecognized). + content: + application/json: + schema: + type: string + '413': + description: >- + Payload too large. Indicates that batch size was over the limit + specified in x-trapi. + content: + application/json: + schema: + type: string + '429': + description: >- + Too many requests. Indicates that the client issued requests that + exceed the rate limit specified in x-trapi. + content: + application/json: + schema: + type: string + '500': + description: >- + Internal server error. + content: + application/json: + schema: + type: string + '501': + description: >- + Not implemented. + content: + application/json: + schema: + type: string + ## copied from /asyncquery above and modified: BTE-specific endpoint + /team/{team_name}/asyncquery: + post: + tags: + - asyncquery + summary: >- + This endpoint is for asynchronously querying an individual Translator team's SMARTAPI KP APIs (that have x-bte annotation) + as an individual TRAPI service by specifying the team name. + + Initiate a query that will be handled in an asynchronous manner (there is a + queue and queries will be executed in the order that they enter the queue). + For BTE, it is optional to have a callback property in the request-body. If + the callback property is not included, BTE will handle the query in a polling + manner: it will provide a job-id that can be used to check the status or retrieve + the Response using BTE's /v1/check_query_status/{id} endpoint. + parameters: + - description: >- + Translator Team Name. Current options: Service Provider, Multiomics Provider, Text Mining Provider. + The easiest way to find what KP APIs would be included under these teams is to read the list of APIs BTE uses + https://github.com/biothings/BioThings_Explorer_TRAPI/blob/main/src/config/apis.js. + Note that Service Provider endpoints are also advertised separately as a KP + http://smart-api.info/registry?q=36f82f05705c317bac17ddae3a0ea2f0 + in: path + name: team_name + required: true + example: "Service Provider" + schema: + type: string + enum: + - Multiomics Provider + - Text Mining Provider + - Service Provider + - description: option to choose whether or not to enable caching + in: query + name: caching + required: false + schema: + type: boolean + - description: dryrun a query (logs the queries BTE will make) + in: query + name: dryrun + required: false + schema: + type: boolean + requestBody: + description: Query information to be submitted + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AsyncQuery' + ## should use MyVariant to answer this + example: + message: + query_graph: + nodes: + n0: + ids: + - "DBSNP:rs121913521" + categories: + - "biolink:SequenceVariant" + n1: + categories: + - "biolink:Disease" + edges: + e1: + subject: "n0" + object: "n1" + responses: + '200': + description: >- + The query is accepted for processing. The behavior will depend on whether + the callback property is included. If the callback property is included, + the Response will be sent to the callback url when complete. If the callback + property is not included, BTE will handle the query in a polling manner: it + will provide a job-id that can be used to check the status or retrieve + the Response using BTE's /v1/check_query_status/{id} endpoint. + content: + application/json: + schema: + type: string + '400': + description: >- + Bad request. The request is invalid according to this OpenAPI + schema OR a specific identifier is believed to be invalid somehow + (not just unrecognized). + content: + application/json: + schema: + type: string + '413': + description: >- + Payload too large. Indicates that batch size was over the limit + specified in x-trapi. + content: + application/json: + schema: + type: string + '429': + description: >- + Too many requests. Indicates that the client issued requests that + exceed the rate limit specified in x-trapi. + content: + application/json: + schema: + type: string + '500': + description: >- + Internal server error. + content: + application/json: + schema: + type: string + '501': + description: >- + Not implemented. + content: + application/json: + schema: + type: string +components: + ## look for comments to see parts that have been modified for BTE + ## - Query: comment out workflow.allOf section since the $ref breaks execution of + ## BTE's api-schema-builder/openapi-validator-middleware + ## - AsyncQuery: callback property not required (commented it out of the 'required' field), + ## comment out workflow.allOf section + ## - Response: comment out workflow.allOf section + ## - QEdge: set additionalProperties to false (see comments below for details) + ## - Attribute: comment out properties.attributes.items since the self-$ref breaks execution of + ## BTE's api-schema-builder/openapi-validator-middleware + schemas: + Query: + description: >- + 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. + x-body-name: request_body + type: object + properties: + message: + $ref: '#/components/schemas/Message' + description: >- + 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. + log_level: + description: The least critical level of logs to return + allOf: + - $ref: '#/components/schemas/LogLevel' + nullable: true + workflow: + description: List of workflow steps to be executed. + # allOf: + # - $ref: http://standards.ncats.io/workflow/1.0.0/schema + nullable: true + submitter: + type: string + description: >- + Any string for self-identifying the submitter of a query. The + purpose of this optional field is to aid in the tracking of + the source of queries for development and issue resolution. + nullable: true + additionalProperties: true + required: + - message + AsyncQuery: + description: >- + The AsyncQuery class is effectively the same as the Query class but + it requires a callback property. + x-body-name: request_body + type: object + properties: + callback: + type: string + format: uri + pattern: ^https?:// + description: >- + 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. + message: + $ref: '#/components/schemas/Message' + description: >- + 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. + log_level: + description: The least critical level of logs to return + allOf: + - $ref: '#/components/schemas/LogLevel' + nullable: true + workflow: + description: List of workflow steps to be executed. + # allOf: + # - $ref: http://standards.ncats.io/workflow/1.0.0/schema + nullable: true + submitter: + type: string + description: >- + Any string for self-identifying the submitter of a query. The + purpose of this optional field is to aid in the tracking of + the source of queries for development and issue resolution. + nullable: true + additionalProperties: true + required: + ## BTE does not require the callback property, see the asyncquery + ## endpoint summary and 200 response description + # - callback + - message + Response: + type: object + description: >- + 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. + properties: + message: + description: >- + Contains the knowledge of the response (query graph, knowledge + graph, and results). + $ref: '#/components/schemas/Message' + status: + description: >- + One of a standardized set of short codes, + e.g. Success, QueryNotTraversable, KPsNotAvailable + type: string + example: Success + nullable: true + description: + description: A brief human-readable description of the outcome + type: string + example: Success. 42 results found. + nullable: true + logs: + description: >- + Log entries containing errors, warnings, debugging information, etc + type: array + items: + $ref: '#/components/schemas/LogEntry' + nullable: true + workflow: + description: List of workflow steps that were executed. + # allOf: + # - $ref: http://standards.ncats.io/workflow/1.0.0/schema + nullable: true + additionalProperties: true + required: + - message + Message: + description: >- + 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. + type: object + properties: + results: + description: >- + List of all returned Result objects for the query posed. + The list SHOULD NOT be assumed to be ordered. The 'score' property, + if present, MAY be used to infer result rankings. + type: array + items: + $ref: '#/components/schemas/Result' + nullable: true + query_graph: + description: >- + QueryGraph object that contains a serialization of a query in the + form of a graph + allOf: + - $ref: '#/components/schemas/QueryGraph' + nullable: true + knowledge_graph: + description: >- + KnowledgeGraph object that contains lists of nodes and edges + in the thought graph corresponding to the message + allOf: + - $ref: '#/components/schemas/KnowledgeGraph' + nullable: true + additionalProperties: false + LogEntry: + description: >- + 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. + type: object + properties: + timestamp: + type: string + format: date-time + description: Timestamp in ISO 8601 format + example: '2020-09-03T18:13:49+00:00' + nullable: true + level: + allOf: + - $ref: '#/components/schemas/LogLevel' + nullable: true + code: + type: string + description: >- + One of a standardized set of short codes + e.g. QueryNotTraversable, KPNotAvailable, KPResponseMalformed + nullable: true + message: + type: string + description: A human-readable log message + nullable: true + additionalProperties: true + LogLevel: + type: string + description: Logging level + enum: + - ERROR + - WARNING + - INFO + - DEBUG + Result: + type: object + description: >- + 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 an EdgeBindings object (list of + query graph edge to knowledge graph edge mappings). + properties: + node_bindings: + type: object + description: >- + 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). This value is an + array of NodeBindings since a given query node may have multiple + knowledge graph Node bindings in the result. + additionalProperties: + type: array + items: + $ref: '#/components/schemas/NodeBinding' + edge_bindings: + type: object + description: >- + The dictionary of Input Query Graph to Result Knowledge Graph edge + bindings where the dictionary keys are the key identifiers of the + Query Graph edges and the associated values of those keys are + instances of EdgeBinding schema type (see below). This value is an + array of EdgeBindings since a given query edge may resolve to + multiple knowledge graph edges in the result. + additionalProperties: + type: array + items: + $ref: '#/components/schemas/EdgeBinding' + score: + type: number + format: float + example: 163.233 + description: >- + A numerical score associated with this result indicating the + relevance or confidence of this result relative to others in the + returned set. Higher MUST be better. + nullable: true + additionalProperties: true + required: + - node_bindings + - edge_bindings + NodeBinding: + type: object + description: >- + An instance of NodeBinding is a single KnowledgeGraph Node mapping, + identified by the corresponding 'id' object key identifier of the + Node within the Knowledge Graph. Instances of NodeBinding may + include extra annotation in the form of additional properties. + (such annotation is not yet fully standardized). + properties: + id: + $ref: '#/components/schemas/CURIE' + description: >- + The CURIE of a Node within the Knowledge Graph. + query_id: + $ref: '#/components/schemas/CURIE' + description: >- + An optional property to provide the CURIE in the QueryGraph to + which this binding applies. If the bound QNode does not have an + an 'id' property or if it is empty, then this query_id MUST be + null or absent. If the bound QNode has one or more CURIEs + as an 'id' and this NodeBinding's 'id' refers to a QNode 'id' + in a manner where the CURIEs are different (typically due to + the NodeBinding.id being a descendant of a QNode.id), then + this query_id MUST be provided. In other cases, there is no + ambiguity, and this query_id SHOULD NOT be provided. + attributes: + type: array + description: >- + A list of attributes providing further information about the + node binding. This is not intended for capturing node attributes + and should only be used for properties that vary from result to + result. + items: + $ref: '#/components/schemas/Attribute' + nullable: true + additionalProperties: true + required: + - id + EdgeBinding: + type: object + description: >- + A instance of EdgeBinding is a single KnowledgeGraph Edge mapping, + 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). + properties: + id: + type: string + description: The key identifier of a specific KnowledgeGraph Edge. + attributes: + type: array + description: >- + A list of attributes providing further information about the + edge binding. This is not intended for capturing edge attributes + and should only be used for properties that vary from result to + result. + items: + $ref: '#/components/schemas/Attribute' + nullable: true + additionalProperties: true + required: + - id + KnowledgeGraph: + type: object + description: >- + 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. + properties: + nodes: + type: object + description: >- + Dictionary of Node instances used in the KnowledgeGraph, + referenced elsewhere in the TRAPI output by the dictionary key. + additionalProperties: + $ref: '#/components/schemas/Node' + edges: + type: object + description: >- + Dictionary of Edge instances used in the KnowledgeGraph, + referenced elsewhere in the TRAPI output by the dictionary key. + additionalProperties: + $ref: '#/components/schemas/Edge' + additionalProperties: true + required: + - nodes + - edges + QueryGraph: + type: object + description: >- + 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. + properties: + nodes: + type: object + description: >- + The node specifications. The keys of this map are unique node + identifiers and the corresponding values include the constraints + on bound nodes. + additionalProperties: + $ref: '#/components/schemas/QNode' + edges: + type: object + description: >- + 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. + additionalProperties: + $ref: '#/components/schemas/QEdge' + additionalProperties: true + required: + - nodes + - edges + QNode: + type: object + description: 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. + properties: + ids: + type: array + items: + $ref: '#/components/schemas/CURIE' + minItems: 1 + example: [OMIM:603903] + description: CURIE identifier for this node + nullable: true + categories: + type: array + items: + $ref: '#/components/schemas/BiolinkEntity' + minItems: 1 + nullable: true + is_set: + type: boolean + description: >- + Boolean that if set to true, indicates that this QNode MAY have + multiple KnowledgeGraph Nodes bound to it within each Result. + The nodes in a set should be considered as a set of independent + nodes, rather than a set of dependent nodes, i.e., the answer + would still be valid if the nodes in the set were instead returned + individually. Multiple QNodes may have is_set=True. If a QNode + (n1) with is_set=True is connected to a QNode (n2) with + is_set=False, each n1 must be connected to n2. If a QNode (n1) + with is_set=True is connected to a QNode (n2) with is_set=True, + each n1 must be connected to at least one n2. + default: false + constraints: + type: array + description: >- + A list of contraints applied to a query node. + If there are multiple items, they must all be true (equivalent + to AND) + items: + $ref: '#/components/schemas/AttributeConstraint' + default: [] + additionalProperties: true + QEdge: + type: object + description: >- + An edge in the QueryGraph used as an 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. + properties: + knowledge_type: + description: >- + Indicates the type of knowledge that the client wants from the + server between the subject and object. If the value is + 'lookup', then the client wants direct lookup information from + knowledge sources. If the value is 'inferred', then the client + wants the server to get creative and connect the subject and + object in more speculative and non-direct-lookup ways. If this + property is absent or null, it MUST be assumed to mean + 'lookup'. This feature is currently experimental and may be + further extended in the future. + example: lookup + nullable: true + type: string + predicates: + type: array + items: + $ref: '#/components/schemas/BiolinkPredicate' + minItems: 1 + nullable: true + subject: + type: string + example: https://omim.org/entry/603903 + description: >- + Corresponds to the map key identifier of the + subject concept node anchoring the query filter + pattern for the query relationship edge. + object: + type: string + example: https://www.uniprot.org/uniprot/P00738 + description: >- + Corresponds to the map key identifier of the + object concept node anchoring the query filter + pattern for the query relationship edge. + attribute_constraints: + type: array + description: >- + A list of attribute contraints applied to a query edge. + If there are multiple items, they must all be true (equivalent + to AND) + items: + $ref: '#/components/schemas/AttributeConstraint' + default: [] + qualifier_constraints: + type: array + description: >- + A list of QualifierConstraints that provide nuance to the QEdge. + If multiple QualifierConstraints 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 qualifier_constraints MUST NOT be specified + because these complex use cases are not supported at this time. + items: + $ref: '#/components/schemas/QualifierConstraint' + default: [] + ## changing from true to false, so BTE will reject queries that have these additional properties + ## BTE doesn't use these and this is the easiest way to recognize when they are there and respond to that + ## Related to Implementation rules https://github.com/NCATSTranslator/ReasonerAPI/blob/1.3/ImplementationRules.md#qedgexxxxx + additionalProperties: false + required: + - subject + - object + Node: + type: object + description: >- + A node in the KnowledgeGraph which represents some biomedical + concept. Nodes are identified by the keys in the KnowledgeGraph + Node mapping. + properties: + name: + type: string + example: Haptoglobin + description: Formal name of the entity + nullable: true + categories: + type: array + items: + $ref: '#/components/schemas/BiolinkEntity' + nullable: true + attributes: + type: array + description: A list of attributes describing the node + items: + $ref: '#/components/schemas/Attribute' + nullable: true + additionalProperties: false + Attribute: + type: object + description: >- + 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). + properties: + attribute_type_id: + $ref: '#/components/schemas/CURIE' + description: >- + The 'key' of the attribute object, holding a CURIE of an ontology + property defining the attribute (preferably the CURIE of a + Biolink association slot). This property captures the relationship + asserted to hold between the value of the attribute, and the node + or edge from which it hangs. For example, that a value of + '0.000153' represents a p-value supporting an edge, or that + a value of 'ChEMBL' represents the original source of the knowledge + expressed in the edge. + example: biolink:synonym + original_attribute_name: + type: string + description: >- + The term used by the original source of an attribute to describe + the meaning or significance of the value it captures. This may be + a column name in a source tsv file, or a key in a source json + document for the field in the data that held the attribute's + value. Capturing this information where possible lets us preserve + what the original source said. Note that the data type is string' + but the contents of the field could also be a CURIE of a third + party ontology term. + example: p-value + nullable: true + value: + description: >- + Value of the attribute. May be any data type, including a list. + example: 0.000153 + value_type_id: + allOf: + - $ref: '#/components/schemas/CURIE' + description: >- + CURIE describing the semantic type of an attribute's value. Use + a Biolink class if possible, otherwise a term from an external + ontology. If a suitable CURIE/identifier does not exist, enter a + descriptive phrase here and submit the new type for consideration + by the appropriate authority. + example: EDAM:data_1187 + nullable: true + attribute_source: + type: string + description: >- + The source of the core assertion made by the key-value pair of an + attribute object. Use a CURIE or namespace designator for this + resource where possible. + example: UniProtKB + nullable: true + value_url: + type: string + description: >- + Human-consumable URL linking to a web document that provides + additional information about an attribute's value (not the node + or the edge fom which it hangs). + example: https://pubmed.ncbi.nlm.nih.gov/32529952 + nullable: true + description: + type: string + description: >- + Human-readable description for the attribute and its value. + example: Assertion Authored By Dr. Trans L. Ator + nullable: true + attributes: + type: array + description: >- + A list of attributes providing further information about the + parent attribute (for example to provide provenance + information about the parent attribute). + # items: + # $ref: '#/components/schemas/Attribute' + nullable: true + required: + - attribute_type_id + - value + additionalProperties: false + Edge: + type: object + description: >- + 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. + properties: + predicate: + allOf: + - $ref: '#/components/schemas/BiolinkPredicate' + nullable: true + subject: + $ref: '#/components/schemas/CURIE' + example: OMIM:603903 + description: >- + Corresponds to the map key CURIE of the + subject concept node of this relationship edge. + object: + $ref: '#/components/schemas/CURIE' + example: UniProtKB:P00738 + description: >- + Corresponds to the map key CURIE of the + object concept node of this relationship edge. + attributes: + type: array + description: A list of additional attributes for this edge + items: + $ref: '#/components/schemas/Attribute' + nullable: true + qualifiers: + type: array + description: >- + A set of Qualifiers that act together to add nuance + or detail to the statement expressed in an Edge. + items: + $ref: '#/components/schemas/Qualifier' + nullable: true + additionalProperties: false + required: + - subject + - object + Qualifier: + additionalProperties: false + description: >- + An additional nuance attached to an assertion + type: object + properties: + qualifier_type_id: + type: string + description: >- + The category of the qualifier, drawn from a hierarchy of qualifier + slots in the Biolink model (e.g. subject_aspect, subject_direction, + object_aspect, object_direction, etc). + example: subject_aspect + nullable: false + qualifier_value: + type: string + description: >- + 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 'subject_aspect', etc). + example: expression + nullable: false + required: + - qualifier_type_id + - qualifier_value + QualifierConstraint: + additionalProperties: false + description: >- + Defines a query constraint based on the + qualifier_types and qualifier_values of a set of + Qualifiers attached to an edge. For example, it 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 "object_aspect" with + a qualifier_value of "expression". + properties: + qualifier_set: + type: array + description: >- + A set of Qualifiers that serves to add nuance to a query, + by constraining allowed values held by Qualifiers + on queried Edges. + items: + $ref: '#/components/schemas/Qualifier' + nullable: false + required: + - qualifier_set + type: object + BiolinkEntity: + description: >- + 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. + type: string + pattern: ^biolink:[A-Z][a-zA-Z]*$ + externalDocs: + description: Biolink model entities + url: https://biolink.github.io/biolink-model/docs/NamedThing.html + example: biolink:PhenotypicFeature + BiolinkPredicate: + description: >- + 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. + type: string + pattern: ^biolink:[a-z][a-z_]*$ + externalDocs: + description: Biolink model predicates + url: https://biolink.github.io/biolink-model/docs/related_to.html + example: biolink:interacts_with + CURIE: + type: string + description: >- + 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. + externalDocs: + url: https://www.w3.org/TR/2010/NOTE-curie-20101216/ + MetaKnowledgeGraph: + type: object + description: >- + 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. + properties: + nodes: + type: object + description: >- + 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. + additionalProperties: + $ref: '#/components/schemas/MetaNode' + edges: + type: array + description: >- + 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. + items: + $ref: '#/components/schemas/MetaEdge' + required: + - nodes + - edges + MetaNode: + type: object + description: >- + Description of a node category provided by this TRAPI web service. + properties: + id_prefixes: + type: array + description: >- + List of CURIE prefixes for the node category that this TRAPI web + service understands and accepts on the input. + items: + type: string + minItems: 1 + example: [CHEMBL.COMPOUND, INCHIKEY] + attributes: + type: array + description: >- + Node attributes provided by this TRAPI web service. + items: + $ref: '#/components/schemas/MetaAttribute' + nullable: true + required: + - id_prefixes + additionalProperties: false + MetaEdge: + type: object + description: >- + Edge in a meta knowledge map describing relationship between a subject + Biolink class and an object Biolink class. + properties: + subject: + $ref: '#/components/schemas/BiolinkEntity' + description: >- + Subject node category of this relationship edge. + example: biolink:ChemicalEntity + predicate: + $ref: '#/components/schemas/BiolinkPredicate' + description: >- + Biolink relationship between the subject and object categories. + example: biolink:affects + object: + $ref: '#/components/schemas/BiolinkEntity' + description: >- + Object node category of this relationship edge. + example: biolink:Protein + knowledge_types: + description: >- + A list of knowledge_types that are supported by the service. + If the knowledge_types is null, this means that only 'lookup' + is supported. Currently allowed values are 'lookup' or 'inferred'. + items: + type: string + minItems: 1 + nullable: true + type: array + attributes: + type: array + description: >- + Edge attributes provided by this TRAPI web service. + items: + $ref: '#/components/schemas/MetaAttribute' + nullable: true + required: + - subject + - predicate + - object + additionalProperties: false + MetaAttribute: + type: object + properties: + attribute_type_id: + $ref: '#/components/schemas/CURIE' + description: >- + Type of an attribute provided by this TRAPI web service + (preferably the CURIE of a Biolink association slot) + example: biolink:p_value + attribute_source: + type: string + description: >- + Source of an attribute provided by this TRAPI web service. + example: infores:chembl + nullable: true + original_attribute_names: + type: array + items: + type: string + description: >- + Names of an the attribute as provided by the source. + nullable: true + minItems: 1 + constraint_use: + type: boolean + description: >- + Indicates whether this attribute can be used as a query + constraint. + default: false + constraint_name: + type: string + description: >- + Human-readable name or label for the constraint concept. + Required whenever constraint_use is true. + example: p-value + nullable: true + required: + - attribute_type_id + AttributeConstraint: + type: object + description: >- + Generic query constraint for a query node or query edge + properties: + id: + allOf: + - $ref: '#/components/schemas/CURIE' + description: >- + CURIE of the concept being constrained. For properties + defined by the Biolink model this SHOULD be a biolink CURIE. + otherwise, if possible, from the EDAM ontology. If a suitable + CURIE does not exist, enter a descriptive phrase here and + submit the new type for consideration by the appropriate + authority. + example: EDAM:data_0844 + name: + type: string + description: >- + Human-readable name or label for the constraint concept. + If appropriate, it SHOULD be the term name of the CURIE used + as the 'id'. This is redundant but required for human + readability. + example: molecular mass + not: + type: boolean + default: false + operator: + type: string + description: >- + Relationship between the database value and the constraint value + for the specified id. The operators ==, >, and < mean + is equal to, is greater than, and is less than, + respectively. The 'matches' operator indicates that the value + is a regular expression to be evaluated. If value is a list type, + then at least one evaluation must be true (equivalent to OR). + This means that the == operator with a list acts like a SQL 'IN' + clause. If the value of the compared attribute is a list, then + comparisons are performed between each of the constraint values + and each of the attribute values, and any one true evaluation + counts as an overall true (e.g., [1,2,3] == [6,7,2] is true). + The == operator is therefore a broad interpretation of inclusion. + The '===' operator requires that the constraint value and + the attribute value be the same data type, length, + content, and order (e.g. only [1,2,3] === [1,2,3]). + The 'not' property negates the operator such that not + and == means 'not equal to' (or 'not in' for a list), and not > + means <=, and not < means >=, not matches means does not + match, and not === means the match between the constraint + and attribute values are not exact. + The '==' operator SHOULD NOT be used in a manner that + describes an "is a" subclass relationship for the parent QNode. + enum: + - == + - '>' + - < + - matches + - === + value: + example: 57.0 + description: >- + Value of the attribute. May be any data type, including a list. + If the value is a list and there are multiple items, at least one + comparison must be true (equivalent to OR) unless the '===' + operator is used. If 'value' is of data + type 'object', the keys of the object MAY be treated as a list. + A 'list' data type paired with the '>' or '<' operators will + encode extraneous comparisons, but this is permitted as it is in + SQL and other languages. + unit_id: + example: UO:0000222 + description: >- + 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. + nullable: true + unit_name: + example: kilodalton + description: >- + 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. + nullable: true + required: + - name + - id + - operator + - value + additionalProperties: false