Built-in grammars

Each language supported by Recognizer comes with predefined built-in speech and DTMF grammars. You can activate these grammars individually, and you can import them into other grammars. Built-in grammars can serve many purposes:

  • To supply typical grammars that are often needed in voice applications.
  • To provide extra functionality for improving accuracy and performance.
  • To tune special-purpose grammars for specific tasks.

The source code of built-in grammars is provided during installation, so you can customize these grammars if necessary.

The built-in grammars available vary for each language. For example, many countries use local formats for postal codes, identification numbers, and other information. The language packs for the corresponding languages will often contain built-in grammars designed to recognize these local formats (see Country-specific built-ins).

A list of built-ins for each supported language can be found in the Language Supplement documents for the languages you install. The Language Supplement documents appear in:

%SWISRSDK%\documentation\languages\

Before planning to use a built-in, check the supplement to verify that the grammar is available in the language you’re using. Some built-ins are not available for all languages, and some languages have additional grammars that are not described here.

The language supplements discuss:

  • The built-in grammars available for the language.
  • Speech utterances recognized by each grammar.
  • Return keys (with example values) returned to the application.
  • Configuration properties for each grammar (for example, a default currency or a constrained date range).

Standard built-ins

The following built-ins are mentioned in the VoiceXML specification:

  • Boolean: The boolean built-in grammar accepts an affirmative or negative reply from the caller: “yes”, “no”, “true”, “false”, and so on. When invoking this grammar you can use URI parameters to assign any two touchtone buttons as synonyms for yes and no. This grammar returns a MEANING with a value of "true" or "false", and the SWI_literal key.
  • Currency: The currency built-in grammar accepts currency amounts appropriate to the current language. The grammar can be constrained to accept only those amounts that fall within a given range or with certain multipliers (tens, hundreds, thousands, and so on).

    The Nuance implementation of currency includes the following features:

    • It allows values up to 999,999,999.99.
    • In a DTMF grammar, a caller can press the star (*) key on the telephone keypad to indicate a decimal point.

    This built-in returns SWI_literal, and a MEANING in the following basic format:

    main_unit_amount.subunit_amount>

    Where main_unit_amount is the amount of the primary unit of currency (such as dollars), and subunit_amount is an amount measured in subdivisions of the main currency (such as cents). If the caller does not specify an amount for one of these fields, it is assigned a value of zero. This means that the built-in can accept amounts like “six dollars” or “forty-one cents”.

    For some languages, the currency built-in may return the main unit of currency. It may also return an AMBIGUOUS key with a switch to indicate that the caller’s statement can be interpreted in more than one way. For example, “twelve fifteen” may mean twelve dollars and fifteen cents ($12.15), or one thousand two hundred and fifteen dollars ($1215.00).

  • Date: The date built-in grammar accepts dates spoken in various formats, and returns SWI_literal and a MEANING with the date in a standard YYYYMMDD format. It may also return keys for the weekday, and for sub-divisions of the date: the century, two-digit year, month, or day. It can be constrained to allow only those dates that fall within a given range in the past, present, or future.
  • Digits: The digits built-in grammar recognizes digit strings of up to 20 digits. It can be constrained to accept a specific list of valid strings, or a specific number of random digits. Punctuation characters such as hyphens (-), dots (.), and underscores (_) are not recognized. If spoken, they reduce recognition accuracy.

    It is strongly recommended that you use the length parameter or minlength and maxlength parameters to constrain this grammar, as doing so improves accuracy.

    This grammar returns SWI_literal, and a MEANING key that contains a string of digits with no embedded spaces, such as "12345”.

  • Number: The number grammar recognizes spoken numbers: that is, numbers expressed as words rather than as a digit string—“four hundred fifty-three” rather than “four five three”. This grammar will accept decimal places up to a specified limit, and can be constrained to various ranges and multipliers (tens, hundreds, thousands, and so on).

    This grammar returns SWI_literal and a MEANING with digits with no embedded spaces, with or without decimals ("12345.678").

  • Phone: The phone built-in grammar accepts local and long distance telephone numbers, as well as variations for special numbers (for example, “911” for emergency in US English). The grammar accepts extension numbers if needed, and can limit the length of these extension numbers to a set number of digits.

    This grammar returns SWI_literal, and a MEANING key containing the phone number as a string of digits with no embedded spaces or punctuation. The number of digits in the string depends on the local standards.

  • Time: The time built-in grammar recognizes a spoken time of day. It can accept times expressed in the twelve-hour am/pm clock, or the 24 hour clock, and further accepts qualifiers, such as “before” or “about”. This grammar can be constrained to recognize ranges of time in the past, present, or future. Also, it can be constrained to recognize only specific increments of time (minutes, quarter hours, half hours, three quarter hours, hours, and so on).

    The MEANING key of this grammar returns a time in HHMMP format, where:

    • HH is the hour
    • MM is the number of minutes
    • P indicates whether the time is am, pm, or on the 24-hour clock.

    This grammar may also return keys that subdivide the time into its components (as listed above: hours, minutes, and am/pm or 24-hour), and a qualifier if that has been specified by the caller (“approx”, “exact”, “before”, or “after”).

