extra info in trapi

TranslatorReasonerAPI.yaml

@@ -374,6 +374,14 @@ components:
           allOf:
             - $ref: '#/components/schemas/KnowledgeGraph'
           nullable: true
+        auxiliary_graphs:
+          type: object
+          description: >-
+            Dictionary of AuxiliaryGraph instances that are used by Knowledge
+            Graph Edges and Result Analyses. These are referenced elsewhere by
+            the dictionary key.
+          additionalProperties:
+            $ref: '#components/schemas/AuxiliaryGraph'
       additionalProperties: false
     LogEntry:
       description: >-
@@ -439,40 +447,26 @@ components:
             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
+        analyses:
+          type: array
           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
+            The list of all Analysis components that contribute to the result.
+            See below for Analysis components.
+          items:
+            $ref: '#/components/schemas/Analysis'
       additionalProperties: true
       required:
         - node_bindings
-        - edge_bindings
+        - analyses
     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).
+          (such annotation is not yet fully standardized). Each Node
+          Binding must bind directly to node in the original Query Graph.
       properties:
         id:
           $ref: '#/components/schemas/CURIE'
@@ -505,13 +499,79 @@ components:
       additionalProperties: true
       required:
         - id
+    Analysis:
+      type: object
+      description: >-
+        An analysis is a dictionary that contains information about
+        the result tied to a particular service. Each Analysis is
+        generated by a single reasoning service, and describes the
+        outputs of analyses performed by the reasoner on a particular
+        Result (e.g. a result score), along with provenance information
+        supporting the analysis (e.g. method or data that supported
+        generation of the score).
+      properties:
+        reasoner_id:
+          $ref: '#/components/schemas/CURIE'
+          description: The id of the service generating and using this Anlysis
+        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
+        edge_bindings:
+          type: object
+          description: >-
+            The dictionary of input Query Graph to 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.
+          additionalProperties:
+            type: array
+            items:
+              $ref: '#/components/schemas/EdgeBinding'
+        support_graphs:
+          type: array
+          description: >-
+            This is a list of references to Auxiliary Graph instances
+            that supported the analysis of a Result as performed by the
+            reasoning service. Each item in the list is the key of a
+            single Auxiliary Graph.
+          nullable: true
+          items:
+            type: string
+        scoring_method:
+          type: string
+          description: >-
+            An identifier and link to an explanation for the method used
+            to generate the score
+          nullable: true
+        attributes:
+          type: array
+          description: >-
+            The attributes of this particular Analysis.
+          items:
+            $ref: '#/components/schemas/Attribute'
+          nullable: true
+      additionalProperties: true
+      required:
+        - reasoner_id
+        - edge_bindings
     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).
+        Edge bindings are captured within a specific reasoner's Analysis
+        object because the Edges in the Knowledge Graph that get bound to
+        the input Query Graph may differ between reasoners.
       properties:
         id:
           type: string
@@ -529,6 +589,36 @@ components:
       additionalProperties: true
       required:
         - id
+    AuxiliaryGraph:
+      type: object
+      description: >-
+        A single AuxiliaryGraph instance that is used by Knowledge Graph
+        Edges and Result Analyses. Edges comprising an Auxiliary Graph
+        are a subset of the Knowledge Graph in the message. Data creators
+        can create an AuxiliaryGraph to assemble a specific collections
+        of edges from the Knowledge Graph into a named graph that can be
+        referenced from an Edge as evidence/explanation supporting that Edge,
+        or from a Result Analysis as information used to generate a score.
+      properties:
+        edges:
+          type: array
+          description: >-
+            List of edges that form the Auxiliary Graph. Each item is a
+            reference to a single Knowledge Graph edge
+          items:
+            type: string
+          nullable: false
+          minItems: 1
+        attributes:
+          type: array
+          description: >-
+            Attributes of the Auxiliary Graph
+          items:
+            $ref: '#/components/schemas/Attribute'
+          nullable: true
+      additionalProperties: true
+      required:
+        - edges
     KnowledgeGraph:
       type: object
       description: >-