Validate Slot Values

Slot validation lets you create validation rules for your slot values. Alexa can then check the user's response against these rules and prompt the user if the user provides an unacceptable value.

Understand slot validation

Slot validation provides an additional dialog model component to help you manage the conversation between your skill and the user. You can configure a set of validation rules for a slot, along with prompts to use for slot values that fail validation.

When the user fills the slot with an utterance, Alexa checks the provided value against your rules. If the value fails the validation, return the Dialog.Delegate directive to tell Alexa to use your prompts to ask the user for a correct value.

For example, in this dialog, the user is filling a custom Planet slot that only accepts values that match the names of planets in our solar system:

User: What is the weather like on the sun? (The value the sun is not an acceptable Planet slot value, so Alexa prompts for a new value.)
Alexa: The Sun is not a planet within our solar system. Please tell me a planet instead.
User: OK, Mars (The value mars is an acceptable value for a Planet slot.)
Alexa: On Mars, high of 70 and low of minus 195 fahrenheit. Sunny with a chance of sandstorms later in the day…

To use slot validation:

  1. Define validation rules and prompts for your slots where needed. These become part of the dialog model for the skill. There are several possible rules for the different types of slots. See:
  2. In your skill code, return the Dialog.Delegate directive if the dialog is not complete. This tells Alexa to prompt based on the dialog model and use slot validation prompts if necessary. See Delegate the dialog to Alexa to use the validation prompts.

Configure a slot with validation rules

You can define validation rules and prompts in the developer console. Alternatively, you can also specify the rules and prompts in the JSON Interaction Model Schema.

To define validation rules:

  1. In the left-hand navigation, find the intent and its list of slots, then click the slot name.

    Alternatively, from the page for a particular intent, find the slot in the Intent Slots section below the Sample Utterances and click the Edit Dialog link.

  2. Under slot type field, select Validations.
  3. Under Create Validation Rule, select the rule you want to use and click the plus.
    • The list shows just the validators that are relevant for the slot's type.
    • For details about the rules, see Validation rules.
  4. Fill in any additional fields specific to the rule, such as the value to compare to. This depends on the rule. See Validation rules.
  5. Below the rule, enter at least one prompt that Alexa should say to ask the user for a new value.

    You can include the slot name in curly brackets ({ }) so that Alexa speaks back the value that failed validation.

  6. Be sure to save and build the interaction model.

Use multiple validation rules for a slot

You can create multiple validation rules for a slot. The rules are checked in the order in which they are shown in the developer console or listed in the JSON. If a value fails a rule, Alexa stops checking and sends the response so your skill can respond with Dialog.Delegate. In a set of multiple rules, a later rule is checked only when all preceding rules have passed.

This means that you can define rules to provide smarter responses depending on the user's mistake. For example, suppose your skill provides facts about planets and uses a custom slot type with the planets of the solar system. You could use a single validation (Accept only Slot type’s values and synonyms) to only accept the planet names and provide a generic prompt like "{Planet} is not a planet. Please tell me a planet in our solar system."

However, you know that users might ask about other objects in the solar system that are not planets. Rather than using this generic prompt, you could set up an additional validation to reject these specific values (Reject only a set of values) with a more specific prompt before applying the more generic validation. For example, you could define these rules for the Planet slot:

  • Reject only a set of values with the values "the sun", "sun", and "our sun". Prompts:
    • "While the sun is part of our solar system, I can only answer this question for planets. Please tell me a planet."
    • "We don't think of the sun as having weather, exactly, so please tell me a planet instead."
    • (similar prompts showing that Alexa understands the value provided)
  • Accept only Slot type’s values and synonyms. Prompts:
    • {Planet} is not a planet. Please tell me a planet in our solar system.
    • (similar generic prompts that repeat back the incorrect value)

Delegate the dialog to Alexa to use the validation prompts

When a validation for a slot value fails, Alexa sends your skill a normal IntentRequest with the dialogState set to either STARTED or IN_PROGRESS. This means that there may be additional steps in the dialog before it can be considered completed, based on the defined dialog model.

It is up to your skill to then return the Dialog.Delegate directive to instruct Alexa to handle the next step of the dialog and use one of your validation prompts to ask the user for a new value. Alexa does not prompt the user if you don't return Dialog.Delegate.

A dialog model can also identify other steps needed to complete a dialog, such as slot elicitation for required slots, slot confirmation, and intent confirmation. Alexa selects the logical next step based on your dialog model when you return Dialog.Delegate.

