2   Using Built-in Grammars

The VoiceXML 2.0 specification includes a set of built-in grammars as a convenience to enable developers to get started writing more complex VoiceXML applications quickly. The following basic grammars are built into all standard VoiceXML interpreters:

Grammar Type	Description
boolean	Recognizes a positive or negative response.
currency	Recognizes an amounts of money, in dollars.
date	Recognizes a calendar date.
digits	Recognizes a sequence of digits.
number	Recognizes a number.
phone	Recognizes a telephone number adhering to the North American Dialing Plan (with no extension).
time	Recognizes a clock time.

Note: All standard built-in grammars are supported in the Spanish language. Currently there are no extended built-in grammars for Spanish. Neither standard nor extended built-in grammars are currently supported in French Canadian. All extended built-in grammars are supported only in English. If you specify a language other than English and refer to an unsupported built-in grammar, a parse error error.unsupported.builtin is thrown.

In addition, BeVocal VoiceXML contains a set of extended built-in grammars, so VoiceXML developers can reference these quite complex grammars which have been tuned over the years by caller usage. The extended grammars are:

Grammar Type	Description
airport	Recognizes an airport name or code, such as DFW or Dallas-Fort Worth
airline	Recognizes an airline name or code, such as AA or American Airlines.
citystate	Recognizes US city and state names, for example, "Sunnyvale, California".
datetime	Recognizes a date and time. Please contact your BeVocal sales representative or sales@bevocal.com for further information on pricing and availability.
equity	Recognizes a company symbol or full name, such as IBM or Cisco Systems.
stockindex	Recognizes the names of the major US stock indexes, such as "Nasdaq".
street	Recognizes a street name (with or without street number).
streetaddress	Recognizes a street name and a street number.

Referencing a Built-in Grammar

You can reference a built-in grammar in one of following ways:

builtin:grammar/typeName 
builtin:grammar/typeName?parameters 

<grammar src="builtin:grammar/number" />

builtin:dtmf/type 

<var name="numgram" value="'builtin:grammar/number'" />
<grammar expr="numgram" />

<field name="num" type="number"> 

Semantic Interpretations

See Setting Input Variables for a general description of how the interpreter uses recognition results to fill input variables. Most built-in grammars, such as phone, return a simple text string, which is used to fill a single slot whose name is the same as the grammar name. For example, the date grammar sets a slot named date. However, some of the more complex grammars provide a semantic interpretation that can fill in multiple slots; for example, airline sets code and name.

The following table lists the properties for the extended built-in grammars which provide a complex semantic interpretation.

Field Type	Properties
airport	•  code--Code of the airport, such as DFW. For a list of known airport codes, see Airport & Airline Codes on the Resources page of the BeVocal Café web site.  •  spokencity--The city that was spoken, such as dallas. This slot is only returned if a domestic (US) airport is being recognized.  •  airportcity--The airport city for the recognized airport, such as ft. worth  •  state--The two-letter abbreviation for the state, such as CA.  •  country--The country where the airport is located, such as united states of america.
airline	•  code--The airline's identifying code, such as AS. For a list of known airline codes, see Airport & Airline Codes.  •  name--Full name of the airline, such as Alaska Airlines.
citystate	•  city--The city, such as Sunnyvale.  •  county--The county in which the city is located, such as Santa Clara.  •  state--The two-letter abbreviation for the state, such as CA.  •  datacity--If the city is unlikely to appear in data feeds for traffic, weather, and so on (for example, because it is tiny or unincorporated), the name of an adjacent city that is more likely to work with data feeds. In all other cases, this property is identical to the city property.
datetime	•  month--The month for this date/time.  •  day--The day for this date/time  •  time_hours--The hour value of the time  •  time_minutes--The minute value of the time  •  ampm--Whether the date/time is AM or PM.  •  timezone--The timezone associated with this datet/ime  •  duration_hours--The number of hours to the specified time  •  duration_minutes--The number of minutes to the specified time  •  dayofweek--The day of thw eek associated with this date/time The following examples show utterances and the corresponding slots that are filled: "tomorrow "  •  day = tomorrow "next monday"  •  dayofweek = monday "six o'clock central time"  •  time_hours = 6  •  time_minutes = 0  •  timezone = ct "four twenty-two p m on november thirtieth"  •  ampm = pm  •  day = 30  •  month = november  •  time_hours = 4  •  time_minutes = 22 "in one hour and fifteen minutes"  •  duration_hours = 1  •  duration_minutes = 15
equity	•  name--The name of the company, such as Cisco Systems.  •  symbol--Stock symbol, such as CSCO.
stockindex	•  name--The name of the index, such as Nasdaq Composite Index.  •  symbol--Symbol for the index, such as COMP.
street	(none)
streetaddress	•  streetname--The name of the street, such as Bordeaux Drive.  •  streetnumber--The number of the street, such as 1380.

