Standard Variables and Data Types

Introduction

The Speechly SLU applications are built by specifying a set of example utterances for which we use our Speechly Annotation Language (SAL). The example utterances should, as accurately as possible, reflect what your users might say to your application. Your examples are then fed as training data to a fairly complex machine learning system, which takes care of building all the bits and pieces required for a computer to understand human speech.

Standard Variables are building blocks that make supporting certain common but somewhat complex expressions in the Speechly SLU applications easier. While you could construct these same expressions yourself with the SAL, our predefined standard types let you focus more on the unique aspects of your application. The Standard Variables look like and are used like normal variables, but you don’t have to define them in your configuration, because we’ve already done it for you. The Standard Variables can be identified by their names, which start with SPEECHLY. You can see a standard variable being used in the example utterance below, which now permits various ways of expressing dates to be recognized, without having to define them individually.

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

Data Types determine what is done to an entity after it has been recognized. While the default Data Type String leaves the entities as they are recognized, 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.

While the Standard Variables and Data Types can be used separately, the two features are best when combined. With the entity departure defined as Date in the example above, an utterance like “Book a flight for August ninth two thousand twenty” would be recognized, and the SLU API would return the recognition as:

intent: book
entity:
    name: "departure"
    value: "2020-08-09"

Now one neither has to make the effort to define how the dates look like nor determine how they map into a structured format.

Supported Standard Variables and the corresponding Data Types

Data Types

• Date — expressions that define a date are converted into ISO-8601 as a string (e.g., January fifth twenty twenty → 2020-01-05). Relative expressions like tomorrow or next Friday are parsed relative to the current date. If the year is missing from the expression, the current year will be used. Works together with the $SPEECHLY.DATE standard variable.

• 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 pm → 15:30, quarter past two in the morning → 02:15, twenty past nine pm → 21:20). Works together with $SPEECHLY.TIME.

• Number normalizes all numeric utterances into digits (e.g., five six four nine → 5649, seventeen point five → 17.5, three hundred thousand → 300000, three quarters → 0.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 x → 007x, one two seven dot zero dot zero dot one slash x y → 127.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’brien → Conan 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 com → john.smith@company.com, this data type also supports spelling parts of the entity: a n t t i at speechly dot com → antti@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 com → https://docs.speechly.com). Works together with $SPEECHLY.WEB_ADDRESS standard variable.

Dates

In many applications, you need to use dates and concepts such as tomorrow or today. While, theoretically, you could provide the model with thousands of examples of how the users may refer to certain times, there’s a simpler way.

If you use the Standard Variable $SPEECHLY.DATE, the model automatically understands dates and relative constructs that can be mapped into a certain date or month:

• today
• tomorrow
• day after tomorrow
• next Friday
• next January

This allows the end-users to use any sensible way of referring to dates such as, July the fifth twenty-twenty or fifth of July.

When you also define the Data Type on the Speechly Dashboard as Date, the resulting entity is parsed as ISO-8601 — in the form of a date string (e.g., 2020-07-05).

Of course, it’s not always sensible to have all dates available in all applications. If your application supports a limited range of date expressions, you might want to add a set of examples in your configuration instead, like:

weekdays = [monday|tuesday|wednesday|thursday|friday]
*scheduling next week only $weekdays(available) is okay
*scheduling next week only $weekdays(available) [and|or] $weekdays(available) are okay

Numbers

Often SLU applications need to understand numbers, and thus Speechly supports several Standard Variables for recognizing them. In addition, the Speechly Annotation Language has the number range syntax amount = [1..20] (explained here) for defining custom number ranges easily.

• $SPEECHLY.NUMBER is the most general of the number variables. It aims to support the widest range of numbers, for example, five million five hundred twenty-eight thousand eight, minus zero point zero five, and eleven hundred point sixteen.

• $SPEECHLY.CARDINAL_NUMBER is otherwise similar in scope, but it does not support decimals or fractions. $SPEECHLY.POSITIVE_NUMBER and $SPEECHLY.NEGATIVE_NUMBER are subsets of $SPEECHLY.CARDINAL_NUMBER but strictly either positive or negative.

• $SPEECHLY.SMALL_NUMBER recognizes small numbers, for example, seventeen point five and minus five, and it is optimized for number expressions smaller than two hundred. $SPEECHLY.SMALL_CARDINAL_NUMBER is otherwise similar in scope, but it does not support decimals or fractions.

• $SPEECHLY.FOUR_DIGIT_NUMBER recognizes numbers that consist of four digits, for example, five six four nine.

• $SPEECHLY.SMALL_ORDINAL_NUMBER recognizes ordinal numbers from 1 to 31, for example, “fifth” in fifth floor.

For the best results, you should choose the most specific Standard Variable for your use case.

All of these Standard Variables can be used with the Data Type Number, which parses the recognized expression as a string consisting of digits. For example, zero zero three five would be parsed as 0035, nineteen as 19, seventeen point five as 17.5, and three hundred thousand as 300000.

Alphanumeric identifiers

The value of some entities, such as license plates or product codes, can be in the form of a mixed sequence of letters, digits, and special characters. Speechly provides three Standard Variables that can be used to represent such identifiers. These are:

• $SPEECHLY.IDENTIFIER_SHORT (for sequences of 1-4 characters)
• $SPEECHLY.IDENTIFIER_MEDIUM (for sequences of 5-8 characters)
• $SPEECHLY.IDENTIFIER_LONG (for sequences of 9-12 characters)

In addition to letters and digits, these sequences may contain the following symbols: # (hash), / (slash), - (dash), . (point), and , (comma).

These variables should be used with the Data Type Identifier.

*add_product add $SPEECHLY.SMALL_NUMBER(amount) units of $SPEECHLY.IDENTIFIER_MEDIUM(product_id)

The example utterance above — with the entity amount defined as the Data Type Number, and the entity product_id as the Data Type Identifier — would recognize the utterance “Add five units of a b one two three slash x," and parse amount with the value of 5 and product_id with the value of AB123/X.

Should your configuration include identifiers that are more than 12 characters in length, you can combine any of the abovementioned Standard Variables in the following fashion:

my_super_long_identifier = $SPEECHLY.IDENTIFIER_LONG $SPEECHLY.IDENTIFIER_LONG

Now, my_super_long_identifier supports identifiers that are up to 24 characters in length. However, do keep in mind that spelling out very long character sequences might not be that easy for your users.

Also, it is good to be aware that some letters and digits are phonetically very close to one another. For example, the letters A and H can be easily confused with the digit 8. To help avoid such problems, the Standard Variables that represent identifiers also have support for the International Radiotelephony Spelling Alphabet (also known as the NATO phonetic alphabet): Alfa, Bravo, Charlie, Delta, Echo, Foxtrot, Golf, Hotel, India, Juliett, Kilo, Lima, Mike, November, Oscar, Papa, Quebec, Romeo, Sierra, Tango, Uniform, Victor, Whiskey, X-ray, Yankee, and Zulu. Thereby, an identifier uttered using the NATO phonetic alphabet, for instance, “charlie delta echo bravo one point five," would thus be parsed as CDEB1.5.