# Response Validation

Response validation allows you to check that the user response contains the information you need to complete a task, or route to an appropriate task. You use validators in the requirements for your tasks (see Task Requirements).

You can use several different types of validation:

- Simple. Validate against a simple list of words and phrases, which the user input must match exactly.
- Regular expression. Validate against a regular expression pattern, which the user input must match.
- Eduction. Validate against a set of Eduction grammars and entities. This validator uses the embedded Answer Server Eduction module.
- Lua. Validate by using a Lua function. This validator calls a function in an external Lua script, which you must configure in the task configuration file. See Lua Processing Scripts.

You configure validators in the `validators` section of the task configuration file. This property takes an array of validators. Each validator must contain a unique ID, and a configuration object (one of `simple`, `regex`, `eduction`, and `lua`, depending on the validation type). The following sections describe each type of validator configuration in more detail, and provide examples of each type of validator.

Each validator object can also optionally include the properties in the following table.

Property | Type | Description
--- | --- | ---
`invalid_input_lua` | string | (Optional) A Lua function in the configured Lua script to call if the user input is not valid. For example, you might use this to submit the user response to your other answer systems. See Lua Processing Scripts.
`inverted` | Boolean | (Optional) Set to true if you want to invert the match (that is, to consider user input text as valid if it does not match the validator). The default value is false (user input text must match the validator).

## Simple Validation

In simple validation, you provide a simple list of values that the user input must match.

The following table describes the properties that you can set in the `simple` validation configuration object.

Property | Type | Description
--- | --- | ---
`matches` | array, objects | One or more match JSON objects, which contain the following properties: `values` (array, strings) Required. A list of values that you want to accept as user input for this validator. Answer Server accepts these values if they appear as part of a sentence in the input. `return_value` (string) Optional. The value that the validator uses if the user input matches any of the values in the array. If you do not set this value, the validator returns the value that was matched in the user input.
`case_insensitive` | Boolean | (Optional) Set to true if you want to match values case insensitively. The default value is false (case sensitive matching).

For example:

    {
       "tasks": [
          ...
       ]
       "validators": [
          {
             "id" : "UKcountryname",
             "simple" : {
                "matches": [
                   {
                      "values": [ "United Kingdom", "UK", "Great Britain", "GB" ],
                      "return_value": "UK"
                   },
                   {
                      "values": [ "England", "Northern Ireland", "Scotland", "Wales" ]
                   }
                ],
                "case_insensitive" : true
             }
          }
       ]
    }

This example validator checks that the user input matches one of the listed names for the United Kingdom. If the user text includes one of United Kingdom, UK, Great Britain, or GB, the validator returns the value UK to the task. If the user text includes England, Northern Ireland, Scotland, or Wales, the validator returns the value that the user matches.

## Regular Expression Validator

In regular expression validation, you provide a regular expression pattern that the user input string must match.

The following table describes the properties that you can set in the `regex` validation configuration object.

Property | Type | Description
--- | --- | ---
`pattern` | string | (Required) A regular expression pattern in ECMAScript regular expression format. The user input text must match the pattern to be valid. The validator supports named captures, which must have the name `<return>`. The validator returns the matched value if the input is valid.
`case_insensitive` | Boolean | (Optional) Set to true if you want to match values case insensitively. The default value is false (case sensitive matching).

For example:

    {
       "tasks": [
          ...
       ]
       "validators": [
          {
             "id": "PRODUCT_CODE",
             "regex": {
                "pattern": "PCO-.*"
             }
          }
       ]
    }

This validator matches any string that starts with the value `PCO-`.

## Eduction Validator

In Eduction validation, you specify one or more Eduction grammars (and optionally entities) that the user input string must match. This option uses the Answer Server embedded Eduction module.

The following table describes the properties that you can set in the `eduction` validation configuration object.

Property | Type | Description
--- | --- | ---
`grammars` | string | (Required) A comma-separated list of grammars to use to validate the input. You can use Wildcards in the grammar name to specify multiple grammars. However, you cannot use Wildcard values in the directory name. You can specify grammar files with an absolute path or a path relative to the Answer Server working directory.
`entities` | string | (Optional) A comma-separated list of entities in the configured grammars to use to validate the input. You can use Wildcards in the entity string to specify multiple entities.

For example:

    {
       "tasks": [
          ...
       ]
       "validators": [
          {
             "id": "UK_PHONE",
             "eduction": {
                "grammars": "configuration/number_phone_gb.xml",
                "entities": "phone/all/gb"
             }
          }
       ]
    }

This validator checks that the user input text contains a phone number that matches one of the types in the `phone/all/gb` entity of the `number_phone_gb.xml` grammar. If the user input text contains a valid match, the validator returns the normalized match text to the task.

## Lua Validator

In Lua validation, you specify the name of a Lua function to use to validate the user input.

The function that you specify must accept a string (the text to validate) as the first parameter. You can optionally also use a `taskUtils` object as the second parameter, if you want to use `taskUtils` methods in your validator.

When the text is a valid response, the function must a string (the normalized value to use from the user input text). When the user text is not a valid response the function must either return `nil` or not return a value.

The following table describes the properties that you can set in the `lua` validation JSON configuration object.

Property | Type | Description
--- | --- | ---
`function` | string | (Required) The name of the function to call. This function must exist in the Lua script that you configure in your task configuration JSON file (see Lua Processing Scripts).

For example:

    {
       "tasks": [
          ...
       ]
       "validators": [
          {
             "id": "FTSE_SYMBOL",
             "lua": {
               "function": "check_ftse_symbol"
             }
          }
       ]
    }

This validator calls the `check_ftse_symbol` function in the task Lua script to validate user input text. If the user input text is valid, the validator sends the value that the function returns to the task.

## Process Non-Valid Input

You can configure your response validators to call a Lua function when the user input text fails to validate.

To configure a Lua function, you set the `invalid_input_lua` property in your validator configuration to the name of the Lua function to call. This function must exist in the Lua script that you configure in your task configuration JSON file (see Lua Processing Scripts).

You can use this function to process non-valid input further. For example, if a user asks a question instead of providing a direct answer to a requirement, you might use the `invalid_input_lua` function to send the user input text to the `Ask` action, and retrieve answers from your answer systems.

The function that you specify must take a `taskUtils` object. If the function sets a response, Answer Server returns this response to the user.

If the function does not update the response, Answer Server uses a default message I'm sorry. I didn't understand that., and then repeats the requirement prompt. You can modify this message, if required (see Default Messages).

For example:

    {
       "tasks": [
          {
             "id" : "HOLIDAY",
             "trigger" : {
                "regex" : {
                   "pattern" : "(book|go) .* holiday"
                }
             },
             "requirements": [
                {
                   "id": "HOLIDAY_LOCATION",
                   "prompt": "What country would you like to visit?",
                   "validators": [ "COUNTRYVALIDATOR" ]
                }
             ]
          }
       ],
       "validators": [
          {
             "id": "COUNTRYVALIDATOR",
             "eduction": {
                "grammars": "configuration/place_countries.ecr"
             },
             "invalid_input_lua": "holiday_planner"
          }
       ]
    }

If `holiday_planner` is a Lua function that uses the user input text to send an `Ask` action, and returns the answer as a prompt, you might get a conversation similar to the following (user text is in italic, Answer Server response in bold):

I'd like to go on holiday.

What country would you like to visit?

What country is Budapest in?

Hungary. What country would you like to visit?

Hungary.

_FT_HTML5_bannerTitle.htm