<grammar>

Specifies a speech-recognition grammar.

Syntax

<grammar
src="URI"       srcexpr="js_expression"       expr="js_expression"	Only to point to an external or built-in grammar
mode="voice"|"dtmf"       root="string"       tag-format="URI"       version="version_number"       xml:base="URI"       xml:lang="lang"	Only for an XML grammar allowed inline and in grammar file
xmlns="URI"       xmlns:xsi="URI"       xsi:schemaLocation="URI"	Only in an external XML grammar file
scope="document"|"dialog"       type="MIME_type"       universal="string"	Allowed for all grammars,  except references to built-in grammars
fetchhint="prefetch"|"safe"       fetchtimeout="time_interval"       maxage="time_interval"       maxstale="time_interval"	Allowed for external grammars
weight="N"	Not implemented
>    Optional Inline Grammar </grammar>

Description

Specifies a grammar to be used within some VoiceXML tag such as <field>, <form>, or <link>. When the speech-recognition engine detects a match with a grammar, it may cause a transition to another dialog (if the grammar is in a menu item or link) or assign a return value to assign to an input variable (if the grammar is in a form or input item).

The <grammar> element serves two primary purposes:

(VoiceXML 1.0 only) The following attributes can be used in applications in which the version attribute of the <vxml> tag is set to 1.0.

Attribute	Description
caching	VoiceXML 1.0 only. Specifies the caching policy for the resource being fetched. See Caching. Optional. Used in place of the VoiceXML 2.0 attributes maxage and maxstale.

Multiple grammars may be active at the same time. When the speech-recognition engine detects a match from a higher level, control is passed to that grammar's parent element.

Grammar Formats.

BeVocal VoiceXML supports the W3C specification, Speech Recognition Grammar Format, which defines an XML Grammar and an ABNF Grammar. The VoiceXML 2.0 specification defines the XML grammar as a must support, and the ABNF Grammar as a should support. It is expected that many VoiceXML developers will use ABNF because it is more readable and concise.

BeVocal VoiceXML additionally supports the Java JSGF format (used as examples in the VoiceXML 1.0 draft) and the Nuance GSL Grammar format.

See the following for details:

Compiled Grammars

You may refer to a compiled GSL grammar using the src attribute of the <grammar> tag; for example:

 <grammar src="compiled:/key"/>

However, if you want to combine a compiled grammar in a more complex way with another grammar, you can refer to a compiled grammar from within an ABNF grammar:

 <grammar>
   <![CDATA[
     #ABNF 1.0 en-US;
     root $script;
     $script = prescription $<compiled:/key>;
   ]]>
 </grammar>

Using the Grammar Compiler tool on the BeVocal Café, you can compile a grammar and receive an associated key. For information on compiling grammars, see Chapter 7, "Grammar Compiler" in Using the BeVocal Café Tools.

Built-in Grammars

The VoiceXML 2.0 specification (Appendix P) includes a set of built-in grammars as a convenience to enable developers to get started writing more complex VoiceXML applications quickly. Some of the basic built-in grammars such as date and time are actually difficult to write and tune by hand, but are very useful in many applications. The basic built-in grammars are:

Grammar Type	Description
boolean	Recognizes a positive or negative response.
currency	Recognizes an amount 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.
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, such as IBM or CSCO.
citystate	Recognizes US city and state names, for example, "Sunnyvale, California".
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 street number.

Note that built-in grammars can be used where other grammars are used, commonly either in fields or in forms.

A built-in grammar can be specified using the syntax:

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

For example the phone type is specified using:

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

Most built-in grammars, such as phone, fill a single slot whose name is the same as the grammar name. For example, the date grammar fills a slot named date. However, some of the more complex grammars fill in multiple slots, for example airline fills in code and name.

Standard built-in dtmf-only grammars can be specified using the syntax:

 <grammar src="builtin:dtmf/type"> 

Currently, the boolean, digits, number, and date built-in grammars are supported for dtmf-only. For other buil-tin grammars, such as phone, currency, and time, a warning is thrown that the dtmf-only version is not supported, and the regular grammar (voice and dtmf) is used. Other built-in grammars may be supported as dtmf-only in a future release.

Built-in Grammars--Fields and Forms

If the built-in grammar is used as a field grammar, the input variable is set to the slot value.

If the built-in grammar fills multiple slots:

For more details, see Chapter 1, "Using VoiceXML Grammars" in the Grammar Reference.

Built-in Grammars--Multiple Slots

The following table lists the slots for the extended built-in grammars which return multiple slots. In the case of using a built-in grammar in a <field> element, these are the properties of the field's item variable which are assigned the slot values.

