Define Synonyms and IDs for Slot Type Values (Entity Resolution)

Entity resolution improves the way Alexa matches possible slot values in a user's utterance with the slots defined in your interaction model. You can define your custom slot type values as entities with fixed identifiers and synonyms. Then, when users make requests to your skill, Alexa attempts to match the possible slot values in the utterance with the values and synonyms in the entities you have defined. If there is a match, your skill gets the canonical value defined for the entity, the actual value that the user spoke, and the unique identifier.

Entity resolution takes place automatically, but to take full advantage of the feature, you need to define the synonyms and IDs for your slot values.

• Slot Value Synonyms, Unique Identifiers, and Entity Resolution
• Create Synonyms and Unique Identifiers for Custom Slot Type Values
  • Edit Slot Type Values and Identifiers
  • View or Edit Slot Type Values in the JSON Editor
• Custom Slot Type JSON Reference
• Slot Value Resolutions in the IntentRequest
• Entity Resolution for Built-in Slot Types
• Sample Slot Type Definition and IntentRequest
• Related Topics

Slot Value Synonyms, Unique Identifiers, and Entity Resolution

Users often use different words to say the same thing. For instance, for a MEDIA_TYPE slot intended to collect a particular type of media, a user might say "song", "track", or "single". In most cases, you would want your code to handle these three different values the same way.

To simplify this, define your slot type values as entities. An entity consists of:

• A possible slot value (such as "song"). This is the canonical slot value.
• An optional list of synonyms (such as "track" and "single"). These synonyms are tied to the canonical slot value.
• A unique ID (such as SONG).

Alexa uses these entities to resolve the user's utterance. The IntentRequest sent to your skill includes:

• The actual value the user spoke. This might be the canonical value, one of the synonyms, or another matching value.
• The canonical value defined for the matching entity.
• The unique ID of the matching entity.

Note that multiple possible matches can be returned.

You can use the unique ID in your code directly and not worry about the specific word that the user said for the slot. For example, for a MEDIA_TYPE slot type, the slot value "song" could have the ID SONG and the synonyms "track" and "single." When a user says "track" for this slot, your skill gets:

• The value "track"
• The canonical value "song"
• The ID SONG

Also note that the IntentRequest can include multiple possible matches for a slot rather than just one.

Create Synonyms and Unique Identifiers for Custom Slot Type Values

You can define the synonyms and unique identifiers for any custom slot type or extensible built-in slot type.

In the developer console, you can define the ID and synonyms for each slot value when editing the type. Alternatively, you can use the JSON Editor to view and edit these values in JSON.

Edit Slot Type Values and Identifiers

1. In the developer console, add or edit a custom slot type. Select the type from the Slot Types area in the left-hand navigation.
2. Add slot values normally.
3. Click in the ID column for a value to edit its ID.
4. Click in the Synonyms column for a value to enter a synonym, then click the plus or press Enter to save it.

View or Edit Slot Type Values in the JSON Editor

You can also use the JSON Editor to view and edit the IDs and synonyms for the slot type values in the JSON. For example, the following JSON defines a custom slot type called MEDIA_TYPE with two values. Each value ("album" and "song") has an ID and three synonyms:

{
  "types": [
    {
      "name": "MEDIA_TYPE",
      "values": [
        {
          "id": "SONG",
          "name": {
            "value": "song",
            "synonyms": ["tune","single","track"]
          }
        },
        {
          "id": "ALBUM",
          "name": {
            "value": "album",
            "synonyms": ["record","lp","cd"]
          }
        }
      ]
    }
  ]
}

See the JSON syntax shown below for definitions of these JSON properties.

After making any changes in the JSON Editor, always click Save Model. Then build your model before testing.

Custom Slot Type JSON Reference

The JSON format for custom slot types specifies the types property as an array of objects. Each object represents a custom slot type and includes a name and array of values. Each value consists of:

• A unique identifier (id).
• A string value (name.value).
• An optional array of synonyms for that value (name.synonyms[]).

When a user's utterance mentions either the value or one of the synonyms, Alexa resolves the utterance to the value and includes it in the IntentRequest sent to your skill.

Slot type definition syntax:

{
  "types": [
    {
      "name": "string",
      "values": [
        {
          "id": "string",
          "name": {
            "value": "string",
            "synonyms": [
              "string",
              "string"
            ]
          }
        }
      ]
    }
  ]
}

