grammar
grammar element
Specifies a permissible vocabulary for user interaction.
Syntax
<grammar
fetchhint = "string"
fetchtimeout = "string"
maxage = "seconds"
maxstale = "seconds"
mode = "string"
root = "string"
scope = "document_dialog"
src = "URI"
srcexpr = "ECMAScript_Expression"
tag-format = "string"
type = "encoding_type"
version = "string"
xml:base = "URI"
xml:lang = "string"
/>
Attributes
expr |
DEPRECATED. Use srcexpr instead. |
fetchhint |
Defines when the interpreter context may retrieve grammar files from the server.
prefetchGrammar files may be prefetched.
safeGrammar files may only be fetched when needed, never before.
|
fetchtimeout |
The time in seconds (s) or milliseconds (ms) for the VoiceXML interpreter to wait for content to be returned by the HTTP server before throwing an error.badfetch event. The fetchtimeout value is rounded down to the nearest whole second (e.g., 5700ms or 5.7s would be rounded down to 5s). If fetchtimeout has a value less than 1 second, it is reset to the default value. The default value is 15s. |
maxage |
Sends the max-age Cache-Control HTTP header along with the request for the specified resource. The header indicates that the document is willing to use content whose age is no greater than the specified time in seconds, unless maxstale is also provided. Voice application developers should use extreme caution when setting this attribute. If used improperly, it could have an adverse affect on the performance of your application. You should only consider using this attribute in requests for frequently changing content (e.g. dynamically generated content) hosted on a misconfigured HTTP server that you do not control. To reduce load, some HTTP servers are configured to indicate to clients that content expires some arbitrary time in the future. In that case, set the maxage attribute to 0. If you do control the HTTP server, you should instead configure the HTTP server to omit the expires header and possibly to send the Cache-Control: no-cache header. The former requires the VoiceXML interpreter to check with the server before using any cached content. The latter requires the VoiceXML interpreter to not cache the fetched resource. |
maxstale |
Instructs the VoiceXML interpreter to send a max-stale Cache-Control header aong with the HTTP request for the specified resource. The header indicates that the document is willing to use content that has exceeded its expiration time by no more than the specified number of seconds. Voice application developers should use extreme caution when setting this attribute. If used improperly, your application may present stale content to users. If you do control the HTTP server, you should instead configure the HTTP server to send an expires header with a time in the distant future. |
mode |
Provides a hint to the interpreter regarding the mode of the contained grammar. Omitting the attribute indicates that the grammar contains both speech and DTMF values. To control what type of input the speech system will accept, use the inputmodes property.
dtmfThe grammar contains values for DTMF input only. Specifying "dtmf" on a DTMF-only grammar bypasses the speech system and results in increased performance.
voiceThe grammar contains values for speech input only.
|
root |
Required. Specifies the grammar rule to activate. |
scope |
The scope of the form-level grammar. This attribute overrides the value set by a form or menu element. |
src |
The URI of an external grammar file. |
srcexpr |
An ECMAScript expression that evaluates to the URI of a grammar. Each time the VoiceXML interpreter is about to wait for user input, it evaluates the expression if the grammar is active. |
tag-format |
Specifies the content format for all tags within the grammar.
semantics/1.0Defines the content of tags to be ECMAScript.
semantics/1.0-literalsDefines the content of tags to be strings.
|
type |
The MIME type of the grammar. If unspecified, the platform tries to determine the type dynamically.
application/srgs+xml The grammar is in the XML-based Speech Recognition Grammar Specification (SRGS).
|
version |
Required. The version of the grammar specification. This should be set to "1.0". |
xml:base |
The base URI used to resolve relative references within the document. |
xml:lang |
The language and locale type for this grammar as defined in RFC 3066. If xml:lang is not specified, the value is inherited from the document hierarchy. |
Parents
choice, field, form, link, record, transfer
Children
None.
Remarks
The grammar element lets you define an inline grammar or reference a built-in or external grammar. An inline grammar is a list of phrases and subgrammars included within the grammar element. You can define any number of inline grammars using SRGS syntax.
A grammar contained by the link element must be defined inline.
The attributes of the VoiceXML grammar element for an inline grammar are slightly different than the SRGS grammar element specified in an external grammar. For example, the VoiceXML grammar element does not include an xmlns attribute.
Grammars are cached based upon their URI. If a grammar's srcexpr attribute evaluates to a URI that exists in the grammar cache, the cached copy is used so long as it hasn't expired and the HTTP server reports that it doesn't have a newer version.
Gain additional performance by placing your grammars inline or by configuring your Web server to set the expires HTTP header on your grammars to a date in the distant future. Doing so allows the VoiceXML interpreter to eliminate querying the Web server for the last modification time of the grammar.
The src and srcexpr attributes are mutually exclusive.
If you do not specify a scope for a grammar, the scope is determined by its parent element. The scope attribute is only valid on grammars contained directly by a form.
If any of the fetchtimeout, fetchhint, maxage, or maxstale attributes is not specified for a grammar element, then the value of the fetchtimeout, grammarfetchhint, grammarmaxage, or grammarmaxstale property, respectively, is used.
Prior to Revision 3, if you set the mode attribute to "voice", it is treated the same as if you had omitted the attribute. That is, the grammar is considered to contain both speech and DTMF values. In Revision 3 and later, if you set mode to "voice", only speech input is recognized against that grammar.
Prior to Revision 3, if a referenced grammar is empty, it is silently ignored. In Revision 3 and later, the interpreter throws error.badfetch.
Prior to Revision 3, if a grammar element contains a type attribute that specifies an unknown format, the VoiceXML interpreter throws error.badfetch. In Revision 3 and later, the interpreter throws error.unsupported.format.
Prior to Revision 3, if a scope attribute is specified for a grammar element that is a child of anything other than a form element, it is ignored. In Revision 3 and later, in that situation the VoiceXML interpreter throws error.badfetch to the calling document.
Prior to Revision 3, if a grammar for a form item contains no explicit result, but the caller says something that matches the grammar, the filled element is not executed. The prompt is immediately reexecuted. In Revision 3 and later, the VoiceXML platform uses the raw text string for the utterance as the result.
Examples
Note that these examples are external grammars. To include them as an inline grammar within a VoiceXML document, remove the "<?xml ... ?>" and "xmlns=..." lines.
The following example defines a simple SRGS grammar that allows the user to specify a company department. Each department name maps to a three-digit department number. For example, the grammar returns the string "010" if the user says "sales". The grammar returns "040" if the user says "public relations" or "p r".
<?xml version= "1.0"?>
<grammar mode="voice"
type="application/srgs+xml"
root="root_rule"
tag-format="semantics/1.0"
version="1.0"
xml:lang="en-US"
xmlns="http://www.w3.org/2001/06/grammar">
<rule id="root_rule" scope="public">
<one-of>
<item>
<one-of>
<item>
sales
</item>
</one-of>
<tag>out.dept = "010";</tag>
</item>
<item>
<one-of>
<item>
marketing
</item>
</one-of>
<tag>out.dept = "020";</tag>
</item>
<item>
<one-of>
<item>
engineering
</item>
</one-of>
<tag>out.dept = "030";</tag>
</item>
<item>
<one-of>
<item>
public relations
</item>
<item>
p r
</item>
</one-of>
<tag>out.dept = "040";</tag>
</item>
</one-of>
</rule>
</grammar>
The following example defines a SRGS grammar that allows the user to confirm or deny a request. For example, the grammar returns the string "yes" if the user says "yes", "yup", or "you got it" and returns the string "no" if the user says "no", "nope", or "no way."
<?xml version= "1.0"?>
<grammar mode="voice"
root="root_rule"
tag-format="semantics/1.0"
version="1.0"
xml:lang="en-US"
xmlns="http://www.w3.org/2001/06/grammar">
<rule id="root_rule" scope="public">
<tag>str = "";</tag>
<item>
<one-of>
<item>
<ruleref uri="#LIB_YES_NO"/>
<tag>str = rules.latest();</tag>
</item>
</one-of>
<tag>out = str;</tag>
</item>
</rule>
<rule id="LIB_YES_NO" scope="private">
<one-of>
<item>
<one-of>
<item>
yes
</item>
<item>
yeah
</item>
<item>
yup
</item>
<item>
sure
</item>
<item>
okay
</item>
<item>
correct
</item>
<item>
right
</item>
<item>
<item repeat="0-1">
<item repeat="0-1">
yes
</item>
that's
</item>
<one-of>
<item>
right
</item>
<item>
correct
</item>
</one-of>
</item>
<item>
<item repeat="0-1">
yes
</item>
it is
</item>
<item>
you got it
</item>
<item>
yes i do
</item>
<item>
yes i would
</item>
<item>
yes it is correct
</item>
</one-of>
<tag>out = "yes";</tag>
</item>
<item>
<one-of>
<item>
no
</item>
<item>
nope
</item>
<item>
incorrect
</item>
<item>
no way
</item>
<item>
no it isn't
</item>
<item>
<item repeat="0-1">
no
</item>
<one-of>
<item>
it's
</item>
<item>
that's
</item>
</one-of>
not
<one-of>
<item>
correct
</item>
<item>
right
</item>
</one-of>
</item>
<item>
<item repeat="0-1">
no
</item>
it isn't
</item>
<item>
<item repeat="0-1">
no
</item>
it is not
</item>
<item>
<item repeat="0-1">
no
</item>
it's not
</item>
<item>
no i don't
</item>
<item>
no i do not
</item>
<item>
no i wouldn't
</item>
</one-of>
<tag>out = "no";</tag>
</item>
</one-of>
</rule>
</grammar>
The following example defines a city/state grammar in SRGS that allows the user to say a limited number of U.S. cities and states, for example, "Boston, Massachusetts."
<?xml version= "1.0"?>
<grammar mode="voice"
root="root_rule"
tag-format="semantics/1.0"
version="1.0"
xml:lang="en-US"
xmlns="http://www.w3.org/2001/06/grammar">
<rule id="root_rule" scope="public">
<tag>cs = "";</tag>
<item>
<one-of>
<item>
<ruleref uri="#LIB_CITY_STATE"/>
<tag>cs = rules.latest();</tag>
</item>
</one-of>
<tag>out.loc = cs;</tag>
</item>
</rule>
<rule id="LIB_CITY_STATE" scope="private">
<one-of>
<item>
boston
</item>
<item>
massachusetts
<tag>out = "boston_ma";</tag>
</item>
<item>
fargo
</item>
<item>
north
</item>
<item>
dakota
<tag>out = "fargo_nd";</tag>
</item>
<item>
philadelphia
</item>
<item>
pennsylvania
<tag>out = "philadelphia_pa";</tag>
</item>
<item>
san
</item>
<item>
francisco
</item>
<item>
california
<tag>out = "san_francisco_ca";</tag>
</item>
<!-- and so on -->
</one-of>
</rule>
</grammar>
See Also
Understanding Grammars