From f29c767491082abce0bfe691218d024ebbd2b8a4 Mon Sep 17 00:00:00 2001
From: Ioana Tagirta <ioanatia@users.noreply.github.com>
Date: Wed, 19 Jul 2023 14:26:16 +0200
Subject: [PATCH] Document dictionary parameter for Search Applications
 (#97501)

* Document dictionary parameter for Search Applications

* Address PR feedback
---
 .../apis/put-search-application.asciidoc      | 91 ++++++++++++++++++-
 1 file changed, 90 insertions(+), 1 deletion(-)

diff --git a/docs/reference/search-application/apis/put-search-application.asciidoc b/docs/reference/search-application/apis/put-search-application.asciidoc
index 9e77b2c98cd6b..e4ed907be8b9a 100644
--- a/docs/reference/search-application/apis/put-search-application.asciidoc
+++ b/docs/reference/search-application/apis/put-search-application.asciidoc
@@ -49,6 +49,21 @@ The <<search-template,search template>> associated with this search application.
 - The template may be modified with subsequent <<put-search-application,put search application>> requests.
 - If no template is specified when creating a search application, or if a template is removed from a search application, we use the <<query-string-query-ex-request,query_string>> defined in the template examples as a default.
 - This template will be used by the <<search-application-search,search application search>> API to execute searches.
+- The template accepts an optional `dictionary` parameter which defines a https://json-schema.org[JSON schema] used for validating parameters sent to the <<search-application-search,search application search>> API.
+
+.Properties of `<template>`
+[%collapsible%open]
+=====
+
+`script`::
+(Required, object)
+The associated mustache template.
+
+`dictionary`::
+(Optional, object)
+The dictionary used to validate the parameters used with the <<search-application-search, search application search>> API. The dictionary must be a valid JSON schema.
+If `dictionary` is not specified, then the parameters will not be validated before being applied in the template.
+=====
 ====
 
 
@@ -85,12 +100,69 @@ PUT _application/search_application/my-app?create
         "query_string": "*",
         "default_field": "*"
       }
+    },
+    "dictionary": {
+      "properties": {
+        "query_string": {
+          "type": "string"
+        },
+        "default_field": {
+          "type": "string",
+          "enum": [
+            "title",
+            "description"
+          ]
+        },
+        "additionalProperties": false
+      },
+      "required": [
+        "query_string"
+      ]
     }
   }
 }
 ----
 // TEST[skip:TBD]
 
+When the above `dictionary` parameter is specified, the <<search-application-search, search application search>> API will perform the following parameter validation:
+
+* It accepts only the `query_string` and `default_field` parameters
+* It verifies that `query_string` and `default_field` are both strings
+* It accepts `default_field` only if it takes the values `title` or `description`
+
+If the parameters are not valid, the the <<search-application-search, search application search>> API will return an error.
+[source,console]
+----
+POST _application/search_application/my-app/_search
+{
+  "params": {
+    "default_field": "author",
+    "query_string": "Jane"
+  }
+}
+----
+// TEST[skip:TBD]
+
+In the above example, the value of the `default_field` parameter is not valid, therefore Elasticsearch will return an error:
+
+[source,console-result]
+----
+{
+  "error": {
+    "root_cause": [
+      {
+        "type": "validation_exception",
+        "reason": "Validation Failed: 1: $.default_field: does not have a value in the enumeration [title, description];"
+      }
+    ],
+    "type": "validation_exception",
+    "reason": "Validation Failed: 1: $.default_field: does not have a value in the enumeration [title, description];"
+  },
+  "status": 400
+}
+----
+// TEST[skip:TBD]
+
 The following example creates or updates an existing Search Application called `my-app`:
 
 [source,console]
@@ -112,9 +184,26 @@ PUT _application/search_application/my-app
         "query_string": "*",
         "default_field": "*"
       }
+    },
+    "dictionary": {
+      "properties": {
+        "query_string": {
+          "type": "string"
+        },
+        "default_field": {
+          "type": "string",
+          "enum": [
+            "title",
+            "description"
+          ]
+        },
+        "additionalProperties": false
+      },
+      "required": [
+        "query_string"
+      ]
     }
   }
 }
 ----
 // TEST[skip:TBD]
-