Entity Data Types

Speechly can post-process some entity values so that they are returned in a more structured format. This is done by assigning the entity to have an appropriate Data Type in the Dashboard.

Why do we need Entity Data Types?

Unless otherwise specified, the entity values returned from the Speechly API are verbatim what the user said. If you have configured the template

*book book a flight for $SPEECHLY.DATE(departure)

and the user says “book a flight for july third twenty twenty one”, without using a Data Type the API returns

intent: book
entity:
    name: "departure"
    value: "july third twenty twenty one"

However, if you explicitly designate the entity departure to have Data Type Date in the Dashboard, the API returns

intent: book
entity:
    name: "departure"
    value: "2021-07-03"

The Data Type of an entity thus determines what is done to the entity value after it has been recognized. While the default Data Type String returns the value verbatim, the other Data Types, such as Date, provide normalizations for the entities that make their further use easier. The Data Types are defined in the Speechly Dashboard when listing entities.

And while Standard Variables and Data Types can be used separately, the two features are best when combined.

Entity Data Type Reference

Here are all Entity Data Types that we support, a brief description of what they do, and what Standard Variable they are designed to work with.

  • Date — expressions that define a date are converted into ISO-8601 formatted strings (e.g., January fifth twenty twenty2020-01-05). Relative expressions like tomorrow or next Friday are parsed relative to the current date. Works together with the $SPEECHLY.DATE standard variable.

Note: You can choose from two Date types: Date (Prefer Future Dates) and Date (Prefer Past Dates). They only differ in their behaviour with relative date expressions in which it is unknown whether the user speaks about the future or the past. For example, the phrase “on Monday” can either refer to the previous Monday (in the past), or the following Monday (in the future). Likewise, “January fifth” can either refer to the previous or next January. By choosing the variant that prefers future dates, such phrases are mapped to a date in the future, while the one that prefers the past will return a date in the past, respectively. Which variant you should use depends on the application in question, and whether your users are more likely to talk about the future or the past. (When using the Command Line Tool to deploy your application, these Date type variants are date_future and date_past, respectively.)

  • Time - expressions that define a time of day are returned as a hh:mm formatted string using a 24-hour clock (e.g., three thirty pm15:30, quarter past two in the morning02:15, twenty past nine pm21:20). Works together with $SPEECHLY.TIME.

  • Number normalizes all numeric utterances into digits (e.g., five six four nine5649, seventeen point five17.5, three hundred thousand300000, three quarters0.75). Works together with $SPEECHLY.*_NUMBER standard variables.

  • Identifier should be used together with alphanumeric identifiers (sequences) that are spelled out one character at a time. Entities of this type are normalized into character sequences representing the identifier (e.g., zero zero seven x007x, one two seven dot zero dot zero dot one slash x y127.0.0.1/xy). Works together with $SPEECHLY.IDENTIFIER* standard variables.

  • Phone is the recommended data type for expressions that are phone numbers. Entities with this type are formatted according to common conventions for writing telephone numbers (plus four four two oh seven seven three oh one two three four+44 207 730 1234). Works together with $SPEECHLY.PHONE_NUMBER standard variable.

  • Person Name is a data type that should be used with entities that are person names. The returned entity value should in most cases have appropriate capitalization, and parts of the name that were spelled letter by letter should be combined to a single word (c o n a n o’brienConan O’Brien). Works together with $SPEECHLY.PERSON_NAME standard variable.

  • Email formats the returned entity value as an email address (john dot smith at company dot comjohn.smith@company.com, this data type also supports spelling parts of the entity: a n t t i at speechly dot comantti@speechly.com). Works together with $SPEECHLY.EMAIL_ADDRESS standard variable.

  • Website formats the returned entity value as a website URL (h t t p s colon slash slash docs dot speechly dot comhttps://docs.speechly.com). Works together with $SPEECHLY.WEB_ADDRESS standard variable.

  • Street address formats the returned entity value as a (US style) street address (one twenty three michigan avenue123 Michigan Av., forty seven east one hundred and tenth street47 E 100th St. ). Works together with $SPEECHLY.STREET_ADDRESS standard variable.


Profile image for Antti Ukkonen

Last updated by Antti Ukkonen on September 6, 2021 at 16:49 +0300

Found an error on our documentation? Please file an issue or make a pull request