Copy QuestionAnswering definitions to common.json and refer them in analyzeconversations.json (#19030)

Co-authored-by: Chong Tang <[email protected]>

Author: ChongTang

specification/cognitiveservices/data-plane/Language/stable/2022-05-01/analyzeconversations.json

@@ -76,10 +76,10 @@
           "Conversation project result": {
             "$ref": "./examples/conversations/SuccessfulAnalyzeConversations.json"
           },
-          "Arbitration result": {
+          "Orchestration result": {
             "$ref": "./examples/conversations/SuccessfulAnalyzeConversationsArbitration.json"
           },
-          "Orchestrator direct target result": {
+          "Orchestration direct target result": {
             "$ref": "./examples/conversations/SuccessfulAnalyzeConversationsArbitrationDirectTarget.json"
           }
         }
@@ -409,8 +409,8 @@
       ],
       "properties": {
         "callingOptions": {
-          "type": "object",
-          "description": "The options sent to a Question Answering KB."
+          "description": "The options sent to a Question Answering KB.",
+          "$ref": "common.json#/definitions/AnswersOptions"
         }
       }
     },
@@ -1362,7 +1362,7 @@
         "More"
       ],
       "x-ms-enum": {
-        "name": "Modifier",
+        "name": "TemporalModifier",
         "modelAsString": true
       }
     },
@@ -1397,8 +1397,8 @@
       ],
       "properties": {
         "result": {
-          "type": "object",
-          "description": "The generated answer by a Question Answering KB."
+          "description": "The generated answer by a Question Answering KB.",
+          "$ref": "common.json#/definitions/AnswersResult"
         }
       }
     },

specification/cognitiveservices/data-plane/Language/stable/2022-05-01/common.json

@@ -172,6 +172,350 @@
           }
         ]
       }