A property is accessed with an expression of the form:

 fieldName.propertyName

For example the city property of a citystate field is accessed as follows:

 <field name="mycity">
   <grammar src="builtin:grammar/citystate"/>
   <filled>
     <prompt>The city is <value expr="mycity.city"/>
   </filled>
 </field>

Parameterizing Grammars

Two standard built-in grammars, digits and boolean, can be parameterized. Specifically, you can set limits on the length of a digit string, and you can set DTMF key presses to mean yes or no. In addition, you must specify the city and state with the street built-in grammar; you can optionally specify the county to disambiguate a case in which the state contains two cities with the same name.

The following table shows the built-in grammars that can be parameterized and indicates which parameters are required.

Grammar	Parameters
boolean	•  y--The DTMF key press for an affirmative answer.  •  n--The DTMF key press for a negative answer
digits	•  minlength--The maximum number of digits in a valid utterance.  •  length--The exact number of digits in a valid utterance. Note: If you do not specify length or maxlength, the built-in grammar accepts an infinite number of digits. You should use length or maxlength whenever you can; doing so usually results in more accurate speech recognition.
equity	symbol--When true, the grammar expects the input to be the stock symbol spelled-out, as in "eye" "bee" "emm" for IBM.
street	•  city--The city in which the street is located (required).  •  state--The two letter abbreviation for the state in which the specified city is located (required).  •  county--The county in which the specified city is located. If you omit the county and the city name is ambiguous, an error.badfetch event is thrown with a list of multiple possible counties in the error message. Note: An error.badfetch event is thrown if a required parameter is not specified, if the city is not a recognized city of the specified state, or if there is no street grammar for the specified city.
streetaddress	•  city--The city in which the street is located (required).  •  state--The two letter abbreviation for the state in which the specified city is located (required).  •  county--The county in which the specified city is located. If you omit the county and the city name is ambiguous, an error.badfetch event is thrown with a list of multiple possible counties in the error message. Note: An error.badfetch event is thrown if a required parameter is not specified, if the city is not a recognized city of the specified state, or if there is no street grammar for the specified city.
airport	•  domestic--If true, then the grammar recognizes only the major domestic (US) airports. If false, then it recognizes only the major international airports. If no parameter is specified, then this property defaults to true.

You express parameter information using URI-style query syntax of the form:

 builtin:grammar/typeName?parameter=value

For example, the grammar matches a sequence of exactly five digits:

 <grammar src="builtin:grammar/digits?length=5">

You can specify more than one parameter, separated by semicolons. For example, the following grammar allows a user to press 7 for an affirmative answer and 9 for a negative answer:

 <grammar src="builtin:grammar/boolean?y=7;n=9"/>

Note: The interpreter throws a error.badfetch event if it loads a VoiceXML file that contains a built-in grammar with an unrecognized parameter or with inconsistent parameters, such as:

 <!-- ERROR: Inconsistent parameters for built-in grammar-->
 <grammar src="builtin:grammar/digits?minlength=5;maxlength=1">

Extended Built-in Grammars

The following table shows example user inputs for each extended built-in grammar.

Grammar Type	Example Inputs
airport	San Jose DFW
airline	American UA
datetime	May 12 2:47pm
equity	Cisco ORCL
stockindex	Nasdaq
street	Bordeaux Drive
streetaddress	1380 Bordeaux Drive
citystate	Sunnyvale, California

In VoiceXML 2.0 the field's type attribute no longer defines an implicit <say-as> type to output the field's value. Instead it plays the value in normal TTS. You must now use the type attribute of <say-as> for a type-specific read-out of the value (in TTS).

The bevocal:mode attribute of <say-as> can be used to define recorded output for some types. See the <say-as> tag for details.

Grammar Type	Say-As Type	Audio Output	String Result
airport	airport	Airport name	Dallas Fort Worth International Airport (DFW)
airline	airline	Airline name	American Airlines (AA)
equity	equity	Company name	ORCL
stockindex	stockindex	Index name	Nasdaq Composite Index
street	street	Street name	Bordeaux Drive
streetaddress	address	Street number and name	1380 Bordeaux Drive
citystate	citystate	City State	Sunnyvale, CA

Café Home | Developer Agreement | Privacy Policy | Site Map | Terms & Conditions Part No. 520-0004-02 | © 1999-2007, BeVocal, Inc. All rights reserved | 1.877.33.VOCAL