Field Type	Slots (or 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.
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.
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.

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>

Built-in Grammars--Parameters

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 and streetaddress built-in grammars; 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 minimum number of digits in a valid utterance.  •  maxlength--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 value is 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">

Built-in Extended Grammars--Input

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

Grammar Type	Example Inputs
airport	San Jose DFW
airline	American UA
equity	Cisco ORCL
stockindex	Nasdaq
street	Bordeaux Drive
streetaddress	1380 Bordeaux Drive
citystate	Sunnyvale, California

Built-in Extended Grammars--Output.

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

	Tip:
	•  If a JavaScript expression contains any of the characters "<", ">", or "&", that character must be replaced with the corresponding escape sequence "&lt;", "&gt;", or "&amp;". For more information, see JavaScript Quick Reference.

Usage

Parents	Children
<bevocal:listen> <bevocal:register> <bevocal:verify> <choice> <field> <form> <link> <record> <transfer>	<lexicon> <metadata> <rule>

See Also

Examples

Different grammar formats.

XML Grammar - DTMF Recognition

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form>
     <field name="pin">
       What is your pin?
       <grammar mode="dtmf" root="pin" version="1.0">
         <rule id="digit">
           <one-of>
             <item> 0 </item>
             <item> 1 </item>
             <item> 2 </item>
             <item> 3 </item>
             <item> 4 </item>
             <item> 5 </item>
             <item> 6 </item>
             <item> 7 </item>
             <item> 8 </item>
             <item> 9 </item>
           </one-of>
         </rule>
 
         <rule id="pin" scope="public">
           <item repeat="4"><ruleref uri="#digit"/></item>
         </rule>
       </grammar>
 
       <filled>
         You entered <value expr="pin"/>
       </filled>
     </field>
   </form>
 </vxml>  

XML Grammar - Voice Recognition

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form>
     <field name="pin">
       What is your pin?
 
       <grammar mode="voice" root="pin" version="1.0">
         <rule id="digit">
           <one-of>
             <item> 0 </item>
             <item> 1 </item>
             <item> 2 </item>
             <item> 3 </item>
             <item> 4 </item>
             <item> 5 </item>
             <item> 6 </item>
             <item> 7 </item>
             <item> 8 </item>
             <item> 9 </item>
           </one-of>
         </rule>
 
         <rule id="pin" scope="public">
           <item repeat="4"><ruleref uri="#digit"/></item>
         </rule>
       </grammar>
 
       <filled>
         You said <value expr="pin"/>
       </filled>
     </field>
   </form>
 </vxml>  

ABNF Grammar - DTMF Recognition

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form>
     <field name="pin">
       What is your pin?
       <grammar type="application/grammar">
         <![CDATA[
           #ABNF 1.0;
           mode dtmf;
           root $pin;
           $digit = ( 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9);
           $pin = $digit<4> ;
         ]]>
       </grammar>
 
       <filled>
         You said <value expr="pin"/>
       </filled>
     </field>
   </form>
 </vxml>  

ABNF Grammar - Voice Recognition

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form>
     <field name="pin">
       What is your pin?
       <grammar type="application/grammar">
         <![CDATA[
           #ABNF 1.0;
           root $pin;
           $digit = ( 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9);
           $pin = $digit<4> ;
         ]]>
       </grammar>
 
       <filled>
         You said <value expr="pin"/>
       </filled>
     </field>
   </form>
 </vxml>  

GSL Grammar - DTMF Recognition

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form>
     <field name="pin">
       What is your pin?
       <grammar type="application/x-nuance-gsl">
         FourDigits (Digit Digit Digit Digit)
         Digit [dtmf-1 dtmf-2 dtmf-3 dtmf-4 dtmf-5 dtmf-6 dtmf-7 dtmf-8 dtmf-9 
dtmf-0]
       </grammar>
 
       <filled>
         You said <value expr="pin"/>
       </filled>
     </field>
   </form>
 </vxml>  

GSL Grammar - Voice Recognition

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form>
     <field name="pin">
       What is your pin?
       <grammar type="application/x-nuance-gsl">
         FourDigits (Digit Digit Digit Digit)
         Digit [1 2 3 4 5 6 7 8 9 0]
       </grammar>
 
       <filled>
         You said <value expr="pin"/>
       </filled>
     </field>
   </form>
 </vxml>  

JSGF Grammar - Voice Recognition

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form>
     <field name="pin">
       What is your pin?
       <grammar>
         <![CDATA[
           #JSGF 1.0;
           grammar pin;
           <digit> = ( 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9);
           public <pin> = <digit> <digit> <digit> <digit>;
         ]]>
       </grammar>
 
       <filled>
         You said <value expr="pin"/>
       </filled>
     </field>
   </form>
 </vxml>  

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