You can use slot validation with both required and non-required slots. This lets you validate optional values if they are provided, but not force the user to fill those slots:

  • If the user invokes the intent with no value for the slot, the initial IntentRequest is incomplete (dialogState is either STARTED or IN_PROGRESS). After you return Dialog.Delegate, Alexa accepts the blank slot value and does not perform any validation or elicitation. In contrast, if the user does provide a slot value, Alexa performs the validation and uses the prompts when you return Dialog.Delegate.
  • For a required slot, Alexa elicits the slot value if necessary, and then does the validation in a subsequent step.

Since your skill gets an IntentRequest for each turn of the dialog, you can always step in and handle aspects of the dialog yourself. For example, you could default the value of an empty slot to a default value before you return Dialog.Delegate.

For more about ways to manage the conversation when you have a dialog model, see Dialog Interface Reference: About Managing the Conversation with the User.

Validation rules

The following sections provide details about all of the validation rules available and the slot types with which they can be used.

Compare to the values and synonyms defined for a custom slot type

This rule lets you accept only values that are explicitly defined for a custom slot type. The rule checks both value and synonyms. You can use this validation only with slots that use a custom slot type.

Validation Description Type Parameters

Accept only Slot type’s values and synonyms

Accept values that are defined in the list of custom slot type values and synonyms. If the user provides a value that does not match any of these defined values, the value fails the validation and Alexa can use your prompts to ask the user for a new value. This is equivalent to checking the entity resolution status code for the Slot object (resolutions.resolutionsPerAuthority[].status.code) for the slot and only accepting values where the code is ER_SUCCESS_MATCH.

hasEntityResolutionMatch

None

Compare to a fixed set of values

These rules let you either accept or reject a set of values. You can use these rules with the following slot types:

Validation Description Type Parameters

Accept only a set of values

Accept values that match a fixed set of values you specify. If the user provides a value that does not match any items on this list, the value fails the validation.

isInSet

A list of values that should be accepted.

Reject only a set of values

Reject values that match a fixed set of values you specify. If the user provides a value that matches any items on this list, the value fails the validation.

isNotInSet

A list of values that should be rejected.

The list of values in the set to accept or reject must be compatible with the slot type:

  • AMAZON.FOUR_DIGIT_NUMBER: Provide a list of four-digit numbers.
  • AMAZON.NUMBER: Provide a list of numbers.
  • AMAZON.Ordinal: Provide a list of numbers that correspond to the ordinal values to accept. For example, to accept or reject the words "first," "second," and "third," you would provide the numbers 1, 2, and 3.
  • AMAZON.PhoneNumber: Provide a list of phone numbers. Include just the digits of the numbers, no dashes or other formatting. For example: "2065551234".
  • All built-in List Types. Provide a list of string slot values.
  • Any custom slot type. Provide a list of string slot values..

Compare to a specific value (greater than or less than)

These rules let you accept user-provided slot values that are greater or lesser than a value you specify. You can use these rules with the following slot types:

Validation Description Type Parameters

Accept greater than a value

Accept values that are greater than a specified value. If the user's value is less than or equal to the criteria, the value fails the validation.

isGreaterThan

The value to compare to the slot value.

Accept greater than or equal to a value

Accept values that are greater than or equal to a specified value. If the user's value is less than the criteria, the value fails the validation.

isGreaterThanOrEqualTo

The value to compare to the slot value.

Accept less than a value

Accept values that are less than a specified value. If the user's value is greater than or equal to the specified value, the value fails the validation.

isLessThan

The value to compare to the slot value.

Accept less than or equal to a value

Accept values that are less than or equal to a specified value. If the user's value is greater than the specified value, the value fails the validation.

isLessThanOrEqualTo

The value to compare to the slot value.

The value to compare with the user's slot value must be compatible with the slot type:

When you use these validation rules for date and time comparisons (AMAZON.DATE and AMAZON.TIME slot types), note the following:

  • "greater than" means after the date or time
  • "less than" means before the date or time

For example, if you use isGreaterThan with an AMAZON.DATE slot and set the value to 2018-01-01, the slot accepts any date after January 1, 2018. Both December 31, 2017 and January 1, 2018 would fail validation. Use isGreaterThanOrEqualTo to include January 1 as a valid date.

Compare dates or times to a specified time span

