Conditional Slot Validation in ACDL

In ACDL, conditions are criteria that must be satisfied for execution of an API call. Conditional slot validation is a dialog management feature that lets you specify a set of slot validation conditions and determine what action to take if the conditions aren't met. This document explains what conditional slot validation is, explores how utterances are evaluated, and illustrates relevant Alexa Conversations Description Language (ACDL) syntax.

Delegate dialog management

Before you implement conditional slot validation in your skill, you must delegate dialog management to Alexa Conversations. Alexa Conversations uses machine learning to handle state management, dialog variations, contextual carry-over, and corrections. For details, see Hand Off Dialog Management to and from Alexa Conversations.

Define slot validation conditions

You specify the criteria used to determine the validity of user-provided slot values. These values are evaluated immediately after a user utterance fills a slot. Values are evaluated again each time the user mentions the same entity type as the one specified in the condition.

The user utterance "Seattle" fills the cityName slot in the ACDL getWeatherEvent slot type.

type WeatherResult {
    City cityName
    NUMBER highTemp
    NUMBER lowTemp
}

If multiple slot validation conditions are specified, each condition is evaluated independently, in the order in which the rules are given in ACDL. If a validation is executed, then the subsequent conditions are not evaluated.

Handle catalog validation

You can provide a custom catalog against which a given argument can be tested. The argument in the user utterance is compared with a fixed set of values in the catalog to determine if the condition evaluates to true or false. For example, "seattle" can be compared with the custom catalog ["seattle", "san jose", "los angeles"]. This expression evaluates to true.

Determine subsequent actions

Alexa continues to request arguments until all slots are filled. If the condition applied to a user utterance for a given slot evaluates to true and there are no more conditions to evaluate, the API is called and the requested information is returned. If the user utterance is not a valid argument, the condition evaluates to false. This validation failure initiates a sequence of actions to prompt the user for a valid value. Actions are natural language generation (NLG) events invoked if conditions aren't met.

Understand ACDL syntax

You can use ACDL syntax to create Alexa Conversations skills, as shown in the following weather skill example. ACDL executes the API call only if slot values meet specified conditions.

For example, suppose a user asks about the weather in Boston. The slot value "boston" is not an allowed value in the custom catalog ["seattle", "san jose", "los angeles"]. Alexa initiates request_city_apla action to prompt the user again for cityName. Alexa continues to prompt for cityName until the user provides one of the catalog values. A different response, request_city_apla, can be used to explain which values the skill allows.

namespace com.myweather

import com.amazon.alexa.ask.conversations.*
import com.amazon.ask.types.builtins.AMAZON.*
import com.amazon.alexa.schema.Nothing
import prompts.weather_apla
import prompts.request_city_apla
import prompts.request_date_apla
import prompts.request_city_date_apla

type CityAndDate {
    optional City cityName
    optional DATE date
}

getWeatherEvent = utterances < CityAndDate > (
    [
        "What's the weather {date} in {cityName}",
        "what is the weather {date}",
        "How is the weather {date}",
        "How is weather in {cityName} {date}",
        "how is weather",
        "can you please give me weather report for {date}"
    ]
)

type WeatherResult {
    City cityName
    NUMBER highTemp
    NUMBER lowTemp
}

type ResponsePayload {
    WeatherResult weatherResult
}

@validateArg(cityName in ["seattle", "san jose", "los angeles"], request_city_apla, getWeather.arguments.cityName)
action WeatherResult getWeather(City cityName, DATE date)

dialog Nothing Weather {
    example {
        weatherRequest = expect(Invoke, getWeatherEvent)

        ensure(
            RequestArguments {
                arguments = [getWeather.arguments.cityName], response = request_city_apla
            },
            RequestArguments {
                arguments = [getWeather.arguments.date], response = request_date_apla
            },
            RequestArguments {
                arguments = [getWeather.arguments.cityName, getWeather.arguments.date], response = request_city_date_apla
            }
        )

        weatherResult = getWeather(weatherRequest.cityName, weatherRequest.date)

        response(weather_apla, Notify {
            actionName = getWeather
        }, payload = ResponsePayload {
            weatherResult = weatherResult
        })
    }
}

Recognize supported slot validation conditions

The following example API illustrates supported slot validation conditions for an item or quantity.

PlaceOrder(ITEM item, NUMBER quantity, DATE date)

PlaceOrder includes the following arguments.

1. item → slot type: <custom slot: ITEM> is a string
2. quantity → slot type: <NUMBER> is a number

Condition with a list of values

If the user provides an item value that's not in the list, Alexa renders requestItemPrompt.

@validateArg(item in ["pizza", "donut", "burger"], requestItemPrompt, PlaceOrder.arguments.item)
action PlaceOrderResult PlaceOrder(ITEM item, NUMBER quantity)

Condition with a single value

If the user provides an item value equal to “burger”, Alexa renders requestItemPrompt.

@validateArg(item != "burger", requestItemPrompt, PlaceOrder.arguments.item)
action PlaceOrderResult PlaceOrder(ITEM item, NUMBER quantity)

Condition with a number

If the user provides a quantity value less than or equal to 10, Alexa renders requestQuantityPrompt.

@validateArg(quantity > 10, requestQuantityPrompt, PlaceOrder.arguments.quantity)
action PlaceOrderResult PlaceOrder(ITEM item, NUMBER quantity)

Condition with a number and a list of values

If the user provides a quantity value less than or equal to 10, Alexa renders requestQuantityPrompt. Alternatively, if the user provides an item value that's not in the list, Alexa renders requestItemPrompt.

@validateArg(quantity > 10, requestQuantityPrompt, PlaceOrder.arguments.quantity)
@validateArg(item in ["pizza", "donut", "burger"], requestItemPrompt, PlaceOrder.arguments.item)
action PlaceOrderResult PlaceOrder(ITEM item, NUMBER quantity)

Condition with a slot type (condition not met)

If the user provides an item value that's not in slot type ITEM, Alexa renders requestItemPrompt.

@validateArg(item in ITEM, requestItemPrompt, PlaceOrder.arguments.item)
action PlaceOrderResult PlaceOrder(ITEM item, NUMBER quantity)

Condition with slot type (condition met)

If the user provides an item value that is in slot type ITEM, Alexa renders requestItemPrompt.

@validateArg(Array.indexOf(item, ITEM) == -1, `requestItemPrompt`, PlaceOrder.arguments.item)
action PlaceOrderResult PlaceOrder(ITEM item, NUMBER quantity)

Related topics

• Choose Slot Elicitation Order in Alexa Conversations
• Actions in the Alexa Conversations Description Language
• Conditional Expressions in the Alexa Conversations Description Language

Last updated: Nov 27, 2023