Common extensions

The following built-in grammars are not listed in the VoiceXML specification. However, since they can often be useful, many language packs include them.

  • alphanum_lc grammar: The alphanum_lc built-in grammar recognizes a connected alphanumeric string, such as “abc123”. For example, it can be used to spell a person’s name, or to recognize a product number that contains both letters and digits. This grammar requires lowercase input only and replaces the old alphanum grammar; alphanum_lc has better accuracy than alphanum.

    The grammar returns SWI_literal, and a MEANING text containing the alphanumeric string, with no embedded spaces.

    Note: Many languages also support a separate Credit Card built-in grammar, as described below.

    It is strongly recommended that you use the entries parameter to specify a constraint list for use with this grammar. See Constraint lists.

  • ccexpdate grammar: The ccexpdate grammar understands the expiration date on a credit card. These dates generally omit the day, listing only the month and year. The grammar returns SWI_literal and the date in YYYYMMDD format (the date is the last day of the month). If the caller specifies the day, the grammar accepts the utterance but automatically assigns the last day in that month, even if the caller specified a different day.
  • creditcard grammar:The creditcard grammar understands a caller saying a credit card number, optionally preceding the number with the credit card name. It returns SWI_literal and a MEANING text string with the recognized card number. The grammar also returns a CARDTYPE key identifying the type of credit card (Visa, American Express, and so on), based on the first digit in the card number. This grammar can be constrained to accept specific types of credit cards.
  • postcode/zipcode grammar: Many languages have country-specific versions of postal code grammars. For example, when the language is US English, the zipcode grammar recognizes United States ZIP Codes in either five- or nine-digit format. These grammars return the SWI_literal key, and a MEANING text string for the code in whatever format is appropriate for the local postal services. The grammars do not perform extensive validity checking, and your application needs to handle codes that do not exist. For example 99999 matches the five-digit format but is not a valid code.
  • alphanum grammar: Use alphanum_lc instead. The alphanum built-in grammar recognizes a connected alphanumeric string, which can include uppercase and lowercase characters, such as “aBc123”.

Country-specific built-ins

Many countries use local formats for identification numbers and similar information. The language packs for the corresponding languages will often contain built-in grammars designed to recognize these local formats.

Specific information, examples, and instructions for using these grammars can be found in their corresponding language pack Language Supplement.

  • Australian Business Number: The en-AU language includes an ABN grammar that recognizes an Australian Business Number. This is an eleven-digit unique identifier that businesses use in dealings with the Australian Taxation Office or with other businesses.
  • CitizenID: The citizenid grammar for the ko-DR language recognizes Korean citizen identification numbers.
  • Customer Reference Number: The en-AU language includes a CRN grammar, which recognizes the unique Customer Reference Number identifier that Australian businesses assign to their customers. The CRN is typically used for electronic bill payments and other transactions. The advantage of using this built-in instead of digits is that it uses a checksum to boost accuracy.
  • National Insurance Number: The en-GB language includes a national_insurance grammar, which recognizes UK citizens’ national insurance numbers.
  • Socialsecurity: The en-US language includes a socialsecurity grammar, which recognizes 9-digit US Social Security numbers.