+    },
+    "AnswersResult": {
+      "type": "object",
+      "description": "Represents List of Question Answers.",
+      "additionalProperties": false,
+      "properties": {
+        "answers": {
+          "type": "array",
+          "description": "Represents Answer Result list.",
+          "items": {
+            "$ref": "#/definitions/KnowledgeBaseAnswer"
+          }
+        }
+      }
+    },
+    "KnowledgeBaseAnswer": {
+      "type": "object",
+      "description": "Represents knowledge base answer.",
+      "additionalProperties": false,
+      "properties": {
+        "questions": {
+          "type": "array",
+          "description": "List of questions associated with the answer.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "answer": {
+          "type": "string",
+          "description": "Answer text."
+        },
+        "confidenceScore": {
+          "type": "number",
+          "format": "double",
+          "x-ms-client-name": "confidence",
+          "description": "Answer confidence score, value ranges from 0 to 1.",
+          "maximum": 1,
+          "minimum": 0
+        },
+        "id": {
+          "type": "integer",
+          "x-ms-client-name": "qnaId",
+          "description": "ID of the QnA result.",
+          "format": "int32"
+        },
+        "source": {
+          "type": "string",
+          "description": "Source of QnA result."
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Metadata associated with the answer, useful to categorize or filter question answers.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "dialog": {
+          "type": "object",
+          "$ref": "#/definitions/KnowledgeBaseAnswerDialog"
+        },
+        "answerSpan": {
+          "type": "object",
+          "x-ms-client-name": "shortAnswer",
+          "description": "Answer span object of QnA with respect to user's question.",
+          "$ref": "#/definitions/AnswerSpan"
+        }
+      }
+    },
+    "KnowledgeBaseAnswerDialog": {
+      "type": "object",
+      "description": "Dialog associated with Answer.",
+      "properties": {
+        "isContextOnly": {
+          "type": "boolean",
+          "description": "To mark if a prompt is relevant only with a previous question or not. If true, do not include this QnA as search result for queries without context; otherwise, if false, ignores context and includes this QnA in search result."
+        },
+        "prompts": {
+          "type": "array",
+          "description": "List of prompts associated with the answer.",
+          "maxItems": 20,
+          "items": {
+            "$ref": "#/definitions/KnowledgeBaseAnswerPrompt"
+          }
+        }
+      }
+    },
+    "KnowledgeBaseAnswerPrompt": {
+      "type": "object",
+      "description": "Prompt for an answer.",
+      "properties": {
+        "displayOrder": {
+          "type": "integer",
+          "description": "Index of the prompt - used in ordering of the prompts.",
+          "format": "int32"
+        },
+        "qnaId": {
+          "type": "integer",
+          "description": "QnA ID corresponding to the prompt.",
+          "format": "int32"
+        },
+        "displayText": {
+          "type": "string",
+          "description": "Text displayed to represent a follow up question prompt.",
+          "maxLength": 200
+        }
+      }
+    },
+    "AnswerSpan": {
+      "type": "object",
+      "description": "Answer span object of QnA.",
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "type": "string",
+          "description": "Predicted text of answer span."
+        },
+        "confidenceScore": {
+          "type": "number",
+          "x-ms-client-name": "confidence",
+          "description": "Predicted score of answer span, value ranges from 0 to 1.",
+          "format": "double",
+          "maximum": 1,
+          "minimum": 0
+        },
+        "offset": {
+          "type": "integer",
+          "description": "The answer span offset from the start of answer.",
+          "format": "int32"
+        },
+        "length": {
+          "type": "integer",
+          "description": "The length of the answer span.",
+          "format": "int32"
+        }
+      }
+    },
+    "AnswersOptions": {
+      "type": "object",
+      "description": "Parameters to query a knowledge base.",
+      "additionalProperties": false,
+      "properties": {
+        "qnaId": {
+          "type": "integer",
+          "description": "Exact QnA ID to fetch from the knowledge base, this field takes priority over question.",
+          "format": "int32"
+        },
+        "question": {
+          "type": "string",
+          "description": "User question to query against the knowledge base."
+        },
+        "top": {
+          "type": "integer",
+          "description": "Max number of answers to be returned for the question.",
+          "format": "int32"
+        },
+        "userId": {
+          "type": "string",
+          "description": "Unique identifier for the user."
+        },
+        "confidenceScoreThreshold": {
+          "type": "number",
+          "format": "double",
+          "x-ms-client-name": "confidenceThreshold",
+          "description": "Minimum threshold score for answers, value ranges from 0 to 1.",
+          "maximum": 1,
+          "minimum": 0
+        },
+        "context": {
+          "x-ms-client-name": "answerContext",
+          "description": "Context object with previous QnA's information.",
+          "$ref": "#/definitions/KnowledgeBaseAnswerContext"
+        },
+        "rankerType": {
+          "type": "string",
+          "x-ms-client-name": "rankerKind",
+          "description": "Type of ranker to be used.",
+          "x-ms-enum": {
+            "name": "RankerKind",
+            "modelAsString": true,
+            "values": [
+              {
+                "value": "QuestionOnly",
+                "description": "Question only ranker."
+              },
+              {
+                "value": "Default",
+                "description": "Default ranker."
+              }
+            ]
+          },
+          "enum": [
+            "Default",
+            "QuestionOnly"
+          ]
+        },
+        "filters": {
+          "description": "Filter QnAs based on given metadata list and knowledge base sources.",
+          "$ref": "#/definitions/QueryFilters"
+        },
+        "answerSpanRequest": {
+          "x-ms-client-name": "shortAnswerOptions",
+          "description": "To configure Answer span prediction feature.",
+          "$ref": "#/definitions/ShortAnswerOptions"
+        },
+        "includeUnstructuredSources": {
+          "type": "boolean",
+          "description": "(Optional) Flag to enable Query over Unstructured Sources."
+        }
+      }
+    },
+    "KnowledgeBaseAnswerContext": {
+      "type": "object",
+      "description": "Context object with previous QnA's information.",
+      "additionalProperties": false,
+      "required": [
+        "previousQnaId"
+      ],
+      "properties": {
+        "previousQnaId": {
+          "type": "integer",
+          "description": "Previous turn top answer result QnA ID.",
+          "format": "int32"
+        },
+        "previousUserQuery": {
+          "type": "string",
+          "x-ms-client-name": "previousQuestion",
+          "description": "Previous user query."
+        }
+      }
+    },
+    "QueryFilters": {
+      "type": "object",
+      "description": "filters over knowledge base.",
+      "additionalProperties": false,
+      "properties": {
+        "metadataFilter": {
+          "type": "object",
+          "$ref": "#/definitions/MetadataFilter"
+        },
+        "sourceFilter": {
+          "type": "object",
+          "$ref": "#/definitions/SourceFilter"
+        },
+        "logicalOperation": {
+          "type": "string",
+          "description": "Logical operation used to join metadata filter with source filter.",
+          "$ref": "#/definitions/LogicalOperationKind",
+          "default": "AND"
+        }
+      }
+    },
+    "MetadataFilter": {
+      "type": "object",
+      "description": "Find QnAs that are associated with the given list of metadata.",
+      "additionalProperties": false,
+      "properties": {
+        "metadata": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/MetadataRecord"
+          }
+        },
+        "logicalOperation": {
+          "type": "string",
+          "description": "Operation used to join metadata filters.",
+          "$ref": "#/definitions/LogicalOperationKind",
+          "default": "AND"
+        }
+      }
+    },
+    "MetadataRecord": {
+      "type": "object",
+      "description": "Object to provide the key value pair for each metadata.",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "value"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "Metadata Key from Metadata dictionary used in the QnA."
+        },
+        "value": {
+          "type": "string",
+          "description": "Metadata Value from Metadata dictionary used in the QnA."
+        }
+      }
+    },
+    "SourceFilter": {
+      "type": "array",
+      "description": "Find QnAs that are associated with any of the given list of sources in knowledge base.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "LogicalOperationKind": {
+      "type": "string",
+      "description": "Set to 'OR' or 'AND' for using corresponding logical operation.",
+      "x-ms-enum": {
+        "name": "LogicalOperationKind",
+        "modelAsString": true
+      },
+      "enum": [
+        "AND",
+        "OR"
+      ]
+    },
+    "ShortAnswerOptions": {
+      "type": "object",
+      "description": "To configure Answer span prediction feature.",
+      "additionalProperties": false,
+      "required": [
+        "enable"
+      ],
+      "properties": {
+        "enable": {
+          "type": "boolean",
+          "description": "Enable or disable Answer Span prediction.",
+          "enum": [
+            true
+          ],
+          "x-ms-enum": {
+            "name": "enable",
+            "modelAsString": false
+          }
+        },
+        "confidenceScoreThreshold": {
+          "type": "number",
+          "format": "double",
+          "x-ms-client-name": "confidenceThreshold",
+          "description": "Minimum threshold score required to include an answer span, value ranges from 0 to 1.",
+          "maximum": 1,
+          "minimum": 0
+        },
+        "topAnswersWithSpan": {
+          "type": "integer",
+          "x-ms-client-name": "top",
+          "description": "Number of Top answers to be considered for span prediction from 1 to 10.",
+          "format": "int32",
+          "maximum": 10,
+          "minimum": 1
+        }
+      }
     }
   },
   "parameters": {