These rules let you either accept or reject a date or time that falls within a particular time span. You can use these rules with AMAZON.DATE and AMAZON.TIME slots.

Validation Description Type Parameters

Accept within a duration

Accept date or time values that fall within a specified time span. If the user's value is before ore after the specified time span, the value fails validation.

isInDuration

The start and end of the time span. For details, see below.

Reject within a duration

Reject date or time values that fall within a specified time span. If the user's value is within the specified time span, the value fails validation.

isNotInDuration

The start and end of the time span. For details, see below.

You can use relative and absolute dates and times to specify the start and end of the time span.

The start and end of the time span are relative to when the user makes the request to your skill, based on the user's configured time zone. If the user's device is not configured with a time zone, the validation assumes GMT. The start time must come come before the end time.

When you use a duration in days or hours, you can use a minus sign (-) to indicate time before the current time. For example, -P3D specifies three days before today. Note that this is not part of the ISO-8601 standard.

You can combine absolute dates and relative durations in the same validation. For example, set start to 2018-07-04 and end to P3D to accept a date within three days of July 4, 2018.

You can also leave either start or end blank to create an open-ended time span. For example, set start to P0D (today) and leave end blank to accept just dates today or later and reject any dates in the past.

Date examples:

Scenario Start End
Date in the next 30 days

P0D

P30D

Date between 7 and 21 days from today

P7D

P21D

Future dates only

P0D

Date within three days of a specific date

2018-07-04

P3D

Past dates only

-P1D

Date that is within 15 days of today (15 days in the past or 15 days in the future)

-P15D

P15D

Date in the last 60 days

-P60D

P0D

Date within the past 30 days since yesterday (not counting today)

-P30D

-P1D

Time examples:

Scenario Start End
Time in the next 2.5 hours

PT0H

PT2H30M

Time that falls between three and six hours from now.

PT3H

PT6H

Future time only (time after the current time)

PT0H

Time between 6 PM and 3 hours after 6 PM.

18:00

PT3H

Past time only (time before the current time)

PT0H

Time within the last three hours or next three hours (so between 3 hours ago and 3 hours in the future)

-PT3H

PT3H

Past time between three hours ago and six hours ago.

-PT6H

-PT3H

Time in the last 5 hours

-PT5H

PT0H

JSON for Validation Rules

You can see and edit the JSON representation of slot validations within your dialog model in the JSON Editor. Validations for a slot are defined in the validations array in interactionModel.dialog.intents[].slots[].validations. The corresponding prompts are in prompts.

For brevity, the languageModel property is not shown. For details about the interaction model JSON, see Interaction Model Schema.

{
  "interactionModel": {
    "dialog": {
      "intents": [
        {
          "name": "PlanetWeather",
          "confirmationRequired": false,
          "prompts": {},
          "slots": [
            {
              "name": "PlanetSlot",
              "type": "Planet",
              "confirmationRequired": false,
              "elicitationRequired": false,
              "prompts": {},
              "validations": [
                {
                  "type": "isNotInSet",
                  "prompt": "Slot.Validation.732783665450.1021749810162.1251889105792",
                  "values": [
                    "the sun",
                    "our sun",
                    "sun"
                  ]
                },
                {
                  "type": "hasEntityResolutionMatch",
                  "prompt": "Slot.Validation.722668100550.1421087061194.1198477460217"
                }
              ]
            }
          ]
        }
      ]
    },
    "prompts": [
      {
        "id": "Slot.Validation.722668100550.1421087061194.1198477460217",
        "variations": [
          {
            "type": "PlainText",
            "value": "Please tell me a planet like Earth, Mars, or Jupiter. You know, one of the nine in the solar system."
          },
          {
            "type": "PlainText",
            "value": "{PlanetSlot} is not a planet -- I need one of the nine planets in our solar system"
          },
          {
            "type": "PlainText",
            "value": "I did not recognize {PlanetSlot} as a planet in our solar system. Please tell me a valid planet."
          },
          {
            "type": "PlainText",
            "value": "Please tell me a planet within our solar system"
          }
        ]
      },
      {
        "id": "Slot.Validation.732783665450.1021749810162.1251889105792",
        "variations": [
          {
            "type": "PlainText",
            "value": "While the sun is part of our solar system, I can only answer this question for planets. Please tell me a planet."
          },
          {
            "type": "PlainText",
            "value": "We don't think of the Sun as having weather, exactly, so please tell me a planet instead."
          }
        ]
      }
    ]
  }
}