Universals

Recognizer also provides several universal built-in grammars for general use within an application. These universal grammars are not translated in language packs. To use them in a language other than US English, you must modify them.

The universal built-in grammars are:

  • cancel: Recognizes a request to cancel the previous transaction.
  • exit: Recognizes a request to exit the voice application.
  • help: Recognizes a request for help or more information.
  • operator: Recognizes a request to be transferred to a live operator.

These universal grammars will only recognize the caller’s request, not perform it. To carry out any of these actions, you must provide the appropriate instructions in the main VoiceXML document of your application.

By default, universals are disabled. To use universals, you must enable them using the universals VoiceXML property.

Using built-ins

Like developer-created grammars, built-in grammars can be invoked in a VoiceXML document, or imported into a GrXML grammar. When recognition occurs, the built-in grammar returns standard keys that can be used to fill variables in the main application.

The basic format for a built-in URI is:

builtin:type/name?language=langcode;parameter1=value1;parameter2=value2

In this format:

  • type specifies whether the grammar is a speech grammar (grammar) or DTMF (dtmf).
  • name is the name of the built-in grammar.
  • langcode specifies the language (see Controlling languages in a grammar).
  • parameter1=value1 and parameter2=value2 are constraints to be applied to the built-in grammar (see Constraints), or other applicable parameters.

For example, in a VoiceXML document you could invoke the digits built-in as follows:

<field name="accountNum">
    <prompt>What is your seven-digit account number?</prompt>
    <grammar src="builtin:grammar/digits?language=en-US;length=7"/>
</field>

Alternatively, you could use the type attribute of <field> to specify the built-in:

<field name="accountNum" type="digits?language=en-US;length=7">
    <prompt>What is your seven-digit account number?</prompt>
</field>