For an example, see Sample Slot Type Definition and IntentRequest, below.

Slot Value Resolutions in the IntentRequest

The IntentRequest sent to your skill includes additional information for the slot values. The additional properties are all within the slots object on the intent.

Continuing the earlier MEDIA_TYPE slot type example, an intent using this type for the MediaType slot might produce an IntentRequest like this:

{
  "type": "IntentRequest",
  "intent": {
    "name": "GetMediaIntent",
    "slots": {
      "MediaType": {
        "name": "MediaType",
        "value": "track",
        "resolutions": {
          "resolutionsPerAuthority": [
            {
              "authority": "amzn1.er-authority.echo-sdk.<skill_id>.MEDIA_TYPE",
              "status": {
                "code": "ER_SUCCESS_MATCH"
              },
              "values": [
                {
                  "value": {
                    "name": "song",
                    "id": "SONG"
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

In this request:

• The value property for the slot object (MediaType) reflects the value the user spoke. In the above example, the user spoke one of the synonyms defined for the SONG value.
• The resolutions property contains the results of entity resolution. These are organized by authority. An authority represents the source for the data provided for the slot. For a custom slot type, the authority is the slot type you defined.
• The values array within resolutionsPerAuthority contains the possible matching slot values. This includes the canonical value (resolutionsPerAuthority[].values[].value.name) and unique ID (resolutionsPerAuthority[].values[].value.id) for each possible match. Multiple matches can be returned. The values in the resolutionsPerAuthority[].values[] array are ordered from the most likely to least likely matches. Therefore, the first value in the array is considered the best match.

See the standard IntentRequest definition for details about the IntentRequest properties.

For an example, see Sample Slot Type Definition and IntentRequest, below.

Entity Resolution for Built-in Slot Types

When using a built-in slot type as is, no entity resolution takes place. The slot type value spoken by the user is sent to your skill with just the name, value, and confirmationStatus properties. For instance, the toCity slot in this example uses the built-in type AMAZON.US_CITY (for brevity, these JSON examples show just the relevant slot in the IntentRequest):

{
  "toCity": {
    "name": "toCity",
    "value": "Chicago",
    "confirmationStatus": "NONE"
  }
}

A subset of the built-in slot types can be extended with custom values. If you extend a slot type, entity resolution does take place and the resolutions property is included on all values for the slot. You can add synonyms and custom IDs for your values.

In this example, the AMAZON.US_CITY slot type has been extended. The value "chicago" was added, and given the synonym "the windy city" and the ID ORD:

{
  "toCity": {
    "name": "toCity",
    "value": "the windy city",
    "resolutions": {
      "resolutionsPerAuthority": [
        {
          "authority": "amzn1.er-authority.echo-sdk.<skill_id>.AMAZON.US_CITY",
          "status": {
            "code": "ER_SUCCESS_MATCH"
          },
          "values": [
            {
              "value": {
                "name": "chicago",
                "id": "ORD"
              }
            }
          ]
        }
      ]
    },
    "confirmationStatus": "NONE"
  }
}

Note that you can add values that were already part of the built-in slot type data set and assign your own IDs and synonyms. In the above example, the value "chicago" was already a value in the AMAZON.US_CITY slot type. The version you add as a custom value overrides the original, so the resolutions property includes your custom ID for this utterance.

You can also add a value that was already part of the built-in type data set as a synonym to your own value. This also overrides the original. For example, you could add the custom value "the windy city" to AMAZON.US_CITY and give it the synonym "chicago". In this case, the user's utterance "chicago" would send your skill the value they spoke ("chicago") and your custom canonical value "the windy city":

{
  "toCity": {
    "name": "toCity",
    "value": "Chicago",
    "resolutions": {
      "resolutionsPerAuthority": [
        {
          "authority": "amzn1.er-authority.echo-sdk.<skill-id>.AMAZON.US_CITY",
          "status": {
            "code": "ER_SUCCESS_MATCH"
          },
          "values": [
            {
              "value": {
                "name": "the windy city",
                "id": "ORD"
              }
            }
          ]
        }
      ]
    },
    "confirmationStatus": "NONE"
  }
}

Note the meaning of the status code (resolutions.resolutionsPerAuthority[].status.code) for an extended built-in slot type:

• If the user's value matches one of your custom values or synonyms, the status code is ER_SUCCESS_MATCH.
• If the user's value matches anything else (such as the built-in data for the type), the code is ER_SUCCESS_NO_MATCH.

For more about how to extend a built-in slot type, see Extend a Built-in Slot Type with Additional Values. For the list of extensible types, see Slot Types You Can Extend.

Sample Slot Type Definition and IntentRequest

The following example shows the JSON for a GetMediaIntent intent and two custom slot types that include identifiers and synonyms (MEDIA_TYPE and MEDIA_TITLE).

{
  "interactionModel": {
    "languageModel": {
      "invocationName": "my sample skill",
      "intents": [
        {
          "name": "GetMediaIntent",
          "slots": [
            {
              "name": "MediaType",
              "type": "MEDIA_TYPE"
            },
            {
              "name": "MediaTitle",
              "type": "MEDIA_TITLE"
            }
          ],
          "samples": [
            "tell me about the {MediaType} {MediaTitle}",
            "get the {MediaType} called {MediaTitle}",
            "get the {MediaType} {MediaTitle}",
            "many more sample utterances"
          ]
        }
      ],
      "types": [
        {
          "name": "MEDIA_TYPE",
          "values": [
            {
              "id": "VIDEO",
              "name": {
                "value": "video",
                "synonyms": [
                  "music video"
                ]
              }
            },
            {
              "id": "SONG",
              "name": {
                "value": "song",
                "synonyms": [
                  "tune",
                  "single",
                  "track"
                ]
              }
            },
            {
              "id": "ALBUM",
              "name": {
                "value": "album",
                "synonyms": [
                  "record",
                  "lp",
                  "cd"
                ]
              }
            }
          ]
        },
        {
          "name": "MEDIA_TITLE",
          "values": [
            {
              "id": "song_id_456",
              "name": {
                "value": "Rolling in the Deep",
                "synonyms": [
                  "in the deep",
                  "rolling deep"
                ]
              }
            },
            {
              "id": "song_id_123",
              "name": {
                "value": "Ray of Light",
                "synonyms": [
                  "ray",
                  "ray of lights",
                  "ray of the ligh"
                ]
              }
            }
          ]
        }
      ]
    }
  }
}

The user might interact with the skill like this:

This utterance mentions values for both slots (MediaType, MediaTitle). Alexa resolves these mentions using the data provided in your custom slot type and sends your skill the following IntentRequest:

{
  "type": "IntentRequest",
  "intent": {
    "name": "GetMediaIntent",
    "slots": {
      "MediaType": {
        "name": "MediaType",
        "value": "song",
        "resolutions": {
          "resolutionsPerAuthority": [
            {
              "authority": "amzn1.er-authority.echo-sdk.<skill_id>.MEDIA_TYPE",
              "status": {
                "code": "ER_SUCCESS_MATCH"
              },
              "values": [
                {
                  "value": {
                    "name": "song",
                    "id": "SONG"
                  }
                }
              ]
            }
          ]
        }
      },
      "MediaTitle": {
        "name": "MediaTitle",
        "value": "rolling in the deep",
        "resolutions": {
          "resolutionsPerAuthority": [
            {
              "authority": "amzn1.er-authority.echo-sdk.<skill_id>.MEDIA_TITLE",
              "status": {
                "code": "ER_SUCCESS_MATCH"
              },
              "values": [
                {
                  "value": {
                    "name": "Rolling in the Deep",
                    "id": "song_id_456"
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Since the entity definitions include synonyms, your skill gets a similar result if the user uses slightly different wording:

Since track was defined as a synonym of song, Alexa can resolve this value and provide you with the same ID (for brevity, this example only shows the request JSON for the MediaType slot):

{
  "MediaType": {
    "name": "MediaType",
    "value": "track",
    "resolutions": {
      "resolutionsPerAuthority": [
        {
          "authority": "amzn1.er-authority.echo-sdk.<skill_id>.MEDIA_TYPE",
          "status": {
            "code": "ER_SUCCESS_MATCH"
          },
          "values": [
            {
              "value": {
                "name": "song",
                "id": "SONG"
              }
            }
          ]
        }
      ]
    }
  }
}

Related Topics

• Create Intents, Utterances, and Slots
• Interaction Model Schema
• Standard Request Types Reference
• Steps to Build a Custom Skill