translator_interchange_0.9.0.yaml

openapi: 3.0.1
info:
  description: Compare Translator answers.
  version: 0.9.0
  title: Answer comparison tool.
  contact:
    email: scox@renci.org
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
externalDocs:
  description: Documentation for the comparing NCATS Biomedical Translator Reasoner answers.
  url: 'https://github.com/NCATS-Tangerine/NCATS-ReasonerStdAPI-diff'
components:
  schemas:
    FeedbackResponse:
      type: object
      properties:
        detail:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
    Ratings:
      type: object
      properties:
        ratings:
          type: array
          items:
            $ref: '#/components/schemas/Rating'
        n_ratings:
          type: integer
    Rating:
      type: object
      properties:
        description:
          type: string
        rating_id:
          type: integer
        name:
          type: string
        score:
          type: number
        tag:
          type: string
    ExpertiseLevels:
      type: object
      properties:
        expertise_levels:
          type: array
          items:
            $ref: '#/components/schemas/ExpertiseLevel'
        n_expertise_levels:
          type: integer
    ExpertiseLevel:
      type: object
      properties:
        description:
          type: string
        expertise_level_id:
          type: integer
        name:
          type: string
        score:
          type: number
        tag:
          type: string
    Query:
      type: object
      properties:
        bypass_cache:
          type: string
          example: 'true'
          description: >-
            Set to true in order to bypass any possible cached message and try to
            answer the query over again
        asynchronous:
          type: string
          example: 'false'
          description: >-
            Set to true in order to receive an incomplete message_id if the query
            will take a while. Client can then periodically request that
            message_id for a status update and eventual complete message
        max_results:
          type: integer
          example: 100
          description: Maximum number of individual results to return
        page_size:
          type: integer
          example: 20
          description: Split the results into pages with this number of results each
        page_number:
          type: integer
          example: 1
          description: >-
            Page number of results when the number of results exceeds the
            page_size
        reasoner_ids:
          type: array
          example:
            - RTX
            - Robokop
          description: List of reasoners to consult for the query
          items:
            type: string
        query_message:
          type: object
          description: Message object that represents the query to be answered
          items:
            $ref: '#/components/schemas/Message'
        previous_message_processing_plan:
          type: object
          description: >-
            Container for one or more Message objects or identifiers for one or
            more Messages along with a processing plan for how those messages
            should be processed and returned
          items:
            $ref: '#/components/schemas/PreviousMessageProcessingPlan'
      additionalProperties: true
    PreviousMessageProcessingPlan:
      type: object
      properties:
        previous_message_uris:
          type: array
          example:
            - 'https://rtx.ncats.io/api/rtx/v1/message/300'
          description: List of URIs for Message objects to fetch and process
          items:
            type: string
        previous_messages:
          type: array
          description: List of Message objects to process
          items:
            $ref: '#/components/schemas/Message'
        processing_actions:
          type: array
          example:
            - mod45filter
            - redirect2RTX
          description: >-
            List of order-dependent actions to guide what happens with the Message
            object(s)
          items:
            type: string
        options:
          type: object
          example:
            topNMostFrequent: 1
          description: >-
            Dict of options that apply during processing in an order independent
            fashion
          additionalProperties: true
      additionalProperties: true
    Message:
      type: object
      properties:
        context:
          type: string
          example: 'https://rtx.ncats.io/ns/translator.jsonld'
          description: JSON-LD context URI
        type:
          type: string
          example: translator_reasoner_message
          description: Entity type of this message
        id:
          type: string
          example: 'https://rtx.ncats.io/api/rtx/v1/message/123'
          description: URI for this message
        reasoner_id:
          type: string
          example: reasoner
          description: >-
            Identifier string of the reasoner that provided this message (one of
            RTX, Robokop, Indigo, Integrator, etc.)
        tool_version:
          type: string
          example: RTX 0.5.0
          description: Version label of the tool that generated this message
        schema_version:
          type: string
          example: 0.9.0
          description: Version label of this JSON-LD schema
        datetime:
          type: string
          example: '2018-01-09 12:34:45'
          description: Datetime string for the time that this message was generated
        n_results:
          type: integer
          example: 42
          description: >-
            Total number of results from the query (which may be less than what is
            returned if limits were placed on the number of results to return)
        message_code:
          type: string
          example: OK
          description: >-
            Set to OK for success, or some other short string to indicate and
            error (e.g., KGUnavailable, TermNotFound, etc.)
        code_description:
          type: string
          example: 9 results found
          description: >-
            Extended description denoting the success or mode of failure in the
            generation of the message
        table_column_names:
          type: array
          example:
            - chemical_substance.name
            - chemical_substance.id
          description: List of column names that corresponds to the row_data for each result
          items:
            type: string
        original_question:
          type: string
          example: what proteins are affected by sickle cell anemia
          description: The original question text typed in by the user
        restated_question:
          type: string
          example: Which proteins are affected by sickle cell anemia?
          description: >-
            A precise restatement of the question, as understood by the
            Translator, for which the answer applies. The user should verify that
            the restated question matches the intent of their original question
            (it might not).
        query_type_id:
          type: string
          example: Q2
          description: >-
            The query type id if one is known for the query/message (as defined in
            https://docs.google.com/spreadsheets/d/18zW81wteUfOn3rFRVG0z8mW-ecNhdsfD_6s73ETJnUw/edit#gid=1742835901
            )
        terms:
          type: object
          description: Dict of terms needed by the specific query type
          properties:
            disease:
              type: string
              example: malaria
            protein:
              type: string
              example: P12345
            anatomical_entity:
              type: string
              example: liver
            chemical_substance:
              type: string
              example: ibuprofen
            metabolite:
              type: string
              example: ibuprofen
          additionalProperties: true
        query_options:
          type: object
          example: 
            coalesce: true
            threshold: 0.9
          description: >-
            Dict of options that can be sent with the query. Options are tool
            specific and not stipulated here
        results:
          description: List of all returned potential answers for the query posed
          type: array
          items:
            $ref: '#/components/schemas/Result'
        query_graph:
          type: object
          description: >-
            QueryGraph object that contains a serialization of a query in the form
            of a graph
          items:
            $ref: '#/components/schemas/QueryGraph'
        knowledge_graph:
          type: object
          description: >-
            KnowledgeGraph object that contains all the nodes and edges referenced
            in any of the possible answers to the query
          items:
            $ref: '#/components/schemas/KnowledgeGraph'
        remote_knowledge_graph:
          type: object
          description: >-
            Connection information for a remote knowledge graph that is a
            substitute for local KnowledgeGraph contained in this Message
          items:
            $ref: '#/components/schemas/RemoteKnowledgeGraph'
      additionalProperties: true
    Result:
      type: object
      description: One of potentially several results or answers for a query
      properties:
        id:
          type: string
          example: 'https://rtx.ncats.io/api/rtx/v1/result/234'
          description: URI for this message
        description:
          type: string
          example: >-
            The genetic condition sickle cell anemia may provide protection from
            cerebral malaria via genetic alterations of proteins HBB (P68871) and
            HMOX1 (P09601).
          description: A free text description of this result answer from the reasoner
        essence:
          type: string
          example: ibuprofen
          description: >-
            A single string that is the terse essence of the result (useful for
            simple answers)
        essence_type:
          type: string
          example: drug
          description: A Translator bioentity type of the essence
        row_data:
          type: array
          example:
            - ibuprofen
            - 'CHEMBL:CHEMBL521'
          description: >-
            An arbitrary list of values that captures the essence of the result
            that can be turned into a tabular result across all answers (each
            result is a row) for a user that wants tabular output
          items:
            type: string
        score:
          type: number
          format: float
          example: 163.233
          description: Any type of score associated with this result
        score_name:
          type: string
          example: Jaccard distance
          description: Name for the score
        score_direction:
          type: string
          example: lower_is_better
          description: >-
            Sorting indicator for the score: one of higher_is_better or
            lower_is_better
        confidence:
          type: number
          format: float
          example: 0.9234
          description: >-
            Confidence metric for this result, a value between (inclusive) 0.0 (no
            confidence) and 1.0 (highest confidence)
        result_type:
          type: string
          example: individual query answer
          description: >-
            One of several possible result types: 'individual query answer',
            'neighborhood graph', 'type summary graph'
        result_group:
          type: integer
          example: 1
          description: >-
            An integer group number for results for use in cases where several
            results should be grouped together. Also useful to control sorting
            ascending.
        result_group_similarity_score:
          type: number
          format: float
          example: 0.95
          description: >-
            A score that denotes the similarity of this result to other members of
            the result_group
        reasoner_id:
          type: string
          example: RTX
          description: >-
            Identifier string of the reasoner that provided this result (e.g.,
            RTX, Robokop, Indigo, Integrator)
        result_graph:
          type: object
          description: >-
            A graph that describes the thought pattern of this result (i.e. answer
            to the query)
          $ref: '#/components/schemas/KnowledgeGraph'
        knowledge_map:
          type: object
          description: >-
            Lookup dict that maps QNode and QEdge identifiers in the QueryGraph to
            Node and Edge identifiers in the KnowledgeGraph
          additionalProperties: true
    KnowledgeGraph:
      type: object
      description: >-
        A thought graph associated with this result. This will commonly be a
        linear path subgraph from one concept to another, but related items aside
        of the path may be included.
      properties:
        nodes:
          type: array
          description: List of nodes in the KnowledgeGraph
          items:
            $ref: '#/components/schemas/Node'
        edges:
          type: array
          description: List of edges in the KnowledgeGraph
          items:
            $ref: '#/components/schemas/Edge'
      additionalProperties: true
    RemoteKnowledgeGraph:
      type: object
      description: >-
        A thought graph associated with this result that is not repeated here, but
        stored elsewhere in a way that can be remotely accessed by the reader of
        this Message
      properties:
        url:
          type: string
          example: 'http://robokop.renci.org/api/kg'
          description: URL that provides programmatic access to the remote knowledge graph
        credentials:
          type: object
          description: >-
            Credentials needed for programmatic access to the remote knowledge
            graph
          items:
            $ref: '#/components/schemas/Credentials'
      additionalProperties: true
    Credentials:
      description: Credentials needed for programmatic access to the remote knowledge graph
      type: object
      required:
        - username
        - password
      properties:
        username:
          description: Username needed for programmatic access to the remote knowledge graph
          type: string
        password:
          type: string
          description: Password needed for programmatic access to the remote knowledge graph
      additionalProperties: true
    QueryGraph:
      type: object
      description: >-
        A graph intended to be the thought path to be followed by a reasoner to
        answer the question. This graph is a representation of a question.
      properties:
        nodes:
          type: array
          description: List of nodes in the QueryGraph
          items:
            $ref: '#/components/schemas/QNode'
        edges:
          type: array
          description: List of edges in the QueryGraph
          items:
            $ref: '#/components/schemas/QEdge'
      additionalProperties: true
    QNode:
      type: object
      description: A node in the QueryGraph
      properties:
        node_id:
          type: string
          example: n00
          description: >-
            QueryGraph internal identifier for this QNode. Recommended form: n00,
            n01, n02, etc.
        curie:
          type: string
          example: 'OMIM:603903'
          description: CURIE identifier for this node
        type:
          type: string
          description: 'Entity type of this node (e.g., protein, disease, etc.)'
          example: disease
      additionalProperties: true
    QEdge:
      type: object
      description: An edge in the QueryGraph
      properties:
        edge_id:
          type: string
          example: e00
          description: >-
            QueryGraph internal identifier for this QEdge. Recommended form: e00,
            e01, e02, etc.
        type:
          type: string
          example: affects
          description: Higher-level relationship type of this edge
        relation:
          type: string
          example: upregulates
          description: Lower-level relationship type of this edge
        source_id:
          type: string
          example: 'https://omim.org/entry/603903'
          description: Corresponds to the @id of source node of this edge
        target_id:
          type: string
          example: 'https://www.uniprot.org/uniprot/P00738'
          description: Corresponds to the @id of target node of this edge
        negated:
          type: boolean
          example: true
          description: >-
            Boolean that if set to true, indicates the edge statement is negated
            i.e. is not true
      additionalProperties: true
    Node:
      type: object
      description: A node in the thought subgraph
      properties:
        id:
          type: string
          example: 'OMIM:603903'
          description: CURIE identifier for this node
        uri:
          type: string
          example: 'https://www.uniprot.org/uniprot/P00738'
          description: URI identifier for this node"
        name:
          type: string
          example: Haptoglobin
          description: Formal name of the entity
        type:
          type: array
          description: 'Entity type of this node (e.g., protein, disease, etc.)'
          example:
            - protein
          items:
            type: string
        description:
          type: string
          example: 'Haptoglobin captures, and combines with free plasma hemoglobin...'
          description: One to three sentences of description/definition of this entity
        symbol:
          type: string
          example: HP
          description: Short abbreviation or symbol for this entity
        node_attributes:
          type: array
          description: A list of arbitrary attributes for the node
          items:
            $ref: '#/components/schemas/NodeAttribute'
      additionalProperties: true
    NodeAttribute:
      type: object
      description: A generic attribute for a node
      properties:
        type:
          type: string
          example: article
          description: Entity type of this attribute
        name:
          type: string
          example: Wikipedia article
          description: Formal name of the attribute
        value:
          type: string
          example: '7.23e-12'
          description: Value of the attribute
        url:
          type: string
          example: 'https://en.wikipedia.org/wiki/Malaria'
          description: A URL corresponding to this attribute
      additionalProperties: true
    Edge:
      type: object
      description: An edge in the thought subgraph linking two nodes
      properties:
        id:
          type: string
          example: '553903'
          description: >-
            Local identifier for this node which is unique within this
            KnowledgeGraph, and perhaps within the source reasoner's knowledge
            graph
        type:
          type: string
          example: affects
          description: Higher-level relationship type of this edge
        relation:
          type: string
          example: upregulates
          description: Lower-level relationship type of this edge
        source_id:
          type: string
          example: 'https://omim.org/entry/603903'
          description: Corresponds to the @id of source node of this edge
        target_id:
          type: string
          example: 'https://www.uniprot.org/uniprot/P00738'
          description: Corresponds to the @id of target node of this edge
        is_defined_by:
          type: string
          example: reasoner
          description: A CURIE/URI for the translator group that made the KG
        defined_datetime:
          type: string
          example: '2018-11-03 15:34:23'
          description: >-
            Datetime at which the KG builder/updater pulled the information from
            the original source. Used as a freshness indicator.
        provided_by:
          type: string
          example: OMIM
          description: A CURIE/URI for the knowledge source that defined this edge
        confidence:
          type: number
          format: float
          example: 0.99
          description: >-
            Confidence metric for this edge, a value between (inclusive) 0.0 (no
            confidence) and 1.0 (highest confidence)
        weight:
          type: number
          format: float
          example: 0.99
          description: >-
            Weight metric for this edge, with no upper bound. Perhaps useful when
            formal confidence metrics are not available
        publications:
          type: array
          description: List of CURIEs for publications associated with this edge
          example:
            - 'PMID:12345562'
          items:
            type: string
        evidence_type:
          type: string
          example: 'ECO:0000220'
          description: >-
            A CURIE/URI for class of evidence supporting the statement made in an
            edge - typically a class from the ECO ontology
        qualifiers:
          type: string
          example: 'ECO:0000220'
          description: >-
            Terms representing qualifiers that modify or qualify the meaning of
            the statement made in an edge
        negated:
          type: boolean
          example: true
          description: >-
            Boolean that if set to true, indicates the edge statement is negated
            i.e. is not true
        edge_attributes:
          type: array
          description: A list of additional attributes for this edge
          items:
            $ref: '#/components/schemas/EdgeAttribute'
      additionalProperties: true
    EdgeAttribute:
      type: object
      description: A generic additional attribute for an edge
      properties:
        type:
          type: string
          example: localization
          description: Entity type of this attribute
        name:
          type: string
          example: Cell type limitation
          description: Formal name of the attribute
        value:
          type: string
          example: MFC cells
          description: >-
            Value of the attribute. While all attributes should have a name, many
            will not have a value
        url:
          type: string
          example: 'https://www.ncbi.nlm.nih.gov/pubmed/29309293'
          description: A URL corresponding to this attribute
      additionalProperties: true
    Feedback:
      type: object
      description: A single unit of Feedback
      properties:
        id:
          type: string
          example: 'https://rtx.ncats.io/api/rtx/v1/result/234/feedback/56'
          description: URI for this feedback item
        result_id:
          type: string
          example: 'https://rtx.ncats.io/api/rtx/v1/result/234'
          description: URI for the result that this feedback corresponds to
        expertise_level_id:
          type: integer
          example: 1
          description: Integer identifier of the claimed expertise level
        rating_id:
          type: integer
          example: 1
          description: Integer identifier of the applied rating
        commenter_id:
          type: integer
          example: 1
          description: Integer identifier of the commenter
        commenter_full_name:
          type: string
          example: John Smith
          description: Full name of the commenter
        datetime:
          type: string
          example: '2018-05-08 12:00'
          description: Datetime when the feedback was provided
        comment:
          type: string
          example: This is a great result because...
          description: A free text comment about this result
    ResultFeedback:
      type: object
      description: Feedback for one result
      properties:
        feedback_list:
          type: array
          description: List of feedback posts for this result
          items:
            $ref: '#/components/schemas/Feedback'
    MessageFeedback:
      type: object
      description: Feedback for all the results corresponding to this message
      properties:
        feedback_list:
          type: array
          description: List of feedback posts for this entire message
          items:
            $ref: '#/components/schemas/Feedback'
    DiffRequest:
      type: object
      description: Diff request
      properties:
        answer_1:
          type: object
          description: First item to diff
          items:
            $ref: '#/components/schemas/Message'
        answer_2:
          type: object
          description: First item to diff
          items:
            $ref: '#/components/schemas/Message'