Note that this second example omits the first part of the URI ("builtin:grammar/”). Only the name of the built-in is required, along with any applicable parameters.

Finally, you can import built-in grammars into a GrXML external grammar with a <ruleref> element as normal: 

<?xml version='1.0' encoding='UTF-8'?>
<grammar xml:lang="en-US" version="1.0" root="ROOT"
    tag-format="swi-semantics/1.0"
    xmlns="http://www.w3.org/2001/06/grammar">
    <rule id="ROOT" scope="public">
      <ruleref uri="builtin:grammar/digits?language=en-US;length=7"/>
        <tag>custnumber=_digits.MEANING </tag>
    </rule>
</grammar>

See Issues in importing grammars and Importing built-in grammars for a discussion of the possible pitfalls when importing a grammar using <ruleref>.

In general, both the speech and the DTMF version (if available) of a built-in grammar allow the same parameters. For examples, see the Language Supplement for your language.

The use of parameters is optional, although some parameters are strongly recommended to improve the performance of certain built-ins such as digits and alphanum_lc.

The language code parameter is not required. If you omit the language of the imported built-in, Recognizer uses the current language from the importing document. If there is no scoped language (that is, if the main grammar is DTMF), the built-in inherits the language from the swirec_language property (if declared) or from the voice platform default.

Many built-in grammars use parameters as constraints to limit the responses that will be accepted. For example, you can use constraints to limit acceptable dates to those in the future, or to place a limit on the amount of money that can be handled in a voice transaction, or to accept credit card numbers from a known list.

Constraints improve recognition accuracy by filtering invalid responses at the recognition stage of your application. They avoid false acceptances, and save time and CPU cycles. For many cases, such as the digits, alphanum_lc, and creditcard built-in grammars, this improvement is so significant that the use of constraints is strongly recommended.

There are two methods for applying constraints to a built-in grammar:

  • URI parameters: You can add simple constraints to the URI used to invoke the built-in by using a question mark followed by param=value pairs separated with semi-colons. For example, the URI below accepts only those currency values that fall between 100 and 2000 units (in US English, the units would be dollars): 
    builtin:grammar/currency?minallowed=100;maxallowed=2000;

    The parameters available depend on the grammar. Parameters for each built-in grammar are described in the appropriate Language Supplement.

  • Constraint lists: a constraint list is a text file that explicitly defines all values to be accepted when using the grammar. A result that doesn’t appear in the list is rejected, even if it would normally be covered by the grammar. 
    builtin:grammar/alphanum_lc?entries=http://myserver/customer_ids.txt;

    See Constraint lists.

A built-in grammar may return several different keys to the main application each time the built-in is invoked. These keys are listed in the Language Supplement document for the language. The two most common keys are:

  • MEANING: Returns a result in a format appropriate for the subject of the grammar, which can be slotted into a variable in the main application.
  • SWI_literal: Returns the exact text of the words that the recognition engine extracted from the utterance.

Other keys available depend on the specific built-in grammar.

When you invoke a built-in in a VoiceXML element, the built-in automatically stores the MEANING in the field variable. For example, the following code assigns the MEANING returned by the US English zipcode built-in to the zipc field variable: 

<field name="zipc" type="zipcode">
    <prompt>What is your zip code?</prompt>
    <filled>
        <prompt>Your zip code is <say-as interpret-as="zip">
        <value expr="zipc"/></say-as></prompt>
        <goto next="#done"/>
    </filled>
</field>

This assignment also happens when you use a <grammar> element to invoke the built-in:

<field name="zipc">
    <prompt>What is your zip code?</prompt>
    <grammar src="builtin:grammar/zipcode"/>
    <filled>
        <prompt>Your zip code is <say-as interpret-as="zip">
        <value expr="zipc"/></say-as></prompt>
        <goto next="#done"/>
    </filled>
</field>

However, when you use a built-in within a GrXML grammar, you must use a <tag> element to assign the value: 

<rule id="zipcode" scope="public">
    <ruleref uri="builtin:grammar/zipcode?language=en-US" />
    <tag>zipc=_zipcode.MEANING </tag>
        shares of 
    <ruleref uri="#MyFavoriteStocks"/> 
</rule>

The matching <tag> element specifies the returned value to be assigned by prefixing the built-in’s name with an underscore (_zipcode.MEANING above). You can use this convention to extract the values of return keys other than MEANING.

Typically, errors in your syntax are revealed during compilation, but this cannot be guaranteed. Errors that may not be evident until runtime can include:

  • Parameters that are specified twice with different values. The error might arise during compilation or at runtime. These have undefined error behavior.
  • Values that are out-of-range or of the wrong data type often lead to a runtime error. For example, this can occur if you specify a float value where an integer is expected.
  • Values that are invalid with relation to other values (for example, a maximum value below the minimum value) are usually caught during grammar compilation. However, these errors cannot be detected at compilation time when the URI contradicts a default that is hard-coded in the built-in—for example, if a parameter sets a minimum value of some range, and that value exceeds the default maximum.

Tip: Again, see Issues in importing grammars and Importing built-in grammars for a discussion of the errors to avoid when you import a built-in grammar into a GrXML grammar using the <ruleref> element.

Built-ins and Nuance Dialog Modules

The built-in field types available in a <field> block can be mapped to corresponding Nuance Dialog Modules as follows:

W3C grammar type

Nuance Dialog Modules

boolean

YesNo

currency

Currency

date

Date

digits

Digits

number

NaturalNumbers. In addition, the number grammar specifies decimal numbers (for example, “five point seven”).

phone

Phone

time

TimeOfDay

Customizing sources of built-in grammars

Recognizer provides the source code format for built-in grammars. This allows you to copy and modify the built-in grammars. The grammars are installed in this path: 

<installation_path>\config\<language_code>\sources

However, copying the sources does not copy all features associated with the grammars. Recognizer performs additional computations for some built-ins that are unavailable when you make your own versions of the grammars:

  • alphanum_lc: The entries constraint is not part of the built-in source.
  • digits: These constraints are not part of the built-in source: entries, length, minlength, and maxlength.
  • dtmf/boolean: The y and n constraints are not part of the built-in source (the source grammar has no way to define which touchtones equal yes and no.
  • dtmf/digits: These constraints are not part of the built-in source: length, minlength, and maxlength.

It is often easier to activate a parallel grammar with the additions than to modify the built-in. For example, to collect a date and also recognize “Christmas” to mean “December 25, 2009”, you could activate the date built-in plus a second grammar that allows “Christmas” with MEANING set to 20091225.